From 1966535e1b08ed4bece2694faa791ca6c6f9a4df Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Tue, 11 Aug 2026 09:19:54 +0300
Subject: [PATCH 001/116] Serve the chartable gateway networks to the trade
 panel
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The connector dropdown is fed by `connected-exchanges`, which filters DEX out by
design and has other callers with a CEX-only contract. Rather than widen it, add
a sibling source of truth for the DEX half: `fetch_gateway_networks` asks Gateway
for its networks and keeps only the ones present in `NETWORK_TO_GECKO`.

That intersection is the point. `dex_candles.uses_gecko_candles` is an exact-match
test on the same dict, so offering only its members means a network can never be
selected and then produce an empty chart — `solana-devnet` and `base-sepolia`
would otherwise fall through to the Hummingbot candle path and 502.

Registered with `strict=True` so an unreachable gateway raises instead of being
cached as "this server has no DEX"; the route turns that into `{"networks": []}`
so the panel degrades to CEX-only while the next request still retries.

FEAT-041
---
 condor/fetchers/__init__.py            |   2 +
 condor/fetchers/connectors.py          |  42 ++++++
 condor/server_data_service.py          |  10 ++
 condor/web/routes/market.py            |  24 ++++
 tests/test_fetcher_gateway_networks.py | 184 +++++++++++++++++++++++++
 5 files changed, 262 insertions(+)
 create mode 100644 tests/test_fetcher_gateway_networks.py

diff --git a/condor/fetchers/__init__.py b/condor/fetchers/__init__.py
index 36e1adcc..6241959d 100644
--- a/condor/fetchers/__init__.py
+++ b/condor/fetchers/__init__.py
@@ -41,6 +41,7 @@
 from condor.fetchers.connectors import (
     fetch_connectors,
     fetch_available_cex_connectors,
+    fetch_gateway_networks,
     is_cex_connector,
 )
 from condor.fetchers.executors import (
@@ -74,6 +75,7 @@
     "fetch_trading_rules",
     "fetch_connectors",
     "fetch_available_cex_connectors",
+    "fetch_gateway_networks",
     "is_cex_connector",
     "fetch_executors",
     "fetch_all_executors",
diff --git a/condor/fetchers/connectors.py b/condor/fetchers/connectors.py
index 6d4cb144..0f4a975b 100644
--- a/condor/fetchers/connectors.py
+++ b/condor/fetchers/connectors.py
@@ -23,6 +23,48 @@ async def fetch_connectors(client, **_kw) -> List[str]:
     return await client.connectors.list_connectors()
 
 
+def _network_id(item) -> str:
+    """The network id of a ``list_networks`` entry, whatever shape it arrives in.
+
+    Gateway has returned plain strings and ``{"network_id": ...}`` / ``{"id": ...}``
+    dicts across versions; the Telegram swap flow normalizes the same three shapes
+    (``handlers/dex/swap.py``).
+    """
+    if isinstance(item, dict):
+        return str(item.get("network_id") or item.get("id") or item)
+    return str(item)
+
+
+async def fetch_gateway_networks(client, strict: bool = False, **_kw) -> List[str]:
+    """Gateway networks that Condor can chart (subset of ``NETWORK_TO_GECKO``).
+
+    The intersection is the point: a network is only offered to the trade panel if
+    ``dex_candles.uses_gecko_candles`` will answer for it, so selecting one can
+    never produce an empty chart. Do not widen this to every gateway network.
+
+    Args:
+        strict: Raise when the gateway request itself fails, instead of reporting
+            that no networks exist. Callers that cache the answer want the
+            distinction: an unreachable gateway is worth retrying, and must not be
+            cached as "this server has no DEX".
+    """
+    # Lazy, like condor.dex_candles.uses_gecko_candles — condor.fetchers must not
+    # import handlers at module scope.
+    from handlers.dex.pool_data import NETWORK_TO_GECKO
+
+    try:
+        response = await client.gateway.list_networks()
+        networks = (response or {}).get("networks") or []
+        return sorted(
+            {n for n in (_network_id(i) for i in networks) if n in NETWORK_TO_GECKO}
+        )
+    except Exception as e:
+        if strict:
+            raise
+        logger.error("Error fetching gateway networks: %s", e, exc_info=True)
+        return []
+
+
 async def fetch_available_cex_connectors(
     client, account_name: str = "master_account", strict: bool = False, **_kw
 ) -> List[str]:
diff --git a/condor/server_data_service.py b/condor/server_data_service.py
index 1d3cea7c..2d747fa9 100644
--- a/condor/server_data_service.py
+++ b/condor/server_data_service.py
@@ -45,6 +45,7 @@ class ServerDataType(Enum):
     CANDLE_CONNECTORS = "candle_connectors"
     SERVER_STATUS = "server_status"
     ALL_CONNECTORS = "all_connectors"
+    GATEWAY_NETWORKS = "gateway_networks"
     TICKERS = "tickers"
     TICKER_POOL = "ticker_pool"
 
@@ -83,6 +84,11 @@ class DataTypeDefaults:
     ServerDataType.ALL_CONNECTORS: DataTypeDefaults(
         interval=300, ttl=600, stale_threshold=30
     ),
+    # Gateway networks change ~never (a chain is added to the gateway config by
+    # hand), so a read is served from cache for half an hour.
+    ServerDataType.GATEWAY_NETWORKS: DataTypeDefaults(
+        interval=300, ttl=1800, stale_threshold=300
+    ),
     ServerDataType.TICKERS: DataTypeDefaults(interval=60, ttl=180, stale_threshold=30),
     # Whole-server ticker pool: one poll feeds every per-connector ticker view and
     # all currency conversion, so reads never hit the network.
@@ -848,6 +854,7 @@ def register_default_fetches() -> None:
         fetch_connectors,
         fetch_current_price,
         fetch_executors,
+        fetch_gateway_networks,
         fetch_portfolio,
         fetch_positions,
         fetch_server_status,
@@ -874,6 +881,9 @@ def register_default_fetches() -> None:
         ServerDataType.CONNECTORS, partial(fetch_available_cex_connectors, strict=True)
     )
     sds.register_fetch(ServerDataType.ALL_CONNECTORS, fetch_connectors)
+    sds.register_fetch(
+        ServerDataType.GATEWAY_NETWORKS, partial(fetch_gateway_networks, strict=True)
+    )
     sds.register_fetch(ServerDataType.BOTS_STATUS, fetch_bots_status)
     sds.register_fetch(ServerDataType.EXECUTORS, fetch_executors)
     sds.register_fetch(ServerDataType.BOT_RUNS, fetch_bot_runs)
diff --git a/condor/web/routes/market.py b/condor/web/routes/market.py
index 6c905862..428ec3ea 100644
--- a/condor/web/routes/market.py
+++ b/condor/web/routes/market.py
@@ -103,6 +103,30 @@ async def get_connected_exchanges(name: str, user: WebUser = Depends(get_current
     return result or []
 
 
+@router.get("/servers/{name}/market/gateway-networks")
+async def get_gateway_networks(name: str, user: WebUser = Depends(get_current_user)):
+    """Gateway networks the trade panel can offer (chartable DEX venues).
+
+    Answers ``{"networks": []}`` rather than a 502 when the gateway container is
+    down: the panel then simply shows no DEX. The fetcher runs ``strict=True``, so
+    the failure is never cached as an empty list and the next request retries.
+    """
+    cm = get_config_manager()
+    if not cm.has_server_access(user.id, name):
+        raise HTTPException(status_code=403, detail="No access")
+
+    from condor.server_data_service import ServerDataType, get_server_data_service
+
+    try:
+        result = await get_server_data_service().get_or_fetch(
+            name, ServerDataType.GATEWAY_NETWORKS
+        )
+    except Exception as e:
+        logger.warning("Gateway networks unavailable for %s: %s", name, e)
+        return {"networks": []}
+    return {"networks": result or []}
+
+
 @router.get("/servers/{name}/market/prices", response_model=MarketPriceResponse)
 async def get_price(
     name: str,
diff --git a/tests/test_fetcher_gateway_networks.py b/tests/test_fetcher_gateway_networks.py
new file mode 100644
index 00000000..a3dd7a6f
--- /dev/null
+++ b/tests/test_fetcher_gateway_networks.py
@@ -0,0 +1,184 @@
+"""Tests for FEAT-041: ``fetch_gateway_networks`` normalizes and gates the list.
+
+The trade panel learns "this connector is a DEX" from this fetcher's output, so
+two properties matter. First, gateway has returned ``list_networks`` entries as
+plain strings and as ``network_id`` / ``id`` dicts across versions, and all three
+have to reduce to the same id. Second, the result is intersected with
+``NETWORK_TO_GECKO``: a network Condor cannot chart must never be offered, or the
+user picks it and gets an empty chart (``dex_candles.uses_gecko_candles`` is an
+exact-match membership test on that same dict).
+"""
+
+import asyncio
+
+import pytest
+
+from condor.fetchers.connectors import fetch_gateway_networks
+
+
+class FakeClient:
+    """Client whose ``gateway.list_networks`` replays one scripted response."""
+
+    def __init__(self, response=None, error=None):
+        self.calls = 0
+        self.gateway = self._Gateway(self)
+        self._response = response
+        self._error = error
+
+    class _Gateway:
+        def __init__(self, outer):
+            self._outer = outer
+
+        async def list_networks(self):
+            self._outer.calls += 1
+            if self._outer._error is not None:
+                raise self._outer._error
+            return self._outer._response
+
+
+def _fetch(response, **kwargs):
+    return asyncio.run(fetch_gateway_networks(FakeClient(response), **kwargs))
+
+
+def test_accepts_plain_string_entries():
+    result = _fetch({"networks": ["solana-mainnet-beta", "base-mainnet"]})
+    assert result == ["base-mainnet", "solana-mainnet-beta"]
+
+
+def test_accepts_network_id_dicts():
+    result = _fetch({"networks": [{"network_id": "solana-mainnet-beta"}]})
+    assert result == ["solana-mainnet-beta"]
+
+
+def test_accepts_id_dicts():
+    result = _fetch({"networks": [{"id": "ethereum-mainnet"}]})
+    assert result == ["ethereum-mainnet"]
+
+
+def test_mixed_shapes_normalize_to_the_same_ids():
+    result = _fetch(
+        {
+            "networks": [
+                "solana-mainnet-beta",
+                {"network_id": "base-mainnet"},
+                {"id": "polygon-mainnet"},
+            ]
+        }
+    )
+    assert result == ["base-mainnet", "polygon-mainnet", "solana-mainnet-beta"]
+
+
+def test_drops_networks_condor_cannot_chart():
+    """A network absent from NETWORK_TO_GECKO would 502 on the candle path."""
+    result = _fetch(
+        {
+            "networks": [
+                "solana-mainnet-beta",
+                "solana-devnet",
+                "base-sepolia",
+                {"network_id": "not-a-chain"},
+            ]
+        }
+    )
+    assert result == ["solana-mainnet-beta"]
+
+
+def test_deduplicates_and_sorts():
+    result = _fetch(
+        {"networks": ["base-mainnet", {"network_id": "base-mainnet"}, "solana"]}
+    )
+    assert result == ["base-mainnet", "solana"]
+
+
+def test_tolerates_missing_and_empty_payloads():
+    assert _fetch({}) == []
+    assert _fetch({"networks": None}) == []
+    assert _fetch(None) == []
+
+
+def test_strict_reraises_so_the_failure_is_not_cached():
+    """A cached empty list would tell the panel "this server has no DEX"."""
+    client = FakeClient(error=RuntimeError("gateway down"))
+    with pytest.raises(RuntimeError):
+        asyncio.run(fetch_gateway_networks(client, strict=True))
+
+
+def test_non_strict_swallows_the_failure():
+    client = FakeClient(error=RuntimeError("gateway down"))
+    assert asyncio.run(fetch_gateway_networks(client)) == []
+
+
+# ── The REST route ────────────────────────────────────────────────────────────
+#
+# The panel merges this endpoint's answer into its connector dropdown, so a
+# server whose gateway container is down must degrade to "no DEX offered" rather
+# than break the whole selector with a 502.
+
+
+class _FakeSds:
+    """Stands in for ServerDataService.get_or_fetch."""
+
+    def __init__(self, value=None, error=None):
+        self.value = value
+        self.error = error
+        self.calls = 0
+
+    async def get_or_fetch(self, name, data_type, **params):
+        self.calls += 1
+        if self.error is not None:
+            raise self.error
+        return self.value
+
+
+def _call_route(monkeypatch, sds):
+    from condor import server_data_service
+    from condor.web.models import WebUser
+    from condor.web.routes.market import get_gateway_networks
+
+    monkeypatch.setattr(
+        server_data_service, "get_server_data_service", lambda: sds, raising=True
+    )
+
+    class _Cm:
+        def has_server_access(self, user_id, name):
+            return True
+
+    monkeypatch.setattr(
+        "condor.web.routes.market.get_config_manager", lambda: _Cm(), raising=True
+    )
+    return asyncio.run(get_gateway_networks("srv", user=WebUser(id=1, role="user")))
+
+
+def test_route_returns_the_networks(monkeypatch):
+    sds = _FakeSds(value=["base-mainnet", "solana-mainnet-beta"])
+    assert _call_route(monkeypatch, sds) == {
+        "networks": ["base-mainnet", "solana-mainnet-beta"]
+    }
+
+
+def test_route_returns_empty_list_when_the_gateway_is_down(monkeypatch):
+    """Not a 500: the panel just shows no DEX."""
+    sds = _FakeSds(error=RuntimeError("gateway down"))
+    assert _call_route(monkeypatch, sds) == {"networks": []}
+
+
+def test_route_normalizes_a_none_answer(monkeypatch):
+    assert _call_route(monkeypatch, _FakeSds(value=None)) == {"networks": []}
+
+
+def test_route_rejects_a_caller_without_access(monkeypatch):
+    from fastapi import HTTPException
+
+    from condor.web.models import WebUser
+    from condor.web.routes.market import get_gateway_networks
+
+    class _Cm:
+        def has_server_access(self, user_id, name):
+            return False
+
+    monkeypatch.setattr(
+        "condor.web.routes.market.get_config_manager", lambda: _Cm(), raising=True
+    )
+    with pytest.raises(HTTPException) as e:
+        asyncio.run(get_gateway_networks("srv", user=WebUser(id=1, role="user")))
+    assert e.value.status_code == 403

From 9dbc772e4cf78e858c3e0a1bb10638addd24d196 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Tue, 11 Aug 2026 09:20:14 +0300
Subject: [PATCH 002/116] Make DEX connectors first-class in the trade panel
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A gateway network can now be picked like `binance`: the chart draws from
GeckoTerminal, and the panel collapses to what the venue actually supports.

DEX-ness is learned as data. `connector-capabilities.ts` classifies by membership
in the server's gateway-network list rather than by name, because the backend
already carries four disagreeing connector predicates (`binance-smart-chain` is a
gateway network that `is_cex_connector` calls a CEX) and a frontend prefix list
would become the fifth and drift the same way. What stays a frontend literal is
the map from kind to capabilities — which tabs and strategies to render is a UI
decision, not a server fact.

For a DEX the panel now offers Order only (`lp` is already declared, and lights up
when FEAT-042 adds the tab), Market as the only execution strategy — there is no
resting book to post to — and hides Depth and Markets. The endpoints with no DEX
answer are switched off rather than left to 502: trading-rules, tickers, and
`/market/prices`, whose job is taken over by the last candle close from the store
TradeChart already streams. Pair entry becomes free text, since Gateway resolves
whatever pair it is given and there is no list to browse; a base58 mint is a valid
base, so normalization uppercases only the sides that are not addresses.

Two corrections are held until both halves of the dropdown have loaded. Judging a
persisted DEX network against the CEX list alone would bounce the selection back
to `connectors[0]` on every reload and reset its tab.

FEAT-041
---
 .../components/executor/OrderConfigPanel.tsx  |  30 ++-
 .../components/market/ExchangeSelector.tsx    |  84 ++++++--
 .../src/components/market/PairSelector.tsx    | 199 +++++++++++++++++-
 .../src/components/market/PriceTicker.tsx     |  10 +-
 frontend/src/components/market/useTickers.ts  |   7 +-
 frontend/src/lib/api.ts                       |   6 +
 frontend/src/lib/connector-capabilities.ts    |  74 +++++++
 frontend/src/pages/CreateExecutor.tsx         |  96 +++++++--
 8 files changed, 460 insertions(+), 46 deletions(-)
 create mode 100644 frontend/src/lib/connector-capabilities.ts

diff --git a/frontend/src/components/executor/OrderConfigPanel.tsx b/frontend/src/components/executor/OrderConfigPanel.tsx
index 338140e5..ada09094 100644
--- a/frontend/src/components/executor/OrderConfigPanel.tsx
+++ b/frontend/src/components/executor/OrderConfigPanel.tsx
@@ -1,4 +1,4 @@
-import { useMemo, useReducer } from "react";
+import { useEffect, useMemo, useReducer } from "react";
 import { Sparkles } from "lucide-react";
 
 import {
@@ -179,12 +179,32 @@ interface Props {
   currentPrice: number | null;
   isSpot?: boolean;
   pair?: string;
+  /**
+   * Execution strategies this venue allows. A gateway swap has no resting order
+   * book, so a DEX passes `["MARKET"]`. Defaults to all of them.
+   */
+  strategies?: string[];
 }
 
-export function OrderConfigPanel({ state, dispatch, validation, currentPrice, isSpot = false, pair }: Props) {
+export function OrderConfigPanel({ state, dispatch, validation, currentPrice, isSpot = false, pair, strategies }: Props) {
   const d = dispatch as FieldDispatch;
-  const needsPrice = state.execution_strategy === "LIMIT" || state.execution_strategy === "LIMIT_MAKER";
-  const isChaser = state.execution_strategy === "LIMIT_CHASER";
+  const options = strategies
+    ? STRATEGY_OPTIONS.filter((o) => strategies.includes(o.value))
+    : STRATEGY_OPTIONS;
+
+  // A strategy carried over from another venue (LIMIT on binance → solana) has to
+  // fall back, or the panel would submit a strategy the venue cannot honor.
+  const allowed = options.some((o) => o.value === state.execution_strategy);
+  useEffect(() => {
+    if (!allowed) {
+      d({ type: "SET_FIELD", field: "execution_strategy", value: "MARKET" });
+    }
+  }, [allowed]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const needsPrice =
+    allowed &&
+    (state.execution_strategy === "LIMIT" || state.execution_strategy === "LIMIT_MAKER");
+  const isChaser = allowed && state.execution_strategy === "LIMIT_CHASER";
 
   return (
     <div className="flex flex-col gap-4 overflow-y-auto p-3">
@@ -207,7 +227,7 @@ export function OrderConfigPanel({ state, dispatch, validation, currentPrice, is
           value={state.execution_strategy}
           field="execution_strategy"
           dispatch={d}
-          options={STRATEGY_OPTIONS}
+          options={options}
         />
         <LeverageField value={state.leverage} field="leverage" dispatch={d} isSpot={isSpot} />
         {!isSpot && (
diff --git a/frontend/src/components/market/ExchangeSelector.tsx b/frontend/src/components/market/ExchangeSelector.tsx
index 344b9d7d..6eac9957 100644
--- a/frontend/src/components/market/ExchangeSelector.tsx
+++ b/frontend/src/components/market/ExchangeSelector.tsx
@@ -1,14 +1,33 @@
-import { useEffect, useRef, useState } from "react";
+import { useEffect, useRef, useState, type ReactNode } from "react";
 import { ChevronDown } from "lucide-react";
 
 interface ExchangeSelectorProps {
   connectors: string[];
   value: string;
   onChange: (v: string) => void;
+  /** Connectors that are gateway DEX networks — listed under their own heading. */
+  dexConnectors?: string[];
+}
+
+/**
+ * Format a gateway network id the way the Telegram surface does, so the two read
+ * alike: `solana-mainnet-beta` → `Solana`, `solana-devnet` → `Solana Dev`.
+ * Mirrors `utils/telegram_formatters.format_network_display`.
+ */
+function formatNetwork(id: string) {
+  const parts = id.split("-");
+  const chain = parts[0].charAt(0).toUpperCase() + parts[0].slice(1);
+  if (parts.length === 1) return chain;
+  const net = parts[1];
+  if (net === "mainnet") return chain;
+  if (net === "devnet") return `${chain} Dev`;
+  if (net === "testnet") return `${chain} Test`;
+  return `${chain} ${net.slice(0, 4)}`;
 }
 
 // Format connector name for display (e.g. "binance_perpetual" -> "Binance Perp")
-function formatName(name: string) {
+function formatName(name: string, isDex = false) {
+  if (isDex) return formatNetwork(name);
   return name
     .replace(/_perpetual$/, " perp")
     .replace(/_/g, " ")
@@ -19,9 +38,13 @@ export function ExchangeSelector({
   connectors,
   value,
   onChange,
+  dexConnectors = [],
 }: ExchangeSelectorProps) {
   const [open, setOpen] = useState(false);
   const ref = useRef<HTMLDivElement>(null);
+  const dexSet = new Set(dexConnectors);
+  const cexList = connectors.filter((c) => !dexSet.has(c));
+  const dexList = connectors.filter((c) => dexSet.has(c));
 
   useEffect(() => {
     if (!open) return;
@@ -38,25 +61,21 @@ export function ExchangeSelector({
         onClick={() => setOpen(!open)}
         className="flex items-center gap-1.5 px-3 py-2.5 text-xs transition-colors hover:bg-[var(--color-surface-hover)]"
       >
-        <span className="font-medium text-[var(--color-primary)]">{formatName(value)}</span>
+        <span className="font-medium text-[var(--color-primary)]">{formatName(value, dexSet.has(value))}</span>
         <ChevronDown className={`h-3 w-3 text-[var(--color-text-muted)] transition-transform ${open ? "rotate-180" : ""}`} />
       </button>
 
       {open && (
         <div className="absolute left-0 top-full z-50 mt-px min-w-[180px] overflow-hidden rounded-b-lg border border-t-0 border-[var(--color-border)] bg-[var(--color-surface)] shadow-xl shadow-black/30">
           <div className="max-h-72 overflow-y-auto py-1">
-            {connectors.map((c) => (
-              <button
-                key={c}
-                onClick={() => { onChange(c); setOpen(false); }}
-                className={`flex w-full items-center px-3 py-1.5 text-left text-xs transition-colors ${
-                  c === value
-                    ? "bg-[var(--color-primary)]/10 font-medium text-[var(--color-primary)]"
-                    : "text-[var(--color-text)] hover:bg-[var(--color-surface-hover)]"
-                }`}
-              >
-                {formatName(c)}
-              </button>
+            {/* Headings only earn their space once there is more than one group. */}
+            {dexList.length > 0 && cexList.length > 0 && <GroupHeading>CEX</GroupHeading>}
+            {cexList.map((c) => (
+              <ConnectorOption key={c} name={c} value={value} onSelect={onChange} onClose={() => setOpen(false)} />
+            ))}
+            {dexList.length > 0 && cexList.length > 0 && <GroupHeading>DEX</GroupHeading>}
+            {dexList.map((c) => (
+              <ConnectorOption key={c} name={c} value={value} isDex onSelect={onChange} onClose={() => setOpen(false)} />
             ))}
           </div>
         </div>
@@ -64,3 +83,38 @@ export function ExchangeSelector({
     </div>
   );
 }
+
+function GroupHeading({ children }: { children: ReactNode }) {
+  return (
+    <p className="px-3 pb-0.5 pt-1.5 text-[9px] font-semibold uppercase tracking-wider text-[var(--color-text-muted)]">
+      {children}
+    </p>
+  );
+}
+
+function ConnectorOption({
+  name,
+  value,
+  isDex = false,
+  onSelect,
+  onClose,
+}: {
+  name: string;
+  value: string;
+  isDex?: boolean;
+  onSelect: (v: string) => void;
+  onClose: () => void;
+}) {
+  return (
+    <button
+      onClick={() => { onSelect(name); onClose(); }}
+      className={`flex w-full items-center px-3 py-1.5 text-left text-xs transition-colors ${
+        name === value
+          ? "bg-[var(--color-primary)]/10 font-medium text-[var(--color-primary)]"
+          : "text-[var(--color-text)] hover:bg-[var(--color-surface-hover)]"
+      }`}
+    >
+      {formatName(name, isDex)}
+    </button>
+  );
+}
diff --git a/frontend/src/components/market/PairSelector.tsx b/frontend/src/components/market/PairSelector.tsx
index 511ecc5b..9e6cb436 100644
--- a/frontend/src/components/market/PairSelector.tsx
+++ b/frontend/src/components/market/PairSelector.tsx
@@ -11,15 +11,65 @@ interface PairSelectorProps {
   connector: string;
   value: string;
   onChange: (pair: string) => void;
+  /**
+   * Whether `/market/trading-rules` answers for this connector. False for gateway
+   * DEX networks, which have no pair list at all — the selector becomes free-text
+   * entry backed by a recents list.
+   */
+  hasTradingRules?: boolean;
 }
 
 const MAX_VISIBLE = 50;
 
+/** Recently-entered DEX pairs, per network. */
+const DEX_PAIRS_KEY = "condor_dex_pairs";
+const MAX_DEX_RECENTS = 12;
+
+function loadDexRecents(connector: string): string[] {
+  try {
+    const raw = localStorage.getItem(`${DEX_PAIRS_KEY}:${connector}`);
+    const parsed = raw ? JSON.parse(raw) : [];
+    return Array.isArray(parsed) ? parsed.filter((p) => typeof p === "string") : [];
+  } catch {
+    return [];
+  }
+}
+
+// An EVM 0x-address or a base58 Solana pubkey. A DEX pair may carry a raw mint as
+// its base (`<mint>-SOL`) — base58 is case-sensitive, so such a side must survive
+// normalization untouched. Mirrors ADDRESS_RE in condor/dex_candles.py.
+const ADDRESS_RE = /^(0x[0-9a-fA-F]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$/;
+
+/** `sol-usdc` → `SOL-USDC`, leaving an address side exactly as typed. */
+function normalizeDexPair(input: string): string {
+  const trimmed = input.trim();
+  const dash = trimmed.lastIndexOf("-");
+  if (dash <= 0) return ADDRESS_RE.test(trimmed) ? trimmed : trimmed.toUpperCase();
+  const base = trimmed.slice(0, dash);
+  const quote = trimmed.slice(dash + 1);
+  const up = (side: string) =>
+    ADDRESS_RE.test(side) ? side : side.toUpperCase();
+  return `${up(base)}-${up(quote)}`;
+}
+
+function rememberDexPair(connector: string, pair: string) {
+  try {
+    const next = [pair, ...loadDexRecents(connector).filter((p) => p !== pair)].slice(
+      0,
+      MAX_DEX_RECENTS,
+    );
+    localStorage.setItem(`${DEX_PAIRS_KEY}:${connector}`, JSON.stringify(next));
+  } catch {
+    /* ok */
+  }
+}
+
 export function PairSelector({
   server,
   connector,
   value,
   onChange,
+  hasTradingRules = true,
 }: PairSelectorProps) {
   const [open, setOpen] = useState(false);
   const [search, setSearch] = useState("");
@@ -31,11 +81,15 @@ export function PairSelector({
   const { data: rulesData, isLoading } = useQuery({
     queryKey: ["trading-rules", server, connector],
     queryFn: () => api.getTradingRules(server, connector),
-    enabled: !!server && !!connector,
+    enabled: !!server && !!connector && hasTradingRules,
     staleTime: 5 * 60 * 1000,
   });
 
-  const { byPair, rankByPair, hasTickers } = useTickers(server, connector);
+  const { byPair, rankByPair, hasTickers } = useTickers(
+    server,
+    connector,
+    hasTradingRules,
+  );
 
   // Tradable pairs come from trading rules; tickers only decide the order and the
   // volume badge, so the selector still works on servers without /market-data/tickers.
@@ -121,6 +175,11 @@ export function PairSelector({
     }
   };
 
+  // A gateway network has no pair list to offer: the user types the pair.
+  if (!hasTradingRules) {
+    return <DexPairEntry connector={connector} value={value} onChange={onChange} />;
+  }
+
   // Fallback to plain text input if no rules available
   if (!isLoading && pairs.length === 0) {
     return (
@@ -239,12 +298,144 @@ export function PairSelector({
   );
 }
 
+/**
+ * Pair entry for a gateway DEX network.
+ *
+ * There is no tradable-pair list to browse — Gateway resolves whatever the user
+ * names — so this is free-text `BASE-QUOTE` entry, the same grammar the Telegram
+ * DEX flow uses, with the pairs already tried on this network kept as shortcuts.
+ * A raw mint address is a valid base (`<mint>-SOL`); `_resolve_pool` expects
+ * exactly that shape and `PairLabel` renders it back as a ticker.
+ */
+function DexPairEntry({
+  connector,
+  value,
+  onChange,
+}: {
+  connector: string;
+  value: string;
+  onChange: (pair: string) => void;
+}) {
+  const [open, setOpen] = useState(false);
+  const [draft, setDraft] = useState("");
+  const containerRef = useRef<HTMLDivElement>(null);
+  const inputRef = useRef<HTMLInputElement>(null);
+  const [recents, setRecents] = useState<string[]>(() => loadDexRecents(connector));
+
+  useEffect(() => {
+    setRecents(loadDexRecents(connector));
+  }, [connector]);
+
+  useEffect(() => {
+    if (!open) return;
+    const handler = (e: MouseEvent) => {
+      if (containerRef.current && !containerRef.current.contains(e.target as Node)) {
+        setOpen(false);
+      }
+    };
+    document.addEventListener("mousedown", handler);
+    return () => document.removeEventListener("mousedown", handler);
+  }, [open]);
+
+  useEffect(() => {
+    if (open) {
+      setDraft(value);
+      inputRef.current?.focus();
+      inputRef.current?.select();
+    }
+  }, [open, value]);
+
+  const commit = (raw: string) => {
+    const pair = normalizeDexPair(raw);
+    if (!pair) return;
+    rememberDexPair(connector, pair);
+    setRecents(loadDexRecents(connector));
+    onChange(pair);
+    setOpen(false);
+  };
+
+  return (
+    <div ref={containerRef} className="relative">
+      <button
+        onClick={() => setOpen(!open)}
+        className="group flex items-center gap-1 px-4 py-2.5 transition-colors hover:bg-[var(--color-surface-hover)] focus:outline-none focus-visible:ring-1 focus-visible:ring-inset focus-visible:ring-[var(--color-primary)]"
+      >
+        {value ? (
+          <span className="max-w-[13rem] truncate text-[15px] font-semibold text-[var(--color-text)]" title={value}>
+            {value}
+          </span>
+        ) : (
+          <span className="text-sm text-[var(--color-text-muted)]">Enter pair</span>
+        )}
+        <ChevronDown className="ml-1 h-3.5 w-3.5 text-[var(--color-text-muted)] transition-transform group-hover:text-[var(--color-text)]" />
+      </button>
+
+      {open && (
+        <div className="absolute left-0 top-full z-50 mt-1 w-80 rounded-lg border border-[var(--color-border)] bg-[var(--color-surface)] shadow-xl shadow-black/40">
+          <div className="flex items-center gap-2 border-b border-[var(--color-border)] px-3 py-2">
+            <input
+              ref={inputRef}
+              type="text"
+              value={draft}
+              onChange={(e) => setDraft(e.target.value)}
+              onKeyDown={(e) => {
+                if (e.key === "Enter") {
+                  e.preventDefault();
+                  commit(draft);
+                } else if (e.key === "Escape") {
+                  setOpen(false);
+                }
+              }}
+              placeholder="SOL-USDC or <mint>-SOL"
+              spellCheck={false}
+              autoComplete="off"
+              className="flex-1 bg-transparent text-sm text-[var(--color-text)] placeholder:text-[var(--color-text-muted)] focus:outline-none"
+            />
+            <button
+              onClick={() => commit(draft)}
+              disabled={!draft.trim()}
+              className="shrink-0 rounded border border-[var(--color-border)] px-2 py-0.5 text-[10px] text-[var(--color-text-muted)] transition-colors hover:bg-[var(--color-surface-hover)] hover:text-[var(--color-text)] disabled:opacity-40"
+            >
+              Set
+            </button>
+          </div>
+
+          {recents.length > 0 && (
+            <div className="max-h-64 overflow-y-auto py-1">
+              <p className="px-3 pb-0.5 pt-1 text-[9px] font-semibold uppercase tracking-wider text-[var(--color-text-muted)]">
+                Recent
+              </p>
+              {recents.map((p) => (
+                <button
+                  key={p}
+                  onClick={() => commit(p)}
+                  className={`flex w-full items-center px-3 py-1.5 text-left text-sm ${
+                    p === value
+                      ? "text-[var(--color-primary)]"
+                      : "text-[var(--color-text)] hover:bg-[var(--color-surface-hover)]"
+                  }`}
+                >
+                  <span className="truncate" title={p}>{p}</span>
+                </button>
+              ))}
+            </div>
+          )}
+
+          <p className="border-t border-[var(--color-border)] px-3 py-1.5 text-[10px] text-[var(--color-text-muted)]">
+            Gateway resolves the pool from the pair — a token mint works as the base.
+          </p>
+        </div>
+      )}
+    </div>
+  );
+}
+
 // Export the rules map hook for TradingRulesInfo
-export function useTradingRules(server: string, connector: string) {
+export function useTradingRules(server: string, connector: string, enabled = true) {
   const { data } = useQuery({
     queryKey: ["trading-rules", server, connector],
     queryFn: () => api.getTradingRules(server, connector),
-    enabled: !!server && !!connector,
+    enabled: !!server && !!connector && enabled,
     staleTime: 5 * 60 * 1000,
   });
   return data;
diff --git a/frontend/src/components/market/PriceTicker.tsx b/frontend/src/components/market/PriceTicker.tsx
index f09f4188..1fcb38eb 100644
--- a/frontend/src/components/market/PriceTicker.tsx
+++ b/frontend/src/components/market/PriceTicker.tsx
@@ -10,9 +10,15 @@ interface PriceTickerProps {
   pair: string;
   /** Candle interval to track — defaults to "1m" for most responsive updates */
   interval?: string;
+  /**
+   * Whether `/market/prices` answers for this connector. False for gateway DEX
+   * networks, where the candle close is the only price and the REST call would
+   * only 502; bid/ask/spread are then simply absent.
+   */
+  hasRestPrice?: boolean;
 }
 
-export function PriceTicker({ server, connector, pair, interval = "1m" }: PriceTickerProps) {
+export function PriceTicker({ server, connector, pair, interval = "1m", hasRestPrice = true }: PriceTickerProps) {
   const prevPriceRef = useRef<number>(0);
   const [candlePrice, setCandlePrice] = useState<number>(0);
 
@@ -47,7 +53,7 @@ export function PriceTicker({ server, connector, pair, interval = "1m" }: PriceT
   const { data: price } = useQuery({
     queryKey: ["price", server, connector, pair],
     queryFn: () => api.getPrice(server, connector, pair),
-    enabled: !!server && !!connector && !!pair,
+    enabled: !!server && !!connector && !!pair && hasRestPrice,
     refetchInterval: 15_000,
   });
 
diff --git a/frontend/src/components/market/useTickers.ts b/frontend/src/components/market/useTickers.ts
index 8dacb26e..1d6ec6e1 100644
--- a/frontend/src/components/market/useTickers.ts
+++ b/frontend/src/components/market/useTickers.ts
@@ -6,12 +6,15 @@ import { api, type Ticker } from "@/lib/api";
 /**
  * 24h tickers for a connector, already sorted by USD volume (highest first) by the
  * backend. Shared by PairSelector and MarketsPanel so both hit one cached query.
+ *
+ * @param enabled Pass false for venues with no ticker endpoint (gateway DEX
+ *   networks), where the request would only 502.
  */
-export function useTickers(server: string, connector: string) {
+export function useTickers(server: string, connector: string, enabled = true) {
   const { data, isLoading, isFetching } = useQuery({
     queryKey: ["tickers", server, connector],
     queryFn: () => api.getTickers(server, connector),
-    enabled: !!server && !!connector,
+    enabled: !!server && !!connector && enabled,
     staleTime: 60 * 1000,
     refetchInterval: 60 * 1000,
   });
diff --git a/frontend/src/lib/api.ts b/frontend/src/lib/api.ts
index 409922fc..0d9d9bb4 100644
--- a/frontend/src/lib/api.ts
+++ b/frontend/src/lib/api.ts
@@ -1179,6 +1179,12 @@ export const api = {
   getConnectedExchanges: (server: string) =>
     apiFetch<string[]>(`/api/v1/servers/${encodeURIComponent(server)}/market/connected-exchanges`),
 
+  /** Chartable gateway DEX networks — the trade panel's DEX half of the dropdown. */
+  getGatewayNetworks: (server: string) =>
+    apiFetch<{ networks: string[] }>(
+      `/api/v1/servers/${encodeURIComponent(server)}/market/gateway-networks`,
+    ).then((r) => r.networks),
+
   getPrice: (server: string, connector: string, pair: string) =>
     apiFetch<MarketPrice>(
       `/api/v1/servers/${encodeURIComponent(server)}/market/prices?connector=${encodeURIComponent(connector)}&trading_pair=${encodeURIComponent(pair)}`,
diff --git a/frontend/src/lib/connector-capabilities.ts b/frontend/src/lib/connector-capabilities.ts
new file mode 100644
index 00000000..4998f770
--- /dev/null
+++ b/frontend/src/lib/connector-capabilities.ts
@@ -0,0 +1,74 @@
+import type { ExecutorType } from "@/components/executor/types";
+
+/**
+ * What a connector can do in the trade panel.
+ *
+ * DEX-ness is **not** guessed from the name here. The backend already carries four
+ * mutually inconsistent connector predicates (prefix lists, substring lists, live
+ * gateway lookups) that disagree on cases like `binance-smart-chain`; a fifth one
+ * in the frontend would silently drift the same way, and the symptom would be "the
+ * chart is blank and Grid is offered on a DEX". Instead the server tells us which
+ * connectors are gateway networks (`GET /market/gateway-networks`, already
+ * intersected with the set Condor can chart) and this module classifies by
+ * membership in that list.
+ *
+ * The executor-type and strategy maps below *are* frontend literals, deliberately:
+ * they are a UI product decision about which tabs and options to render, not a
+ * server fact, and they are changed by whoever changes the tabs.
+ */
+
+export type ConnectorKind = "cex" | "dex";
+
+/**
+ * An executor type a *venue* supports, which is not yet the same set as the tabs
+ * the panel implements: `"lp"` has no entry in `TYPE_TABS` until FEAT-042 adds
+ * one. Keeping it out of `ExecutorType` leaves that union meaning "a tab this
+ * panel can render", so the exhaustive switches over it stay exhaustive.
+ */
+export type SupportedExecutorType = ExecutorType | "lp";
+
+export interface ConnectorCapabilities {
+  kind: ConnectorKind;
+  /** Executor types this venue supports. */
+  executorTypes: SupportedExecutorType[];
+  /** Allowed `execution_strategy` values (subset of OrderConfigPanel's options). */
+  orderStrategies: string[];
+  /** Whether `/market/order-book` and `/market/tickers` answer — depth + markets tabs. */
+  hasOrderBook: boolean;
+  /** Whether `/market/trading-rules` answers — pair list + price precision. */
+  hasTradingRules: boolean;
+}
+
+const CEX_CAPABILITIES: ConnectorCapabilities = {
+  kind: "cex",
+  executorTypes: ["order", "position", "grid", "dca"],
+  orderStrategies: ["MARKET", "LIMIT", "LIMIT_MAKER", "LIMIT_CHASER"],
+  hasOrderBook: true,
+  hasTradingRules: true,
+};
+
+// A gateway swap has no resting order book to post to, so MARKET is the only
+// execution strategy that means anything. `lp` is listed from day one; the tab
+// list filters against TYPE_TABS, so it simply finds no entry until FEAT-042
+// adds one.
+const DEX_CAPABILITIES: ConnectorCapabilities = {
+  kind: "dex",
+  executorTypes: ["order", "lp"],
+  orderStrategies: ["MARKET"],
+  hasOrderBook: false,
+  hasTradingRules: false,
+};
+
+/**
+ * Capabilities of `connector`, given the gateway networks this server exposes.
+ *
+ * An unknown connector — or any connector at all before the gateway-networks
+ * query resolves — is treated as a CEX, which is the status quo behavior for
+ * every venue the panel handled before DEX support existed.
+ */
+export function connectorCapabilities(
+  connector: string,
+  gatewayNetworks: string[],
+): ConnectorCapabilities {
+  return gatewayNetworks.includes(connector) ? DEX_CAPABILITIES : CEX_CAPABILITIES;
+}
diff --git a/frontend/src/pages/CreateExecutor.tsx b/frontend/src/pages/CreateExecutor.tsx
index 9cf3a6e4..51e925a6 100644
--- a/frontend/src/pages/CreateExecutor.tsx
+++ b/frontend/src/pages/CreateExecutor.tsx
@@ -29,6 +29,7 @@ import { PositionConfigPanel, usePositionConfig } from "@/components/executor/Po
 import { OrderConfigPanel, useOrderConfig } from "@/components/executor/OrderConfigPanel";
 import { DCAConfigPanel, useDCAConfig } from "@/components/executor/DCAConfigPanel";
 import { TradeBottomPane } from "@/components/trade/TradeBottomPane";
+import { useCandleStore } from "@/hooks/useCandleStore";
 import { useServer } from "@/hooks/useServer";
 import { useCondorWebSocket } from "@/hooks/useWebSocket";
 import { useMainControllerData } from "@/hooks/useMainControllerData";
@@ -36,6 +37,7 @@ import { useRates } from "@/hooks/useRates";
 import { useResizeDrag } from "@/hooks/useResizeDrag";
 import { api } from "@/lib/api";
 import { candleStore } from "@/lib/candle-store";
+import { connectorCapabilities } from "@/lib/connector-capabilities";
 import type { ExecutorType } from "@/components/executor/types";
 import {
   gridReducer,
@@ -141,12 +143,38 @@ export function CreateExecutor() {
     cursor: "row-resize",
   });
 
-  const { data: connectors = [] } = useQuery({
+  const { data: connectors = [], isPending: connectorsPending } = useQuery({
     queryKey: ["connected-exchanges", server],
     queryFn: () => api.getConnectedExchanges(server!),
     enabled: !!server,
   });
 
+  // `connected-exchanges` is CEX-only by contract and has other callers, so the
+  // gateway networks arrive on their own endpoint and the panel merges the two.
+  const { data: gatewayNetworks = [], isPending: networksPending } = useQuery({
+    queryKey: ["gateway-networks", server],
+    queryFn: () => api.getGatewayNetworks(server!),
+    enabled: !!server,
+    staleTime: 5 * 60 * 1000,
+  });
+
+  // Both halves of the dropdown have to be in before the panel may *correct* a
+  // selection: judging a persisted DEX network against the CEX list alone would
+  // bounce it to connectors[0] on every reload, and switch its tab to Order.
+  const listsReady = !!server && !connectorsPending && !networksPending;
+
+  // Deduplicated: `is_cex_connector` still calls `binance-smart-chain` a CEX, so a
+  // network can legitimately appear in both lists.
+  const allConnectors = useMemo(
+    () => [...new Set([...connectors, ...gatewayNetworks])],
+    [connectors, gatewayNetworks],
+  );
+
+  const caps = useMemo(
+    () => connectorCapabilities(connector, gatewayNetworks),
+    [connector, gatewayNetworks],
+  );
+
   // WS for executor data (candle streams are managed by candleStore)
   const wsChannels = useMemo(
     () => server ? [`executors:${server}`] : [],
@@ -158,7 +186,7 @@ export function CreateExecutor() {
   const { executors: mainExecutors, overlays: mainOverlays, positions: mainPositions, isLoadingPositions } =
     useMainControllerData(server, connector, pair);
 
-  const rulesData = useTradingRules(server ?? "", connector);
+  const rulesData = useTradingRules(server ?? "", connector, caps.hasTradingRules);
 
   // Currency conversion for chart tooltip values
   const quoteCurrency = pair.split("-")[1] || "USDT";
@@ -181,12 +209,21 @@ export function CreateExecutor() {
     setSelectedExecutorId(null);
   }, [connector, pair]);
 
-  // Sync connector to filtered list
+  // Sync connector to the merged list. Validating against the CEX list alone would
+  // bounce a selected DEX network back to connectors[0] on every render.
+  useEffect(() => {
+    if (listsReady && allConnectors.length && !allConnectors.includes(connector)) {
+      gridDispatch({ type: "SET_CONNECTOR", value: allConnectors[0] });
+    }
+  }, [listsReady, allConnectors, connector]);
+
+  // Executor types the venue does not support cannot stay selected (Grid on a CEX
+  // → pick a DEX → land on Order).
   useEffect(() => {
-    if (connectors.length && !connectors.includes(connector)) {
-      gridDispatch({ type: "SET_CONNECTOR", value: connectors[0] });
+    if (listsReady && !caps.executorTypes.includes(executorType)) {
+      handleTypeChange("order");
     }
-  }, [connectors, connector]);
+  }, [listsReady, caps, executorType]); // eslint-disable-line react-hooks/exhaustive-deps
 
   // Reset pair when connector changes
   useEffect(() => {
@@ -212,15 +249,28 @@ export function CreateExecutor() {
     dcaConfig.dispatch({ type: "SET_PAIR", value: pair });
   }, [pair]); // eslint-disable-line react-hooks/exhaustive-deps
 
-  // Current price
+  // Current price. /market/prices is a Hummingbot API call with no DEX answer, so a
+  // gateway network reads the last close off the candle stream instead. The store is
+  // a singleton over one shared channel and TradeChart already subscribes with these
+  // exact arguments, so this costs no extra connection.
   const { data: priceData } = useQuery({
     queryKey: ["price", server, connector, pair],
     queryFn: () => api.getPrice(server!, connector, pair),
-    enabled: !!server && !!connector && !!pair,
+    enabled: !!server && !!connector && !!pair && caps.kind === "cex",
     refetchInterval: 5000,
   });
 
-  const currentPrice = priceData?.mid_price ?? null;
+  const { candles: sharedCandles } = useCandleStore(
+    server ?? null,
+    connector,
+    pair,
+    gridState.interval,
+  );
+
+  const currentPrice =
+    caps.kind === "dex"
+      ? (sharedCandles[sharedCandles.length - 1]?.close ?? null)
+      : (priceData?.mid_price ?? null);
 
   // Price precision
   const pricePrecision = useMemo(() => {
@@ -232,6 +282,10 @@ export function CreateExecutor() {
     return Math.max(0, Math.ceil(-Math.log10(inc)));
   }, [rulesData, pair]);
 
+  // Depth and Markets have no DEX answer. Derived rather than reset in an effect, so
+  // a CEX selection is remembered and comes back when the user returns to a CEX.
+  const activePanel = caps.hasOrderBook ? rightPanel : "config";
+
   // ── Active config derived values ──
   const activeValidation = useMemo(() => {
     switch (executorType) {
@@ -372,19 +426,21 @@ export function CreateExecutor() {
             connector={connector}
             value={pair}
             onChange={(v) => gridDispatch({ type: "SET_PAIR", value: v })}
+            hasTradingRules={caps.hasTradingRules}
           />
           <div className="relative border-l border-[var(--color-border)]">
             <ExchangeSelector
-              connectors={connectors}
+              connectors={allConnectors}
               value={connector}
               onChange={(v) => gridDispatch({ type: "SET_CONNECTOR", value: v })}
+              dexConnectors={gatewayNetworks}
             />
           </div>
         </div>
 
         {/* Price ticker */}
         <div className="flex flex-1 items-center px-4 py-2">
-          <PriceTicker server={server} connector={connector} pair={pair} />
+          <PriceTicker server={server} connector={connector} pair={pair} hasRestPrice={caps.hasOrderBook} />
         </div>
 
         {/* Interval + Range */}
@@ -505,7 +561,7 @@ export function CreateExecutor() {
             <button
               onClick={() => setRightPanel("config")}
               className={`flex flex-1 items-center justify-center gap-1.5 px-2 py-2 text-[11px] font-medium transition-colors ${
-                rightPanel === "config"
+                activePanel === "config"
                   ? "border-b-2 border-[var(--color-primary)] text-[var(--color-primary)]"
                   : "text-[var(--color-text-muted)] hover:bg-[var(--color-surface-hover)] hover:text-[var(--color-text)]"
               }`}
@@ -513,10 +569,11 @@ export function CreateExecutor() {
               <Settings2 className="h-3.5 w-3.5" />
               Execute
             </button>
+            {caps.hasOrderBook && (
             <button
               onClick={() => setRightPanel("depth")}
               className={`flex flex-1 items-center justify-center gap-1.5 px-2 py-2 text-[11px] font-medium transition-colors ${
-                rightPanel === "depth"
+                activePanel === "depth"
                   ? "border-b-2 border-[var(--color-primary)] text-[var(--color-primary)]"
                   : "text-[var(--color-text-muted)] hover:bg-[var(--color-surface-hover)] hover:text-[var(--color-text)]"
               }`}
@@ -524,10 +581,12 @@ export function CreateExecutor() {
               <BarChart3 className="h-3.5 w-3.5" />
               Data
             </button>
+            )}
+            {caps.hasOrderBook && (
             <button
               onClick={() => setRightPanel("markets")}
               className={`flex flex-1 items-center justify-center gap-1.5 px-2 py-2 text-[11px] font-medium transition-colors ${
-                rightPanel === "markets"
+                activePanel === "markets"
                   ? "border-b-2 border-[var(--color-primary)] text-[var(--color-primary)]"
                   : "text-[var(--color-text-muted)] hover:bg-[var(--color-surface-hover)] hover:text-[var(--color-text)]"
               }`}
@@ -535,14 +594,15 @@ export function CreateExecutor() {
               <List className="h-3.5 w-3.5" />
               Markets
             </button>
+            )}
           </div>
 
-          {rightPanel === "config" ? (
+          {activePanel === "config" ? (
             <>
               {/* Type Tabs */}
               <div className="border-b border-[var(--color-border)]">
                 <div className="flex">
-                  {TYPE_TABS.map((tab) => (
+                  {TYPE_TABS.filter((t) => caps.executorTypes.includes(t.value)).map((tab) => (
                     <button
                       key={tab.value}
                       onClick={() => handleTypeChange(tab.value)}
@@ -568,7 +628,7 @@ export function CreateExecutor() {
                   <PositionConfigPanel state={positionConfig.state} dispatch={positionConfig.dispatch} validation={positionConfig.validation} currentPrice={currentPrice} isSpot={isSpot} pair={pair} />
                 )}
                 {executorType === "order" && (
-                  <OrderConfigPanel state={orderConfig.state} dispatch={orderConfig.dispatch} validation={orderConfig.validation} currentPrice={currentPrice} isSpot={isSpot} pair={pair} />
+                  <OrderConfigPanel state={orderConfig.state} dispatch={orderConfig.dispatch} validation={orderConfig.validation} currentPrice={currentPrice} isSpot={isSpot} pair={pair} strategies={caps.orderStrategies} />
                 )}
                 {executorType === "dca" && (
                   <DCAConfigPanel state={dcaConfig.state} dispatch={dcaConfig.dispatch} validation={dcaConfig.validation} currentPrice={currentPrice} isSpot={isSpot} pair={pair} />
@@ -596,7 +656,7 @@ export function CreateExecutor() {
                 </button>
               </div>
             </>
-          ) : rightPanel === "depth" ? (
+          ) : activePanel === "depth" ? (
             <MarketDepthPanel server={server} connector={connector} pair={pair} />
           ) : (
             <MarketsPanel

From 58d2bb724d8fdebe27177ccd7e68c19f75794251 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Tue, 11 Aug 2026 09:37:53 +0300
Subject: [PATCH 003/116] Resolve the pool a DEX pair trades in, and whether it
 can take an LP position
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The LP panel has to name a pool and a `dex/clmm` provider before it can build an
`lp_executor` config, and the chart already picks a pool for every DEX candle it
draws. Resolving them by two mechanisms would let the panel and the chart disagree
silently, so `fetch_token_top_pool` — which threw away everything but the address
because that is all the candle path needs — becomes the address form of
`fetch_token_top_pool_info`, sharing its cache entry. Same for the symbol-search
branch. The candle path calls the same functions and cannot tell the difference.

`lp_provider_for_dex` refuses to guess, because a wrong provider is not a wrong
label but a failed executor. It matches on (brand, product) rather than brand,
since GeckoTerminal's dex ids are not a stable vocabulary: Uniswap V3 arrives as
`uniswap_v3`, `uniswap-v3-base` and `uniswap_v3_arbitrum`, while
`uniswap-v4-ethereum`, `meteora-damm-v2` and plain `raydium` share a brand with a
supported venue but not its position model. Every id in the test table was
observed coming back from the live API.

`can_fetch_liquidity` is deliberately not the gate the design named: it compares a
gecko network id against a chain *name*, so it is false for every Uniswap pool on
Ethereum, and it has no notion of Uniswap on Arbitrum or Base at all. It keeps
answering its own question (can Telegram draw the liquidity-bin chart) untouched.

`GET /market/dex-pool` reports the dead end rather than hiding it — a 200 with
`lp_supported: false` when the deepest pool is a router or plain AMM, which is the
common case for pairs like JUP-USDC. The panel's answer is to ask for a pool
address by hand, and that is a state to render, not an error to handle.

FEAT-042
---
 condor/web/routes/market.py       |  67 +++++
 handlers/dex/pool_data.py         | 251 ++++++++++++++--
 tests/test_dex_pool_resolution.py | 475 ++++++++++++++++++++++++++++++
 3 files changed, 762 insertions(+), 31 deletions(-)
 create mode 100644 tests/test_dex_pool_resolution.py

diff --git a/condor/web/routes/market.py b/condor/web/routes/market.py
index 428ec3ea..a3c2def6 100644
--- a/condor/web/routes/market.py
+++ b/condor/web/routes/market.py
@@ -127,6 +127,73 @@ async def get_gateway_networks(name: str, user: WebUser = Depends(get_current_us
     return {"networks": result or []}
 
 
+_NO_POOL = {
+    "pool_address": None,
+    "dex_id": None,
+    "lp_provider": None,
+    "lp_supported": False,
+    "current_price": None,
+    "base_symbol": None,
+    "quote_symbol": None,
+}
+
+
+@router.get("/servers/{name}/market/dex-pool")
+async def get_dex_pool(
+    name: str,
+    connector: str = Query(
+        ..., description="Gateway network, e.g. solana-mainnet-beta"
+    ),
+    trading_pair: str = Query(...),
+    user: WebUser = Depends(get_current_user),
+):
+    """The pool a DEX pair trades in, and whether an LP position can be opened in it.
+
+    Makes explicit the choice the chart already makes implicitly: candles for a DEX
+    pair come from whichever pool ``resolve_pool_info`` picks, and the LP panel has
+    to name that same pool. ``lp_provider`` is the ``dex/trading_type`` string an
+    ``lp_executor`` requires, and is ``None`` with ``lp_supported: false`` whenever
+    the deepest pool is not on one of the five CLMM venues — a router pool, a plain
+    AMM, or Uniswap v4. That is a 200, not an error: the panel's answer to it is to
+    ask for a pool address by hand, which is a state to render rather than a failure
+    to handle.
+    """
+    cm = get_config_manager()
+    if not cm.has_server_access(user.id, name):
+        raise HTTPException(status_code=403, detail="No access")
+
+    from handlers.dex.pool_data import lp_provider_for_dex, resolve_pool_info
+
+    try:
+        info = await resolve_pool_info(connector, trading_pair)
+    except Exception as e:
+        logger.warning(
+            "Pool resolution failed connector=%s pair=%s: %s",
+            connector,
+            trading_pair,
+            e,
+        )
+        return dict(_NO_POOL)
+
+    address = str((info or {}).get("address") or "")
+    # A resolved address that does not look like one would be handed straight back
+    # to /market/candles and the executor config, so it is refused here instead.
+    if not info or not _POOL_ADDRESS_RE.match(address):
+        return dict(_NO_POOL)
+
+    dex_id = str(info.get("dex_id") or "")
+    provider = lp_provider_for_dex(dex_id, connector)
+    return {
+        "pool_address": address,
+        "dex_id": dex_id or None,
+        "lp_provider": provider,
+        "lp_supported": provider is not None,
+        "current_price": info.get("current_price"),
+        "base_symbol": info.get("base_symbol"),
+        "quote_symbol": info.get("quote_symbol"),
+    }
+
+
 @router.get("/servers/{name}/market/prices", response_model=MarketPriceResponse)
 async def get_price(
     name: str,
diff --git a/handlers/dex/pool_data.py b/handlers/dex/pool_data.py
index 80d522eb..3c31ba64 100644
--- a/handlers/dex/pool_data.py
+++ b/handlers/dex/pool_data.py
@@ -14,6 +14,7 @@
 
 import logging
 import math
+import re
 import time
 from typing import Any, Dict, List, Optional, Tuple
 
@@ -25,6 +26,39 @@
 
 logger = logging.getLogger(__name__)
 
+# CLMM venues an ``lp_executor`` can open a position on: (brand, the qualifiers its
+# GeckoTerminal dex id must carry, the gecko networks it exists on). Deliberately
+# separate from LIQUIDITY_SUPPORTED_DEXES below, which answers a different question
+# (can Condor draw Telegram's liquidity-bin chart) and compares gecko network ids
+# against chain *names*, so it is false for every Uniswap pool on Ethereum.
+_CLMM_VENUES: Tuple[Tuple[str, List[str], set], ...] = (
+    # Gecko's `meteora` is DLMM and `orca` is Whirlpools — both already the
+    # concentrated product, so any qualifier means a different pool type.
+    ("meteora", [], {"solana"}),
+    ("orca", [], {"solana"}),
+    # Plain `raydium` is the constant-product AMM v4; only `raydium-clmm` is CLMM.
+    ("raydium", ["clmm"], {"solana"}),
+    ("uniswap", ["v3"], {"eth", "arbitrum", "base", "polygon_pos", "optimism", "bsc"}),
+    ("pancakeswap", ["v3"], {"bsc", "eth", "base", "arbitrum"}),
+)
+
+# Chain suffixes gecko tacks onto a dex id (`uniswap-v3-base`). They say where the
+# venue is, not which product it is, so they are dropped before matching.
+_CHAIN_TOKENS = {
+    "solana",
+    "ethereum",
+    "eth",
+    "base",
+    "arbitrum",
+    "bsc",
+    "polygon",
+    "pos",
+    "optimism",
+    "avalanche",
+}
+
+_DEX_ID_SPLIT_RE = re.compile(r"[-_]")
+
 # Supported DEXes for liquidity data (via gateway CLMM)
 LIQUIDITY_SUPPORTED_DEXES = {
     "meteora": "solana",
@@ -171,8 +205,14 @@ def _gecko_client() -> GeckoTerminalAsyncClient:
 # cannot grow them without limit.
 _TOKEN_CACHE_MAX = 512
 _token_symbol_cache: Dict[Tuple[str, str], Tuple[float, str]] = {}
-_token_pool_cache: Dict[Tuple[str, str, str], Tuple[float, str]] = {}
-_pair_pool_cache: Dict[Tuple[str, str, str], Tuple[float, Tuple[str, bool]]] = {}
+# Both hold normalized pool dicts, and an empty dict for "asked, there is no such
+# pool" — a real answer worth caching, unlike a failed lookup, which is not cached
+# at all. The address-only forms (fetch_token_top_pool, fetch_pair_top_pool) read
+# these same entries.
+_token_pool_cache: Dict[Tuple[str, str, str], Tuple[float, Dict[str, Any]]] = {}
+_pair_pool_cache: Dict[
+    Tuple[str, str, str], Tuple[float, Tuple[Dict[str, Any], bool]]
+] = {}
 
 
 def _ttl_get(cache: dict, key: tuple, ttl: float) -> Optional[Any]:
@@ -223,22 +263,27 @@ def _pool_quote_symbols(name: Any) -> List[str]:
     return [p.strip().upper() for p in str(name or "").split("/") if p.strip()]
 
 
-async def fetch_token_top_pool(mint: str, network: str, quote: str) -> str:
-    """Address of the token's highest-volume pool **quoted in ``quote``**.
+async def fetch_token_top_pool_info(
+    mint: str, network: str, quote: str
+) -> Optional[Dict[str, Any]]:
+    """The token's highest-volume pool **quoted in ``quote``**, normalized.
 
-    Used as a fallback when an executor's own ``pool_address`` yields no candles
-    (a closed slot, a pool that never had one recorded). The quote match is not
-    cosmetic: candles are requested with ``currency="token"``, so prices come back
-    denominated in the pool's quote token. Charting a token/USDC pool underneath a
-    token/SOL position would silently draw the right shape on the wrong scale, so
-    a pool that does not match returns "" and the chart stays empty instead.
+    The quote match is not cosmetic: candles are requested with ``currency="token"``,
+    so prices come back denominated in the pool's quote token. Charting a token/USDC
+    pool underneath a token/SOL position would silently draw the right shape on the
+    wrong scale, so a pool that does not match yields ``None`` and the chart stays
+    empty instead.
+
+    ``None`` distinguishes "no answer yet" from "asked and there is none": a
+    no-match *is* cached (as ``{}``), a failed lookup is not, so a GeckoTerminal
+    blip cannot pin an empty answer for the cache's full hour.
     """
     gnet = get_gecko_network(network)
     want = (quote or "").strip().upper()
     key = (gnet, mint, want)
     cached = _ttl_get(_token_pool_cache, key, TOKEN_POOL_TTL)
     if cached is not None:
-        return cached
+        return cached or None
 
     try:
         pools = await _gecko_client().get_top_pools_by_network_token(gnet, mint)
@@ -246,26 +291,42 @@ async def fetch_token_top_pool(mint: str, network: str, quote: str) -> str:
         # Includes the KeyError geckoterminal_py raises post-processing an empty
         # result set. Not cached — a transient failure must not pin "" for an hour.
         logger.info("top-pool lookup failed mint=%s net=%s: %s", mint, gnet, e)
-        return ""
+        return None
 
-    address = ""
+    info: Dict[str, Any] = {}
     try:
         # Rows arrive sorted by 24h volume, so the first quote match is the deepest.
         for row in pools.to_dict("records"):
             if want and want not in _pool_quote_symbols(row.get("name")):
                 continue
-            address = str(row.get("address") or "")
-            if address:
-                break
+            if not str(row.get("address") or ""):
+                continue
+            info = normalize_pool_data(row, source="gecko")
+            _fill_pool_pair_fields(info, network, row)
+            break
     except Exception as e:
         logger.info("top-pool parse failed mint=%s net=%s: %s", mint, gnet, e)
-        return ""
+        return None
 
-    _ttl_put(_token_pool_cache, key, address, TOKEN_POOL_TTL)
-    return address
+    _ttl_put(_token_pool_cache, key, info, TOKEN_POOL_TTL)
+    return info or None
 
 
-async def fetch_pair_top_pool(base: str, quote: str, network: str) -> Tuple[str, bool]:
+async def fetch_token_top_pool(mint: str, network: str, quote: str) -> str:
+    """Address of the token's highest-volume pool **quoted in ``quote``**.
+
+    Used as a fallback when an executor's own ``pool_address`` yields no candles
+    (a closed slot, a pool that never had one recorded). The address form of
+    :func:`fetch_token_top_pool_info`, which is all the candle path needs; the LP
+    panel wants the venue and price too and shares this function's cache entry.
+    """
+    info = await fetch_token_top_pool_info(mint, network, quote)
+    return str((info or {}).get("address") or "")
+
+
+async def fetch_pair_top_pool_info(
+    base: str, quote: str, network: str
+) -> Tuple[Optional[Dict[str, Any]], bool]:
     """Deepest pool trading ``base``/``quote`` on ``network``, found by *symbol*.
 
     For venues that quote tickers rather than addresses (see
@@ -276,21 +337,22 @@ async def fetch_pair_top_pool(base: str, quote: str, network: str) -> Tuple[str,
     GeckoTerminal UI shows first.
 
     Returns:
-        ``(pool_address, inverted)``. ``inverted`` is True when the pool is quoted
+        ``(pool_info, inverted)``. ``inverted`` is True when the pool is quoted
         the other way round (pair ``XRP-RLUSD`` against a ``RLUSD / XRP`` pool);
-        the caller must then read the quote token's price series, not the base's.
-        ``("", False)`` when nothing matches — an empty chart beats a chart drawn
-        on the wrong pair.
+        the caller must then read the quote token's price series, not the base's,
+        and ``pool_info``'s pair fields are reported as the *caller* asked for
+        them, not as the pool names them. ``(None, False)`` when nothing matches —
+        an empty chart beats a chart drawn on the wrong pair.
     """
     gnet = get_gecko_network(network)
     b, q = (base or "").strip().upper(), (quote or "").strip().upper()
     if not b or not q:
-        return "", False
+        return None, False
 
     key = (gnet, b, q)
     cached = _ttl_get(_pair_pool_cache, key, TOKEN_POOL_TTL)
     if cached is not None:
-        return cached
+        return (cached[0] or None), cached[1]
 
     try:
         # Both symbols in the query: GeckoTerminal matches them against the pool
@@ -301,9 +363,9 @@ async def fetch_pair_top_pool(base: str, quote: str, network: str) -> Tuple[str,
     except Exception as e:
         # Not cached — a blip must not pin "no pool" for the full hour.
         logger.info("pair-pool search failed %s-%s net=%s: %s", b, q, gnet, e)
-        return "", False
+        return None, False
 
-    best: Tuple[str, bool] = ("", False)
+    best: Tuple[Dict[str, Any], bool] = ({}, False)
     best_volume = -1.0
     try:
         for row in data.get("data") or []:
@@ -322,13 +384,140 @@ async def fetch_pair_top_pool(base: str, quote: str, network: str) -> Tuple[str,
                 continue
             volume = _get_nested_float(attrs, "volume_usd", "h24") or 0.0
             if volume > best_volume:
-                best, best_volume = (address, inverted), volume
+                flat = _flatten_search_pool(row)
+                info = normalize_pool_data(flat, source="gecko")
+                _fill_pool_pair_fields(
+                    info, network, flat["attributes"], inverted=inverted
+                )
+                best, best_volume = (info, inverted), volume
     except Exception as e:
         logger.info("pair-pool parse failed %s-%s net=%s: %s", b, q, gnet, e)
-        return "", False
+        return None, False
 
     _ttl_put(_pair_pool_cache, key, best, TOKEN_POOL_TTL)
-    return best
+    return (best[0] or None), best[1]
+
+
+async def fetch_pair_top_pool(base: str, quote: str, network: str) -> Tuple[str, bool]:
+    """``(pool_address, inverted)`` for a symbol-quoted pair.
+
+    The address form of :func:`fetch_pair_top_pool_info`, which is all the candle
+    path needs; both share the same cache entry.
+    """
+    info, inverted = await fetch_pair_top_pool_info(base, quote, network)
+    return str((info or {}).get("address") or ""), inverted
+
+
+def _flatten_search_pool(row: Dict[str, Any]) -> Dict[str, Any]:
+    """Lift a ``search/pools`` row's venue onto its attributes.
+
+    The top-pools *token* endpoint carries ``dex_id`` as a column, but
+    ``search/pools`` puts the venue in ``relationships.dex.data.id`` instead. The
+    LP panel's whole question is which venue the pool is on, so the two shapes have
+    to agree before :func:`normalize_pool_data` sees them.
+    """
+    attrs = dict(row.get("attributes") or {})
+    if not attrs.get("dex_id"):
+        dex = ((row.get("relationships") or {}).get("dex") or {}).get("data") or {}
+        attrs["dex_id"] = str(dex.get("id") or "unknown")
+    return {"id": row.get("id", ""), "attributes": attrs}
+
+
+def _fill_pool_pair_fields(
+    info: Dict[str, Any],
+    network: str,
+    attrs: Dict[str, Any],
+    inverted: bool = False,
+) -> None:
+    """Add the pair fields the LP panel needs, in place.
+
+    GeckoTerminal reports no token *symbol* on a pool row (only the ``"SOL / USDC"``
+    display name) and prices in USD or as a quote-token ratio depending on the
+    endpoint — and ``normalize_pool_data`` keeps neither ratio, hence ``attrs``, the
+    row it was built from. This fills ``base_symbol`` / ``quote_symbol`` /
+    ``current_price`` — base priced in quote, the scale every LP bound is expressed
+    in — and pins ``network`` to what the caller asked for rather than
+    ``normalize_pool_data``'s ``"solana"`` default.
+    """
+    base_sym, quote_sym = extract_pair_from_name(str(info.get("name") or ""))
+    ratio = _get_nested_float(attrs, "base_token_price_quote_token")
+    if ratio is None:
+        base_usd = _get_nested_float(attrs, "base_token_price_usd")
+        quote_usd = _get_nested_float(attrs, "quote_token_price_usd")
+        if base_usd and quote_usd:
+            ratio = base_usd / quote_usd
+
+    if inverted:
+        base_sym, quote_sym = quote_sym, base_sym
+        ratio = (1 / ratio) if ratio else None
+
+    info["base_symbol"] = base_sym.upper()
+    info["quote_symbol"] = quote_sym.upper()
+    info["current_price"] = ratio
+    info["network"] = network
+
+
+async def resolve_pool_info(
+    network: str, trading_pair: str
+) -> Optional[Dict[str, Any]]:
+    """The pool a trading pair trades in, normalized, or ``None``.
+
+    Mirrors ``condor.dex_candles._resolve_pool``'s branching — a base that *is* a
+    mint resolves through the token's top pools, a ticker base through a symbol
+    search — so the LP panel names the same pool the chart is drawn from rather
+    than resolving pools by a second mechanism.
+
+    It differs in one direction only: ``_resolve_pool`` restricts the symbol
+    branch to ``SYMBOL_PAIR_NETWORKS``, so a ticker pair like ``SOL-USDC`` on
+    Solana resolves here but not there (the chart stays blank while the panel
+    still names a pool). Pointing ``_resolve_pool`` at this function would close
+    that gap; it is a change to the candle path and deliberately not made here.
+    """
+    # Lazy, like dex_candles' own import of this module: one definition of what an
+    # on-chain address looks like, and no import cycle between the two.
+    from condor.dex_candles import ADDRESS_RE
+
+    base, _, quote = str(trading_pair or "").partition("-")
+    base, quote = base.strip(), quote.strip()
+    if not base or not quote:
+        return None
+
+    if ADDRESS_RE.match(base):
+        return await fetch_token_top_pool_info(base, network, quote)
+
+    info, _inverted = await fetch_pair_top_pool_info(base, quote, network)
+    return info
+
+
+def lp_provider_for_dex(dex_id: str, network: str) -> Optional[str]:
+    """``"meteora/clmm"``-style LP provider for a GeckoTerminal dex id, or ``None``.
+
+    ``None`` means the pool is not one an ``lp_executor`` can add liquidity to, and
+    the caller is expected to report that dead end rather than guess: the API
+    rejects an ``lp_provider`` that does not match the pool, so a wrong answer here
+    becomes a failed executor.
+
+    Matching is by (brand, product) because GeckoTerminal's dex ids are not a
+    stable vocabulary and brand alone is not the position model. Uniswap V3 is
+    ``uniswap_v3`` on Ethereum, ``uniswap-v3-base`` on Base and
+    ``uniswap_v3_arbitrum`` on Arbitrum; ``uniswap-v4-ethereum`` and
+    ``meteora-damm-v2`` share a brand with a supported venue but not its mechanics;
+    and plain ``raydium`` is the constant-product AMM, while only ``raydium-clmm``
+    is the concentrated pool the ``raydium/clmm`` connector drives.
+    """
+    tokens = [t for t in _DEX_ID_SPLIT_RE.split((dex_id or "").strip().lower()) if t]
+    if not tokens:
+        return None
+    brand, qualifiers = tokens[0], [t for t in tokens[1:] if t not in _CHAIN_TOKENS]
+    for name, required, networks in _CLMM_VENUES:
+        if brand != name:
+            continue
+        if qualifiers != required:
+            return None
+        if get_gecko_network(network) not in networks:
+            return None
+        return f"{name}/clmm"
+    return None
 
 
 def can_fetch_liquidity(dex_id: str, network: str = None) -> bool:
diff --git a/tests/test_dex_pool_resolution.py b/tests/test_dex_pool_resolution.py
new file mode 100644
index 00000000..ef4f97db
--- /dev/null
+++ b/tests/test_dex_pool_resolution.py
@@ -0,0 +1,475 @@
+"""Tests for FEAT-042: pool resolution serves the LP panel and the candle path.
+
+Two things are being protected here.
+
+**The candle path must not notice the refactor.** ``fetch_token_top_pool`` used to
+do the GeckoTerminal query itself; it is now the address form of
+``fetch_token_top_pool_info``, and ``dex_candles._resolve_pool`` still calls the
+former. Same address, same cache entry, same "a failure is not cached but an empty
+answer is" behavior — ``tests/test_dex_candles.py`` covers the address contract,
+these cover the delegation and the shared cache.
+
+**The LP panel cannot guess the venue.** An ``lp_executor`` needs
+``lp_provider`` as ``dex/clmm``, and the API rejects anything else. The deepest pool
+for a pair is frequently *not* a CLMM pool — ``meteora-damm-v2`` and
+``uniswap-v4-ethereum`` are real answers from the live API — so
+``lp_provider_for_dex`` has to say "no" rather than brand-match its way to a payload
+that fails.
+"""
+
+import asyncio
+
+import pytest
+
+from handlers.dex import pool_data
+
+
+def run(coro):
+    return asyncio.run(coro)
+
+
+class _FakeRows:
+    """Stands in for the DataFrame ``get_top_pools_by_network_token`` returns."""
+
+    def __init__(self, rows):
+        self._rows = rows
+
+    def to_dict(self, _orient):
+        return self._rows
+
+
+def _token_row(**over):
+    row = {
+        "name": "BONK / SOL",
+        "address": "bonk_sol_pool",
+        "dex_id": "meteora",
+        "base_token_price_usd": "0.000002",
+        "quote_token_price_usd": "100.0",
+        "volume_usd_h24": 1000.0,
+    }
+    row.update(over)
+    return row
+
+
+def _search_row(name="SOL / USDC", address="sol_usdc_pool", dex="orca", **attrs):
+    base = {
+        "name": name,
+        "address": address,
+        "base_token_price_quote_token": "75.5",
+        "volume_usd": {"h24": 5000.0},
+    }
+    base.update(attrs)
+    return {
+        "id": f"solana_{address}",
+        "attributes": base,
+        "relationships": {"dex": {"data": {"id": dex, "type": "dex"}}},
+    }
+
+
+@pytest.fixture(autouse=True)
+def _clear_caches():
+    caches = (pool_data._token_pool_cache, pool_data._pair_pool_cache)
+    for cache in caches:
+        cache.clear()
+    yield
+    for cache in caches:
+        cache.clear()
+
+
+# ── The candle path is unchanged by the extraction ──
+
+
+def test_the_address_form_still_returns_a_bare_address(monkeypatch):
+    class _Client:
+        async def get_top_pools_by_network_token(self, *_a):
+            return _FakeRows([_token_row()])
+
+    monkeypatch.setattr(pool_data, "_gecko_client", lambda: _Client())
+    assert (
+        run(pool_data.fetch_token_top_pool("mint", "solana", "SOL")) == "bonk_sol_pool"
+    )
+
+
+def test_the_two_forms_share_one_cache_entry(monkeypatch):
+    """The candle path and the LP panel ask the same question — once."""
+    calls = []
+
+    class _Client:
+        async def get_top_pools_by_network_token(self, *_a):
+            calls.append(1)
+            return _FakeRows([_token_row()])
+
+    monkeypatch.setattr(pool_data, "_gecko_client", lambda: _Client())
+    info = run(pool_data.fetch_token_top_pool_info("mint", "solana", "SOL"))
+    address = run(pool_data.fetch_token_top_pool("mint", "solana", "SOL"))
+    assert info["address"] == address == "bonk_sol_pool"
+    assert len(calls) == 1
+
+
+def test_a_no_match_is_cached_once_for_both_forms(monkeypatch):
+    """An unlisted pair is a real answer; re-asking on every render is not."""
+    calls = []
+
+    class _Client:
+        async def get_top_pools_by_network_token(self, *_a):
+            calls.append(1)
+            return _FakeRows([_token_row(name="BONK / USDC")])
+
+    monkeypatch.setattr(pool_data, "_gecko_client", lambda: _Client())
+    assert run(pool_data.fetch_token_top_pool_info("mint", "solana", "SOL")) is None
+    assert run(pool_data.fetch_token_top_pool("mint", "solana", "SOL")) == ""
+    assert len(calls) == 1
+
+
+def test_a_failed_lookup_is_still_not_cached_in_the_info_form(monkeypatch):
+    calls = []
+
+    class _Failing:
+        async def get_top_pools_by_network_token(self, *_a):
+            calls.append(1)
+            raise RuntimeError("429 Too Many Requests")
+
+    monkeypatch.setattr(pool_data, "_gecko_client", lambda: _Failing())
+    assert run(pool_data.fetch_token_top_pool_info("mint", "solana", "SOL")) is None
+    assert run(pool_data.fetch_token_top_pool_info("mint", "solana", "SOL")) is None
+    assert len(calls) == 2
+
+
+def test_a_row_without_an_address_is_skipped(monkeypatch):
+    """Preserved from the address form: a row with no address is not a pool."""
+
+    class _Client:
+        async def get_top_pools_by_network_token(self, *_a):
+            return _FakeRows([_token_row(address=""), _token_row(address="real_pool")])
+
+    monkeypatch.setattr(pool_data, "_gecko_client", lambda: _Client())
+    assert run(pool_data.fetch_token_top_pool("mint", "solana", "SOL")) == "real_pool"
+
+
+# ── What the extraction adds ──
+
+
+def test_the_info_form_carries_the_venue_and_the_pair_price(monkeypatch):
+    class _Client:
+        async def get_top_pools_by_network_token(self, *_a):
+            return _FakeRows([_token_row()])
+
+    monkeypatch.setattr(pool_data, "_gecko_client", lambda: _Client())
+    info = run(
+        pool_data.fetch_token_top_pool_info("mint", "solana-mainnet-beta", "SOL")
+    )
+    assert info["dex_id"] == "meteora"
+    assert info["base_symbol"] == "BONK"
+    assert info["quote_symbol"] == "SOL"
+    # Base priced in quote, the scale every LP bound is expressed in — not USD.
+    assert info["current_price"] == pytest.approx(0.000002 / 100.0)
+    # The caller's network, not normalize_pool_data's "solana" default.
+    assert info["network"] == "solana-mainnet-beta"
+
+
+def test_the_price_is_none_when_gecko_reports_no_usd_prices(monkeypatch):
+    """A missing price must not become 0 — the panel would auto-fill a zero range."""
+
+    class _Client:
+        async def get_top_pools_by_network_token(self, *_a):
+            return _FakeRows(
+                [_token_row(base_token_price_usd=None, quote_token_price_usd=None)]
+            )
+
+    monkeypatch.setattr(pool_data, "_gecko_client", lambda: _Client())
+    info = run(pool_data.fetch_token_top_pool_info("mint", "solana", "SOL"))
+    assert info["current_price"] is None
+
+
+# ── The symbol-search branch ──
+
+
+def test_the_search_branch_lifts_the_venue_out_of_relationships(monkeypatch):
+    """``search/pools`` reports the dex in relationships, not as a column."""
+
+    class _Client:
+        async def api_request(self, *_a, **_kw):
+            return {"data": [_search_row()]}
+
+    monkeypatch.setattr(pool_data, "_gecko_client", lambda: _Client())
+    info, inverted = run(pool_data.fetch_pair_top_pool_info("SOL", "USDC", "solana"))
+    assert inverted is False
+    assert info["dex_id"] == "orca"
+    assert info["address"] == "sol_usdc_pool"
+    assert info["current_price"] == pytest.approx(75.5)
+
+
+def test_an_inverted_pool_reports_the_pair_as_asked(monkeypatch):
+    """Asked for XRP-RLUSD against a ``RLUSD / XRP`` pool: swap sides *and* invert
+    the price, or the panel would draw LP bounds on the reciprocal scale."""
+
+    class _Client:
+        async def api_request(self, *_a, **_kw):
+            return {
+                "data": [
+                    _search_row(
+                        name="RLUSD / XRP",
+                        address="rlusd_xrp",
+                        dex="xrpl-amm",
+                        base_token_price_quote_token="0.4",
+                    )
+                ]
+            }
+
+    monkeypatch.setattr(pool_data, "_gecko_client", lambda: _Client())
+    info, inverted = run(pool_data.fetch_pair_top_pool_info("XRP", "RLUSD", "xrpl"))
+    assert inverted is True
+    assert (info["base_symbol"], info["quote_symbol"]) == ("XRP", "RLUSD")
+    assert info["current_price"] == pytest.approx(1 / 0.4)
+
+
+def test_the_search_address_form_keeps_its_tuple_contract(monkeypatch):
+    class _Client:
+        async def api_request(self, *_a, **_kw):
+            return {"data": [_search_row()]}
+
+    monkeypatch.setattr(pool_data, "_gecko_client", lambda: _Client())
+    assert run(pool_data.fetch_pair_top_pool("SOL", "USDC", "solana")) == (
+        "sol_usdc_pool",
+        False,
+    )
+
+
+def test_the_search_forms_share_one_cache_entry(monkeypatch):
+    calls = []
+
+    class _Client:
+        async def api_request(self, *_a, **_kw):
+            calls.append(1)
+            return {"data": [_search_row()]}
+
+    monkeypatch.setattr(pool_data, "_gecko_client", lambda: _Client())
+    run(pool_data.fetch_pair_top_pool_info("SOL", "USDC", "solana"))
+    run(pool_data.fetch_pair_top_pool("SOL", "USDC", "solana"))
+    assert len(calls) == 1
+
+
+def test_the_deepest_matching_search_pool_wins(monkeypatch):
+    """Ticker collisions are real, so volume decides — not result order."""
+
+    class _Client:
+        async def api_request(self, *_a, **_kw):
+            return {
+                "data": [
+                    _search_row(address="thin", volume_usd={"h24": 10.0}),
+                    _search_row(address="deep", volume_usd={"h24": 900.0}),
+                    _search_row(address="mid", volume_usd={"h24": 500.0}),
+                ]
+            }
+
+    monkeypatch.setattr(pool_data, "_gecko_client", lambda: _Client())
+    info, _ = run(pool_data.fetch_pair_top_pool_info("SOL", "USDC", "solana"))
+    assert info["address"] == "deep"
+
+
+# ── resolve_pool_info dispatches like the candle path ──
+
+
+def test_an_address_base_resolves_through_the_token_branch(monkeypatch):
+    seen = {}
+
+    async def _token(mint, network, quote):
+        seen["token"] = (mint, network, quote)
+        return {"address": "from_token"}
+
+    async def _pair(*_a):
+        raise AssertionError("the search branch must not be used for a mint base")
+
+    monkeypatch.setattr(pool_data, "fetch_token_top_pool_info", _token)
+    monkeypatch.setattr(pool_data, "fetch_pair_top_pool_info", _pair)
+    mint = "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263"
+    info = run(pool_data.resolve_pool_info("solana-mainnet-beta", f"{mint}-SOL"))
+    assert info == {"address": "from_token"}
+    assert seen["token"] == (mint, "solana-mainnet-beta", "SOL")
+
+
+def test_a_ticker_base_resolves_through_the_search_branch(monkeypatch):
+    async def _token(*_a):
+        raise AssertionError("a ticker is not a mint GeckoTerminal can look up")
+
+    async def _pair(base, quote, network):
+        return {"address": "from_search", "asked": (base, quote, network)}, False
+
+    monkeypatch.setattr(pool_data, "fetch_token_top_pool_info", _token)
+    monkeypatch.setattr(pool_data, "fetch_pair_top_pool_info", _pair)
+    info = run(pool_data.resolve_pool_info("solana-mainnet-beta", "SOL-USDC"))
+    assert info["address"] == "from_search"
+    assert info["asked"] == ("SOL", "USDC", "solana-mainnet-beta")
+
+
+@pytest.mark.parametrize("pair", ["", "SOL", "-USDC", "SOL-", "   "])
+def test_a_pair_missing_a_side_resolves_to_nothing(monkeypatch, pair):
+    """No request is spent on a pair that cannot name a pool."""
+
+    async def _boom(*_a):
+        raise AssertionError("no lookup should happen")
+
+    monkeypatch.setattr(pool_data, "fetch_token_top_pool_info", _boom)
+    monkeypatch.setattr(pool_data, "fetch_pair_top_pool_info", _boom)
+    assert run(pool_data.resolve_pool_info("solana-mainnet-beta", pair)) is None
+
+
+# ── lp_provider_for_dex refuses to guess ──
+
+
+@pytest.mark.parametrize(
+    "dex_id,network,expected",
+    [
+        # Every id below was observed coming back from the live GeckoTerminal
+        # search for SOL-USDC, BONK-SOL, JUP-USDC, WETH-USDC and WBNB-USDT.
+        ("meteora", "solana-mainnet-beta", "meteora/clmm"),
+        ("orca", "solana-mainnet-beta", "orca/clmm"),
+        ("raydium-clmm", "solana-mainnet-beta", "raydium/clmm"),
+        # The same venue, spelled three ways across three chains.
+        ("uniswap_v3", "ethereum-mainnet", "uniswap/clmm"),
+        ("uniswap-v3-base", "base-mainnet", "uniswap/clmm"),
+        ("uniswap_v3_arbitrum", "arbitrum-one", "uniswap/clmm"),
+        ("pancakeswap-v3-bsc", "binance-smart-chain", "pancakeswap/clmm"),
+        ("pancakeswap-v3-ethereum", "ethereum-mainnet", "pancakeswap/clmm"),
+        # A brand match is not a position model. `raydium` alone is the
+        # constant-product AMM v4, `meteora-damm-v2` is Meteora's AMM, and
+        # Uniswap v4's hooks are not the v3 CLMM the connector drives.
+        ("raydium", "solana-mainnet-beta", None),
+        ("meteora-damm-v2", "solana-mainnet-beta", None),
+        ("uniswap-v4-ethereum", "ethereum-mainnet", None),
+        ("uniswap-v2-base", "base-mainnet", None),
+        ("pancakeswap_v2", "binance-smart-chain", None),
+        # `uniswap-bsc` names no version, so it is not knowably v3.
+        ("uniswap-bsc", "binance-smart-chain", None),
+        # Right venue, wrong chain.
+        ("uniswap_v3", "solana-mainnet-beta", None),
+        ("meteora", "ethereum-mainnet", None),
+        ("pancakeswap-v3-solana", "solana-mainnet-beta", None),
+        # Not a venue Condor can LP on at all.
+        ("sushiswap-v3-ethereum", "ethereum-mainnet", None),
+        ("aerodrome-slipstream-3", "base-mainnet", None),
+        ("humidifi", "solana-mainnet-beta", None),
+        ("pumpswap", "solana-mainnet-beta", None),
+        ("unknown", "solana-mainnet-beta", None),
+        ("", "solana-mainnet-beta", None),
+    ],
+)
+def test_lp_provider_only_names_a_clmm_venue_on_its_own_chain(
+    dex_id, network, expected
+):
+    assert pool_data.lp_provider_for_dex(dex_id, network) == expected
+
+
+# ── The route ──
+
+
+def _call_route(monkeypatch, resolver, access=True):
+    from condor.web.models import WebUser
+    from condor.web.routes.market import get_dex_pool
+
+    class _Cm:
+        def has_server_access(self, user_id, name):
+            return access
+
+    monkeypatch.setattr(
+        "condor.web.routes.market.get_config_manager", lambda: _Cm(), raising=True
+    )
+    monkeypatch.setattr(pool_data, "resolve_pool_info", resolver)
+    return asyncio.run(
+        get_dex_pool(
+            "srv",
+            connector="solana-mainnet-beta",
+            trading_pair="SOL-USDC",
+            user=WebUser(id=1, role="user"),
+        )
+    )
+
+
+_REAL_POOL = "Czfq3xZZDmsdGdUyrNLtRhGc47cXcZtLG4crryfu44zE"
+
+
+def test_route_reports_the_pool_and_its_lp_provider(monkeypatch):
+    async def _resolve(_net, _pair):
+        return {
+            "address": _REAL_POOL,
+            "dex_id": "orca",
+            "current_price": 75.5,
+            "base_symbol": "SOL",
+            "quote_symbol": "USDC",
+        }
+
+    assert _call_route(monkeypatch, _resolve) == {
+        "pool_address": _REAL_POOL,
+        "dex_id": "orca",
+        "lp_provider": "orca/clmm",
+        "lp_supported": True,
+        "current_price": 75.5,
+        "base_symbol": "SOL",
+        "quote_symbol": "USDC",
+    }
+
+
+def test_route_reports_an_unsupported_venue_without_failing(monkeypatch):
+    """The pool is real and chartable; it just cannot take an LP position. The
+    panel's answer is to ask for a pool address by hand, so this is a 200."""
+
+    async def _resolve(_net, _pair):
+        return {
+            "address": _REAL_POOL,
+            "dex_id": "uniswap-v4-ethereum",
+            "current_price": 1871.0,
+            "base_symbol": "WETH",
+            "quote_symbol": "USDC",
+        }
+
+    result = _call_route(monkeypatch, _resolve)
+    assert result["lp_supported"] is False
+    assert result["lp_provider"] is None
+    # The address is still reported — the chart uses it even when LP cannot.
+    assert result["pool_address"] == _REAL_POOL
+    assert result["dex_id"] == "uniswap-v4-ethereum"
+
+
+def test_route_returns_a_200_when_no_pool_is_found(monkeypatch):
+    async def _resolve(_net, _pair):
+        return None
+
+    assert _call_route(monkeypatch, _resolve) == {
+        "pool_address": None,
+        "dex_id": None,
+        "lp_provider": None,
+        "lp_supported": False,
+        "current_price": None,
+        "base_symbol": None,
+        "quote_symbol": None,
+    }
+
+
+def test_route_returns_a_200_when_resolution_raises(monkeypatch):
+    async def _resolve(_net, _pair):
+        raise RuntimeError("geckoterminal down")
+
+    assert _call_route(monkeypatch, _resolve)["lp_supported"] is False
+
+
+def test_route_refuses_an_address_that_is_not_one(monkeypatch):
+    """Whatever comes back is handed to /market/candles and to the executor config,
+    so a malformed address is dropped rather than passed along."""
+
+    async def _resolve(_net, _pair):
+        return {"address": "not an address", "dex_id": "orca"}
+
+    result = _call_route(monkeypatch, _resolve)
+    assert result["pool_address"] is None
+    assert result["lp_supported"] is False
+
+
+def test_route_rejects_a_caller_without_access(monkeypatch):
+    from fastapi import HTTPException
+
+    async def _resolve(_net, _pair):
+        raise AssertionError("access is checked before anything is resolved")
+
+    with pytest.raises(HTTPException) as e:
+        _call_route(monkeypatch, _resolve, access=False)
+    assert e.value.status_code == 403

From 1822a1ef192af8826d3c8339469eead2e06f3c30 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Tue, 11 Aug 2026 09:46:05 +0300
Subject: [PATCH 004/116] Create and draw an LP position from the trade panel
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The LP executor is already a grid, structurally: `lower_price`/`upper_price` are the
range it earns fees in, and the schema calls its `upper_limit_price` /
`lower_limit_price` "grid-executor style" auto-close triggers. That is a
one-to-one match with `GridBox`, and `TradeChart` draws boxes without ever reading
`type` — so the whole visualization is one `computeLpOverlay` and one `case "lp":`,
with no new drawing code. `custom_info` wins over `config` for the bounds because a
CLMM position is snapped to the venue's bins, so the box shows where the liquidity
actually sits rather than what was asked for.

`ExecutorType` gains `lp` and `SupportedExecutorType` is gone. FEAT-041 introduced
that second union precisely to avoid breaking the switches this commit is here to
extend; keeping both would leave two answers to "which executor types exist" and no
compiler pressure to keep them agreeing. Widening the real union is what made
`tsc` name all four exhaustive sites (`TYPE_LABELS`, `activeValidation`,
`chartProps`, the payload block) instead of failing silently in the two it cannot
see.

The panel resolves its pool from the server and says which one it got, because the
chart already resolves one implicitly for every DEX candle it draws — making that
choice visible costs one endpoint and turns a silent assumption into a stated one.
A manual pool address and provider override it and survive every re-resolve, which
is the real answer for anyone who cares about fee tier or bin step. When the
deepest pool is not a CLMM venue nothing is auto-filled at all: the address of a
router pool would only build a payload the API rejects.

`connector_name` is the network and the DEX goes in `lp_provider`; the config's
`keep_position` is not the flag `stop` takes, so the form says which one it sets.
Every key was cross-checked against the live `lp_executor` schema — all seven
required fields present, no unknown keys — and the range arithmetic reproduces the
schema's own worked single-sided example exactly.

FEAT-042
---
 .../src/components/executor/ExecutorTable.tsx |  81 +++
 .../src/components/executor/LPConfigPanel.tsx | 682 ++++++++++++++++++
 frontend/src/components/executor/fields.tsx   |   9 +
 frontend/src/components/executor/types.ts     |  17 +-
 frontend/src/components/trade/TradeChart.tsx  |  21 +-
 frontend/src/lib/api.ts                       |  24 +
 frontend/src/lib/connector-capabilities.ts    |  15 +-
 frontend/src/lib/executor-overlays.ts         |  78 ++
 frontend/src/pages/CreateExecutor.tsx         |  29 +-
 9 files changed, 929 insertions(+), 27 deletions(-)
 create mode 100644 frontend/src/components/executor/LPConfigPanel.tsx

diff --git a/frontend/src/components/executor/ExecutorTable.tsx b/frontend/src/components/executor/ExecutorTable.tsx
index f6b11fb8..abb7fa4d 100644
--- a/frontend/src/components/executor/ExecutorTable.tsx
+++ b/frontend/src/components/executor/ExecutorTable.tsx
@@ -405,6 +405,12 @@ export function DetailPanel({
   const config = executor.config || {};
   const isPosition = executor.type === "position";
   const isGrid = executor.type === "grid";
+  const isLp = executor.type === "lp";
+  // A CLMM position is snapped to the venue's bins, so the on-chain bounds differ
+  // from the requested ones. Show where the liquidity actually sits.
+  const custom = executor.custom_info || {};
+  const lpLower = custom.lower_price ?? custom.price_lower ?? config.lower_price;
+  const lpUpper = custom.upper_price ?? custom.price_upper ?? config.upper_price;
 
   // Parse triple_barrier_config (may be a JSON string or object)
   const tripleBarrier: Record<string, unknown> = (() => {
@@ -673,6 +679,81 @@ export function DetailPanel({
             </div>
           )}
 
+          {/* LP-specific details */}
+          {isLp && (
+            <div className="rounded-lg border border-[var(--color-border)] bg-[var(--color-surface)] p-4 space-y-3">
+              <h3 className="text-xs font-medium uppercase tracking-wider text-[var(--color-text-muted)]">
+                LP Details
+              </h3>
+              <div className="grid grid-cols-2 gap-3 text-sm">
+                {lpLower != null && (
+                  <div>
+                    <div className="text-[var(--color-text-muted)] text-xs mb-0.5">Lower Price</div>
+                    <div className="font-medium tabular-nums">{formatPrice(Number(lpLower))}</div>
+                  </div>
+                )}
+                {lpUpper != null && (
+                  <div>
+                    <div className="text-[var(--color-text-muted)] text-xs mb-0.5">Upper Price</div>
+                    <div className="font-medium tabular-nums">{formatPrice(Number(lpUpper))}</div>
+                  </div>
+                )}
+                {config.lower_limit_price != null && (
+                  <div>
+                    <div className="text-[var(--color-text-muted)] text-xs mb-0.5">Lower Limit</div>
+                    <div className="font-medium tabular-nums text-[var(--color-red)]">
+                      {formatPrice(Number(config.lower_limit_price))}
+                    </div>
+                  </div>
+                )}
+                {config.upper_limit_price != null && (
+                  <div>
+                    <div className="text-[var(--color-text-muted)] text-xs mb-0.5">Upper Limit</div>
+                    <div className="font-medium tabular-nums text-[var(--color-red)]">
+                      {formatPrice(Number(config.upper_limit_price))}
+                    </div>
+                  </div>
+                )}
+                {config.lp_provider != null && (
+                  <div>
+                    <div className="text-[var(--color-text-muted)] text-xs mb-0.5">Provider</div>
+                    <div className="font-medium text-xs">{String(config.lp_provider)}</div>
+                  </div>
+                )}
+                {custom.in_range != null && (
+                  <div>
+                    <div className="text-[var(--color-text-muted)] text-xs mb-0.5">Range Status</div>
+                    <div className="font-medium text-xs">{String(custom.in_range)}</div>
+                  </div>
+                )}
+                {config.base_amount != null && Number(config.base_amount) > 0 && (
+                  <div>
+                    <div className="text-[var(--color-text-muted)] text-xs mb-0.5">Base Amount</div>
+                    <div className="font-medium tabular-nums">{String(config.base_amount)}</div>
+                  </div>
+                )}
+                {config.quote_amount != null && Number(config.quote_amount) > 0 && (
+                  <div>
+                    <div className="text-[var(--color-text-muted)] text-xs mb-0.5">Quote Amount</div>
+                    <div className="font-medium tabular-nums">{String(config.quote_amount)}</div>
+                  </div>
+                )}
+                {config.pool_address != null && (
+                  <div className="col-span-2">
+                    <div className="text-[var(--color-text-muted)] text-xs mb-0.5">Pool</div>
+                    <div className="font-mono text-[11px] break-all">{String(config.pool_address)}</div>
+                  </div>
+                )}
+                {config.keep_position != null && (
+                  <div>
+                    <div className="text-[var(--color-text-muted)] text-xs mb-0.5">Keep Position</div>
+                    <div className="font-medium">{String(config.keep_position) === "true" ? "Yes" : "No"}</div>
+                  </div>
+                )}
+              </div>
+            </div>
+          )}
+
           {/* Timestamps */}
           {executor.timestamp > 0 && (
             <div className="rounded-lg border border-[var(--color-border)] bg-[var(--color-surface)] p-4 space-y-1">
diff --git a/frontend/src/components/executor/LPConfigPanel.tsx b/frontend/src/components/executor/LPConfigPanel.tsx
new file mode 100644
index 00000000..5d72d9bb
--- /dev/null
+++ b/frontend/src/components/executor/LPConfigPanel.tsx
@@ -0,0 +1,682 @@
+import { useQuery } from "@tanstack/react-query";
+import { useEffect, useMemo, useReducer } from "react";
+import { AlertTriangle, Sparkles } from "lucide-react";
+
+import {
+  AdvancedSection,
+  NumberField,
+  PriceField,
+  SectionHeader,
+  SelectField,
+  ToggleField,
+  ValidationMessages,
+  type FieldDispatch,
+} from "./fields";
+import type { ChartPriceMapping, ExecutorValidation } from "./types";
+import { api, type DexPoolInfo } from "@/lib/api";
+import { getThemeColors } from "@/lib/theme-colors";
+
+// ── Sides ──
+// `side` is a TradeType enum, not a direction: it says which token(s) you are
+// putting in, which in turn dictates where the range sits relative to the price.
+
+export const LP_SIDE_BUY = 1; // quote-only, range below the price
+export const LP_SIDE_SELL = 2; // base-only, range above the price
+export const LP_SIDE_RANGE = 3; // both tokens, range centered
+
+export type LpSide = 1 | 2 | 3;
+
+/** The buffer between a range bound and its auto-close trigger. */
+const LIMIT_BUFFER = 0.1;
+
+// ── State ──
+
+export interface LPState {
+  pool_address: string;
+  lp_provider: string;
+  lower_price: number;
+  upper_price: number;
+  lower_limit_price: number;
+  upper_limit_price: number;
+  side: LpSide;
+  base_amount: number;
+  quote_amount: number;
+  keep_position: boolean;
+  /** Meteora only: 0 Spot / 1 Curve / 2 Bid-Ask. Held as a string for SelectField. */
+  strategy_type: string;
+  /** Half-width of the auto-filled range, as a fraction of the current price. */
+  range_pct: number;
+  activePickField: string | null;
+  showAdvanced: boolean;
+  /**
+   * Whether the user has typed a pool or provider. A manual entry is the real
+   * answer for anyone who cares about fee tier or bin step, so it must survive
+   * every re-resolve of the auto-resolved pool.
+   */
+  poolTouched: boolean;
+}
+
+type LPAction =
+  | { type: "SET_FIELD"; field: string; value: unknown }
+  | { type: "SET_CONNECTOR"; value: string }
+  | { type: "SET_PAIR"; value: string }
+  | { type: "RESOLVED"; pool: DexPoolInfo }
+  | { type: "AUTO_RANGE"; price: number }
+  | { type: "SET_SIDE"; value: LpSide; price: number | null }
+  | { type: "SET_RANGE_PCT"; value: number; price: number | null };
+
+const DEFAULTS: LPState = {
+  pool_address: "",
+  lp_provider: "",
+  lower_price: 0,
+  upper_price: 0,
+  lower_limit_price: 0,
+  upper_limit_price: 0,
+  side: LP_SIDE_RANGE,
+  base_amount: 0,
+  quote_amount: 0,
+  keep_position: true,
+  strategy_type: "0",
+  range_pct: 0.05,
+  activePickField: null,
+  showAdvanced: false,
+  poolTouched: false,
+};
+
+const STORAGE_KEY = "condor_lp_defaults";
+
+// The pool and the range belong to a pair, not to the user's habits, so neither is
+// persisted — only the shape of position they tend to open.
+const PERSISTED_FIELDS: (keyof LPState)[] = [
+  "side",
+  "base_amount",
+  "quote_amount",
+  "keep_position",
+  "strategy_type",
+  "range_pct",
+];
+
+function loadSavedDefaults(): LPState {
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY);
+    if (!raw) return DEFAULTS;
+    const saved = JSON.parse(raw);
+    const merged = { ...DEFAULTS };
+    for (const key of PERSISTED_FIELDS) {
+      if (key in saved && saved[key] !== undefined) {
+        (merged as Record<string, unknown>)[key] = saved[key];
+      }
+    }
+    return merged;
+  } catch {
+    return DEFAULTS;
+  }
+}
+
+function saveDefaults(state: LPState) {
+  const toSave: Record<string, unknown> = {};
+  for (const key of PERSISTED_FIELDS) toSave[key] = state[key];
+  localStorage.setItem(STORAGE_KEY, JSON.stringify(toSave));
+}
+
+/**
+ * Range bounds and auto-close triggers for a side, anchored on the current price.
+ *
+ * A single-sided position has to start out of range for its conversion to happen
+ * in the direction the tokens allow: quote-only (BUY) converts to base as the
+ * price *falls* through a range below it, base-only (SELL) converts to quote as
+ * the price *rises* through a range above it. Centering either one would leave
+ * half the range unusable.
+ */
+export function rangeForSide(side: LpSide, price: number, pct: number) {
+  let lower: number;
+  let upper: number;
+  if (side === LP_SIDE_BUY) {
+    lower = price * (1 - pct);
+    upper = price;
+  } else if (side === LP_SIDE_SELL) {
+    lower = price;
+    upper = price * (1 + pct);
+  } else {
+    lower = price * (1 - pct);
+    upper = price * (1 + pct);
+  }
+  return {
+    lower_price: lower,
+    upper_price: upper,
+    lower_limit_price: lower * (1 - LIMIT_BUFFER),
+    upper_limit_price: upper * (1 + LIMIT_BUFFER),
+  };
+}
+
+function lpReducer(state: LPState, action: LPAction): LPState {
+  switch (action.type) {
+    case "SET_FIELD": {
+      const touched =
+        action.field === "pool_address" || action.field === "lp_provider";
+      return {
+        ...state,
+        [action.field]: action.value,
+        ...(touched ? { poolTouched: true } : {}),
+      };
+    }
+    case "SET_CONNECTOR":
+    case "SET_PAIR":
+      // A pool address belongs to one pair on one chain. Carrying it across would
+      // submit a position in a pool that trades something else entirely.
+      return {
+        ...state,
+        pool_address: "",
+        lp_provider: "",
+        poolTouched: false,
+        lower_price: 0,
+        upper_price: 0,
+        lower_limit_price: 0,
+        upper_limit_price: 0,
+      };
+    case "RESOLVED": {
+      // Only a pool that can actually take a position is filled in. Handing over
+      // the address of a router pool would just build a payload the API rejects.
+      if (state.poolTouched || !action.pool.lp_supported) return state;
+      return {
+        ...state,
+        pool_address: action.pool.pool_address ?? "",
+        lp_provider: action.pool.lp_provider ?? "",
+      };
+    }
+    case "AUTO_RANGE":
+      return { ...state, ...rangeForSide(state.side, action.price, state.range_pct) };
+    case "SET_SIDE":
+      return {
+        ...state,
+        side: action.value,
+        ...(action.price && action.price > 0
+          ? rangeForSide(action.value, action.price, state.range_pct)
+          : {}),
+      };
+    case "SET_RANGE_PCT":
+      return {
+        ...state,
+        range_pct: action.value,
+        ...(action.price && action.price > 0
+          ? rangeForSide(state.side, action.price, action.value)
+          : {}),
+      };
+    default:
+      return state;
+  }
+}
+
+// ── Validation ──
+
+export function useLpValidation(state: LPState): ExecutorValidation {
+  return useMemo(() => {
+    const errors: string[] = [];
+    if (!state.pool_address) errors.push("Pool address required");
+    if (!state.lp_provider) errors.push("LP provider required (e.g. meteora/clmm)");
+    if (state.lower_price <= 0) errors.push("Lower price required");
+    if (state.upper_price <= 0) errors.push("Upper price required");
+    if (
+      state.lower_price > 0 &&
+      state.upper_price > 0 &&
+      state.upper_price <= state.lower_price
+    ) {
+      errors.push("Upper price must be above lower price");
+    }
+    if (state.base_amount <= 0 && state.quote_amount <= 0) {
+      errors.push("At least one amount required");
+    }
+    return { valid: errors.length === 0, errors };
+  }, [state]);
+}
+
+/**
+ * Things the schema permits but that are rarely meant. Kept apart from validation
+ * because none of them should block a create — a deliberately odd position is
+ * still a position.
+ */
+function rangeWarnings(state: LPState, price: number | null): string[] {
+  const warnings: string[] = [];
+  const bothAmounts = state.base_amount > 0 && state.quote_amount > 0;
+
+  if (state.side === LP_SIDE_RANGE && !bothAmounts) {
+    warnings.push("RANGE is double-sided; only one amount is set");
+  }
+  if (state.side !== LP_SIDE_RANGE && bothAmounts) {
+    warnings.push("Single-sided side with both amounts set — one will be unused");
+  }
+  if (price && price > 0) {
+    if (state.side === LP_SIDE_BUY && state.lower_price > price) {
+      warnings.push("BUY (quote-only) usually ranges below the current price");
+    }
+    if (state.side === LP_SIDE_SELL && state.upper_price < price) {
+      warnings.push("SELL (base-only) usually ranges above the current price");
+    }
+  }
+  if (state.upper_limit_price > 0 && state.upper_limit_price <= state.upper_price) {
+    warnings.push("Upper limit sits inside the range");
+  }
+  if (state.lower_limit_price > 0 && state.lower_limit_price >= state.lower_price) {
+    warnings.push("Lower limit sits inside the range");
+  }
+  return warnings;
+}
+
+// ── Chart pick slots ──
+// The chart carries three pick slots. Upper/lower bounds and the upper limit get
+// them; the lower limit is typed, and its PriceField offers no crosshair.
+const PICK_SLOT: Record<string, "start" | "end" | "limit"> = {
+  upper_price: "start",
+  lower_price: "end",
+  upper_limit_price: "limit",
+};
+
+const SLOT_FIELD: Record<"start" | "end" | "limit", keyof LPState> = {
+  start: "upper_price",
+  end: "lower_price",
+  limit: "upper_limit_price",
+};
+
+export function isMeteoraProvider(provider: string): boolean {
+  return provider.toLowerCase().startsWith("meteora/");
+}
+
+// ── Hook ──
+
+export function useLpConfig(
+  server: string | null,
+  connector: string,
+  pair: string,
+  enabled: boolean,
+) {
+  const [state, dispatch] = useReducer(lpReducer, undefined, loadSavedDefaults);
+  const validation = useLpValidation(state);
+
+  const { data: pool, isFetching: poolFetching } = useQuery({
+    queryKey: ["dex-pool", server, connector, pair],
+    queryFn: () => api.getDexPool(server!, connector, pair),
+    enabled: enabled && !!server && !!connector && !!pair,
+    staleTime: 60 * 1000,
+  });
+
+  useEffect(() => {
+    if (pool) dispatch({ type: "RESOLVED", pool });
+  }, [pool]);
+
+  const chartProps: ChartPriceMapping = useMemo(
+    () => ({
+      startPrice: state.upper_price,
+      endPrice: state.lower_price,
+      limitPrice: state.upper_limit_price,
+      // ChartPriceMapping.side is 1 | 2 and only selects the picker's color, so
+      // RANGE collapses onto the BUY color rather than growing the union.
+      side: state.side === LP_SIDE_SELL ? 2 : 1,
+      minSpread: 0,
+      activePickField: PICK_SLOT[state.activePickField ?? ""] ?? null,
+      extraLines:
+        state.lower_limit_price > 0
+          ? [
+              {
+                price: state.lower_limit_price,
+                label: "Lower limit",
+                color: getThemeColors().red,
+                lineStyle: "dotted" as const,
+                lineWidth: 1,
+              },
+            ]
+          : undefined,
+    }),
+    [
+      state.upper_price,
+      state.lower_price,
+      state.upper_limit_price,
+      state.lower_limit_price,
+      state.side,
+      state.activePickField,
+    ],
+  );
+
+  const buildPayload = (connectorName: string, tradingPair: string) => {
+    const config: Record<string, unknown> = {
+      // The NETWORK (solana-mainnet-beta), not the DEX — the API rejects
+      // `meteora/clmm` here with "Invalid network format". The DEX is lp_provider.
+      connector_name: connectorName,
+      lp_provider: state.lp_provider,
+      trading_pair: tradingPair,
+      pool_address: state.pool_address,
+      lower_price: state.lower_price,
+      upper_price: state.upper_price,
+      side: state.side,
+      base_amount: state.base_amount,
+      quote_amount: state.quote_amount,
+      keep_position: state.keep_position,
+    };
+    // Both default to null (no trigger); 0 is not a way to say "unset".
+    if (state.upper_limit_price > 0) config.upper_limit_price = state.upper_limit_price;
+    if (state.lower_limit_price > 0) config.lower_limit_price = state.lower_limit_price;
+    // strategyType is Meteora's alone — any other provider rejects extra_params.
+    if (isMeteoraProvider(state.lp_provider)) {
+      config.extra_params = { strategyType: Number(state.strategy_type) };
+    }
+    return { executor_type: "lp_executor" as const, config };
+  };
+
+  const save = () => saveDefaults(state);
+
+  const handleChartPriceSet = (field: "start" | "end" | "limit", price: number) => {
+    dispatch({ type: "SET_FIELD", field: SLOT_FIELD[field], value: price });
+    dispatch({ type: "SET_FIELD", field: "activePickField", value: null });
+  };
+
+  return {
+    state,
+    dispatch,
+    validation,
+    chartProps,
+    buildPayload,
+    save,
+    handleChartPriceSet,
+    pool,
+    poolFetching,
+  };
+}
+
+// ── Options ──
+
+const SIDE_OPTIONS: { value: LpSide; label: string; hint: string }[] = [
+  { value: LP_SIDE_RANGE, label: "Range", hint: "Both tokens, range around price" },
+  { value: LP_SIDE_BUY, label: "Buy", hint: "Quote only, range below price" },
+  { value: LP_SIDE_SELL, label: "Sell", hint: "Base only, range above price" },
+];
+
+const PROVIDER_OPTIONS = [
+  { value: "", label: "Select provider…" },
+  { value: "meteora/clmm", label: "Meteora (DLMM)" },
+  { value: "raydium/clmm", label: "Raydium (CLMM)" },
+  { value: "orca/clmm", label: "Orca (Whirlpools)" },
+  { value: "uniswap/clmm", label: "Uniswap V3" },
+  { value: "pancakeswap/clmm", label: "PancakeSwap V3" },
+];
+
+const STRATEGY_TYPE_OPTIONS = [
+  { value: "0", label: "Spot (uniform)" },
+  { value: "1", label: "Curve (concentrated)" },
+  { value: "2", label: "Bid-Ask (edges)" },
+];
+
+const RANGE_PCT_PRESETS = [0.01, 0.02, 0.05, 0.1, 0.2];
+
+function truncateAddress(address: string): string {
+  return address.length > 16
+    ? `${address.slice(0, 6)}…${address.slice(-6)}`
+    : address;
+}
+
+function formatPoolPrice(price: number): string {
+  if (price >= 1000) return price.toFixed(2);
+  if (price >= 1) return price.toFixed(4);
+  return price.toPrecision(6);
+}
+
+// ── Panel Component ──
+
+interface Props {
+  state: LPState;
+  dispatch: React.Dispatch<LPAction>;
+  validation: ExecutorValidation;
+  currentPrice: number | null;
+  pair?: string;
+  pool?: DexPoolInfo;
+  poolFetching?: boolean;
+}
+
+export function LPConfigPanel({
+  state,
+  dispatch,
+  validation,
+  currentPrice,
+  pair,
+  pool,
+  poolFetching,
+}: Props) {
+  const d = dispatch as FieldDispatch;
+
+  // A DEX pair's chart can be blank (no candles for the pool) while the pool's own
+  // price is known, so the resolved pool is a second source for the anchor.
+  const price = currentPrice && currentPrice > 0 ? currentPrice : pool?.current_price ?? null;
+
+  const baseAsset = pair?.split("-")[0] || pool?.base_symbol || "base";
+  const quoteAsset = pair?.split("-")[1] || pool?.quote_symbol || "quote";
+
+  // Anchor the range the first time a price is known. Not a reset: once the bounds
+  // are non-zero they are the user's, and only an explicit action moves them.
+  const unanchored = state.lower_price === 0 && state.upper_price === 0;
+  useEffect(() => {
+    if (price && price > 0 && unanchored) {
+      dispatch({ type: "AUTO_RANGE", price });
+    }
+  }, [price, unanchored]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const warnings = rangeWarnings(state, price);
+  const unsupported = !!pool && !pool.lp_supported;
+
+  return (
+    <div className="flex flex-col gap-4 overflow-y-auto p-3">
+      {/* Resolved pool */}
+      <div className="space-y-2">
+        <SectionHeader>Pool</SectionHeader>
+        {poolFetching && !pool ? (
+          <p className="text-[10px] text-[var(--color-text-muted)]">Resolving pool…</p>
+        ) : unsupported ? (
+          <div className="rounded border border-amber-400/30 bg-amber-400/10 p-2">
+            <p className="flex items-start gap-1 text-[10px] text-amber-400">
+              <AlertTriangle className="mt-px h-3 w-3 shrink-0" />
+              <span>
+                The deepest pool for this pair is on{" "}
+                <span className="font-mono">{pool?.dex_id ?? "an unknown venue"}</span>, which
+                is not a CLMM venue. Enter a pool address and provider by hand.
+              </span>
+            </p>
+          </div>
+        ) : pool?.pool_address ? (
+          <div className="flex flex-wrap items-center gap-1.5 text-[10px] text-[var(--color-text-muted)]">
+            <span className="rounded bg-[var(--color-surface-hover)] px-1.5 py-0.5 font-medium text-[var(--color-text)]">
+              {pool.dex_id}
+            </span>
+            <span className="font-mono" title={pool.pool_address}>
+              {truncateAddress(pool.pool_address)}
+            </span>
+            {pool.current_price != null && (
+              <span className="font-mono">
+                {formatPoolPrice(pool.current_price)} {quoteAsset}
+              </span>
+            )}
+            {state.poolTouched && (
+              <span className="rounded bg-[var(--color-primary)]/15 px-1.5 py-0.5 text-[var(--color-primary)]">
+                overridden
+              </span>
+            )}
+          </div>
+        ) : (
+          <p className="text-[10px] text-[var(--color-text-muted)]">
+            No pool found for this pair. Enter one by hand.
+          </p>
+        )}
+
+        <div>
+          <label className="mb-1 block text-xs text-[var(--color-text-muted)]">
+            Pool Address
+          </label>
+          <input
+            type="text"
+            value={state.pool_address}
+            onChange={(e) =>
+              d({ type: "SET_FIELD", field: "pool_address", value: e.target.value.trim() })
+            }
+            placeholder="Pool contract address"
+            spellCheck={false}
+            className="w-full rounded border border-[var(--color-border)] bg-[var(--color-bg)] px-2.5 py-1.5 font-mono text-[11px] text-[var(--color-text)] placeholder:text-[var(--color-text-muted)]/40 focus:border-[var(--color-primary)] focus:outline-none"
+          />
+        </div>
+        <SelectField
+          label="LP Provider"
+          value={state.lp_provider}
+          field="lp_provider"
+          dispatch={d}
+          options={PROVIDER_OPTIONS}
+        />
+      </div>
+
+      {/* Side */}
+      <div className="space-y-2">
+        <SectionHeader>Position Side</SectionHeader>
+        <div className="flex overflow-hidden rounded-md border border-[var(--color-border)]">
+          {SIDE_OPTIONS.map((opt) => (
+            <button
+              key={opt.value}
+              onClick={() => dispatch({ type: "SET_SIDE", value: opt.value, price })}
+              title={opt.hint}
+              className={`flex-1 px-2 py-1.5 text-[11px] font-medium transition-colors ${
+                state.side === opt.value
+                  ? "bg-[var(--color-primary)] text-white"
+                  : "bg-[var(--color-bg)] text-[var(--color-text-muted)] hover:bg-[var(--color-surface-hover)]"
+              }`}
+            >
+              {opt.label}
+            </button>
+          ))}
+        </div>
+        <p className="text-[10px] text-[var(--color-text-muted)]">
+          {SIDE_OPTIONS.find((o) => o.value === state.side)?.hint}
+        </p>
+      </div>
+
+      {/* Range */}
+      <div className="space-y-2.5">
+        <div className="flex items-center justify-between">
+          <SectionHeader>Range</SectionHeader>
+          {price != null && price > 0 && (
+            <button
+              onClick={() => dispatch({ type: "AUTO_RANGE", price })}
+              className="flex items-center gap-1 rounded border border-[var(--color-border)] bg-[var(--color-surface)] px-2 py-1 text-[10px] text-[var(--color-text-muted)] transition-colors hover:bg-[var(--color-surface-hover)]"
+            >
+              <Sparkles className="h-3 w-3" />
+              Auto
+            </button>
+          )}
+        </div>
+        <div className="flex overflow-hidden rounded-md border border-[var(--color-border)]">
+          {RANGE_PCT_PRESETS.map((pct) => (
+            <button
+              key={pct}
+              onClick={() => dispatch({ type: "SET_RANGE_PCT", value: pct, price })}
+              className={`flex-1 px-1.5 py-1 text-[10px] transition-colors ${
+                state.range_pct === pct
+                  ? "bg-[var(--color-primary)] text-white"
+                  : "bg-[var(--color-bg)] text-[var(--color-text-muted)] hover:bg-[var(--color-surface-hover)]"
+              }`}
+            >
+              {pct * 100}%
+            </button>
+          ))}
+        </div>
+        <PriceField
+          label="Upper Price"
+          value={state.upper_price}
+          field="upper_price"
+          activePickField={state.activePickField}
+          dispatch={d}
+          valid={state.upper_price > state.lower_price}
+        />
+        <PriceField
+          label="Lower Price"
+          value={state.lower_price}
+          field="lower_price"
+          activePickField={state.activePickField}
+          dispatch={d}
+          valid={state.lower_price > 0 && state.lower_price < state.upper_price}
+        />
+      </div>
+
+      {/* Amounts */}
+      <div className="space-y-2.5">
+        <SectionHeader>Amounts</SectionHeader>
+        <NumberField
+          label={`Base Amount (${baseAsset})`}
+          value={state.base_amount}
+          field="base_amount"
+          dispatch={d}
+          step={0.001}
+          min={0}
+        />
+        <NumberField
+          label={`Quote Amount (${quoteAsset})`}
+          value={state.quote_amount}
+          field="quote_amount"
+          dispatch={d}
+          step={0.001}
+          min={0}
+        />
+      </div>
+
+      {/* Auto-close triggers */}
+      <div className="space-y-2.5">
+        <SectionHeader>Auto-Close Triggers</SectionHeader>
+        <PriceField
+          label="Upper Limit"
+          value={state.upper_limit_price}
+          field="upper_limit_price"
+          activePickField={state.activePickField}
+          dispatch={d}
+          valid={state.upper_limit_price > state.upper_price}
+          hint="Close when price rises to this level"
+        />
+        <PriceField
+          label="Lower Limit"
+          value={state.lower_limit_price}
+          field="lower_limit_price"
+          activePickField={state.activePickField}
+          dispatch={d}
+          valid={
+            state.lower_limit_price > 0 && state.lower_limit_price < state.lower_price
+          }
+          hint="Close when price falls to this level"
+          pickable={false}
+        />
+        <p className="text-[10px] text-[var(--color-text-muted)]">
+          Both only fire while the position is out of range. Leave at 0 for no trigger.
+        </p>
+      </div>
+
+      <AdvancedSection
+        open={state.showAdvanced}
+        onToggle={() =>
+          d({ type: "SET_FIELD", field: "showAdvanced", value: !state.showAdvanced })
+        }
+      >
+        <ToggleField
+          label="Keep Position"
+          value={state.keep_position}
+          field="keep_position"
+          dispatch={d}
+        />
+        <p className="text-[10px] text-[var(--color-text-muted)]">
+          On close, keep the net token change as a spot position instead of swapping
+          back to {quoteAsset}. This sets the config field; stopping from the
+          executors table asks again.
+        </p>
+        {isMeteoraProvider(state.lp_provider) && (
+          <SelectField
+            label="Meteora Strategy"
+            value={state.strategy_type}
+            field="strategy_type"
+            dispatch={d}
+            options={STRATEGY_TYPE_OPTIONS}
+          />
+        )}
+      </AdvancedSection>
+
+      <ValidationMessages errors={validation.errors} warnings={warnings} />
+    </div>
+  );
+}
diff --git a/frontend/src/components/executor/fields.tsx b/frontend/src/components/executor/fields.tsx
index 13ebb198..90c3955f 100644
--- a/frontend/src/components/executor/fields.tsx
+++ b/frontend/src/components/executor/fields.tsx
@@ -21,6 +21,7 @@ export function PriceField({
   dispatch,
   valid,
   hint,
+  pickable = true,
 }: {
   label: string;
   value: number;
@@ -29,6 +30,12 @@ export function PriceField({
   dispatch: FieldDispatch;
   valid: boolean;
   hint?: string;
+  /**
+   * Whether this price can be picked off the chart. The chart carries exactly
+   * three pick slots (start/end/limit), so a panel with a fourth price offers no
+   * crosshair for it rather than a button that does nothing.
+   */
+  pickable?: boolean;
 }) {
   const isActive = activePickField === field;
   const id = useId();
@@ -71,6 +78,7 @@ export function PriceField({
               : "border-[var(--color-border)] focus:border-[var(--color-primary)]"
           }`}
         />
+        {pickable && (
         <button
           onClick={() =>
             dispatch({
@@ -88,6 +96,7 @@ export function PriceField({
         >
           <Crosshair className="h-3.5 w-3.5" />
         </button>
+        )}
       </div>
       {hint && <p className="mt-0.5 text-[10px] text-[var(--color-text-muted)]">{hint}</p>}
     </div>
diff --git a/frontend/src/components/executor/types.ts b/frontend/src/components/executor/types.ts
index 837a091d..1b44c049 100644
--- a/frontend/src/components/executor/types.ts
+++ b/frontend/src/components/executor/types.ts
@@ -1,11 +1,12 @@
-export type ExecutorType = "grid" | "position" | "order" | "dca";
-
-export const EXECUTOR_TYPES: { value: ExecutorType; label: string; icon: string }[] = [
-  { value: "grid", label: "Grid", icon: "Grid3X3" },
-  { value: "position", label: "Position", icon: "TrendingUp" },
-  { value: "order", label: "Order", icon: "ArrowUpDown" },
-  { value: "dca", label: "DCA", icon: "Layers" },
-];
+/**
+ * An executor type the trade panel implements a tab for.
+ *
+ * This is the single union: `connectorCapabilities` reports which of these a venue
+ * supports, `TYPE_TABS` / `TYPE_LABELS` render them, and four switches in
+ * `CreateExecutor` are exhaustive over it — so adding a member here is what makes
+ * the compiler point at every site that has to learn about it.
+ */
+export type ExecutorType = "grid" | "position" | "order" | "dca" | "lp";
 
 export interface ExtraLine {
   price: number;
diff --git a/frontend/src/components/trade/TradeChart.tsx b/frontend/src/components/trade/TradeChart.tsx
index a73f8659..07d22ada 100644
--- a/frontend/src/components/trade/TradeChart.tsx
+++ b/frontend/src/components/trade/TradeChart.tsx
@@ -349,11 +349,22 @@ export function TradeChart({
           detailRows += `<div style="display:flex;justify-content:space-between;gap:12px"><span style="color:#6b7994">${escapeHtml(label)}</span><span style="font-family:monospace;${color ? `color:${color}` : ""}">${escapeHtml(value)}</span></div>`;
         };
 
-        // Grid-specific details
-        if (o.type === "grid" && o.gridBox) {
-          addRow("Start Price", fmtPrice(o.gridBox.startPrice));
-          addRow("End Price", fmtPrice(o.gridBox.endPrice));
-          if (o.gridBox.limitPrice) addRow("Limit Price", fmtPrice(o.gridBox.limitPrice));
+        // Range-box details. Any executor drawn as a box describes itself by its
+        // bounds, not by an entry→exit pair; only the labels differ per type.
+        if (o.gridBox) {
+          if (o.type === "lp") {
+            // startPrice is the box's upper edge (see computeLpOverlay).
+            addRow("Upper Price", fmtPrice(o.gridBox.startPrice));
+            addRow("Lower Price", fmtPrice(o.gridBox.endPrice));
+            const cfgLower = Number(cfg.lower_limit_price);
+            if (o.gridBox.limitPrice) addRow("Upper Limit", fmtPrice(o.gridBox.limitPrice));
+            if (cfgLower > 0) addRow("Lower Limit", fmtPrice(cfgLower));
+            if (cfg.lp_provider != null) addRow("Provider", String(cfg.lp_provider));
+          } else {
+            addRow("Start Price", fmtPrice(o.gridBox.startPrice));
+            addRow("End Price", fmtPrice(o.gridBox.endPrice));
+            if (o.gridBox.limitPrice) addRow("Limit Price", fmtPrice(o.gridBox.limitPrice));
+          }
         } else if (o.entryPrice && o.entryPrice > 0) {
           addRow("Entry", fmtPrice(o.entryPrice));
           if (o.exitPrice && o.exitPrice > 0 && o.exitPrice !== o.entryPrice) {
diff --git a/frontend/src/lib/api.ts b/frontend/src/lib/api.ts
index 0d9d9bb4..9982cd7b 100644
--- a/frontend/src/lib/api.ts
+++ b/frontend/src/lib/api.ts
@@ -258,6 +258,25 @@ export interface MarketPrice {
   best_ask: number;
 }
 
+/**
+ * The pool a DEX pair trades in — the same one the chart's candles come from.
+ *
+ * `lp_supported` is false, with a null `lp_provider`, whenever the deepest pool is
+ * not one an `lp_executor` can add liquidity to (a router, a plain AMM, Uniswap
+ * v4). That is a normal answer, not an error: the LP panel responds by asking for
+ * a pool address by hand. `current_price` is the base priced in quote — the scale
+ * every LP bound is expressed in — and is null when GeckoTerminal reports no price.
+ */
+export interface DexPoolInfo {
+  pool_address: string | null;
+  dex_id: string | null;
+  lp_provider: string | null;
+  lp_supported: boolean;
+  current_price: number | null;
+  base_symbol: string | null;
+  quote_symbol: string | null;
+}
+
 export interface OrderBookLevel {
   price: number;
   amount: number;
@@ -1185,6 +1204,11 @@ export const api = {
       `/api/v1/servers/${encodeURIComponent(server)}/market/gateway-networks`,
     ).then((r) => r.networks),
 
+  getDexPool: (server: string, connector: string, pair: string) =>
+    apiFetch<DexPoolInfo>(
+      `/api/v1/servers/${encodeURIComponent(server)}/market/dex-pool?connector=${encodeURIComponent(connector)}&trading_pair=${encodeURIComponent(pair)}`,
+    ),
+
   getPrice: (server: string, connector: string, pair: string) =>
     apiFetch<MarketPrice>(
       `/api/v1/servers/${encodeURIComponent(server)}/market/prices?connector=${encodeURIComponent(connector)}&trading_pair=${encodeURIComponent(pair)}`,
diff --git a/frontend/src/lib/connector-capabilities.ts b/frontend/src/lib/connector-capabilities.ts
index 4998f770..3d79c2fa 100644
--- a/frontend/src/lib/connector-capabilities.ts
+++ b/frontend/src/lib/connector-capabilities.ts
@@ -19,18 +19,10 @@ import type { ExecutorType } from "@/components/executor/types";
 
 export type ConnectorKind = "cex" | "dex";
 
-/**
- * An executor type a *venue* supports, which is not yet the same set as the tabs
- * the panel implements: `"lp"` has no entry in `TYPE_TABS` until FEAT-042 adds
- * one. Keeping it out of `ExecutorType` leaves that union meaning "a tab this
- * panel can render", so the exhaustive switches over it stay exhaustive.
- */
-export type SupportedExecutorType = ExecutorType | "lp";
-
 export interface ConnectorCapabilities {
   kind: ConnectorKind;
   /** Executor types this venue supports. */
-  executorTypes: SupportedExecutorType[];
+  executorTypes: ExecutorType[];
   /** Allowed `execution_strategy` values (subset of OrderConfigPanel's options). */
   orderStrategies: string[];
   /** Whether `/market/order-book` and `/market/tickers` answer — depth + markets tabs. */
@@ -48,9 +40,8 @@ const CEX_CAPABILITIES: ConnectorCapabilities = {
 };
 
 // A gateway swap has no resting order book to post to, so MARKET is the only
-// execution strategy that means anything. `lp` is listed from day one; the tab
-// list filters against TYPE_TABS, so it simply finds no entry until FEAT-042
-// adds one.
+// execution strategy that means anything. `lp` is the CLMM liquidity position —
+// the second, and only other, executor a gateway network supports.
 const DEX_CAPABILITIES: ConnectorCapabilities = {
   kind: "dex",
   executorTypes: ["order", "lp"],
diff --git a/frontend/src/lib/executor-overlays.ts b/frontend/src/lib/executor-overlays.ts
index 04c70245..ef0e087c 100644
--- a/frontend/src/lib/executor-overlays.ts
+++ b/frontend/src/lib/executor-overlays.ts
@@ -283,6 +283,82 @@ function computeGridOverlay(executor: ExecutorInfo): ExecutorOverlay {
   };
 }
 
+// ── LP Executor Overlay ──
+
+/**
+ * A CLMM liquidity position, drawn as the grid it structurally is.
+ *
+ * `lower_price` / `upper_price` are the range the position earns fees in, and the
+ * schema itself describes `upper_limit_price` / `lower_limit_price` as
+ * "grid-executor style" auto-close triggers. That is a one-to-one match with
+ * `GridBox`, and `TradeChart` draws boxes without ever reading `type` — so no new
+ * drawing code is involved, only a second producer of the same struct.
+ */
+function computeLpOverlay(executor: ExecutorInfo): ExecutorOverlay {
+  const customInfo = executor.custom_info || {};
+  const config = executor.config || {};
+  const side = normSide(String(customInfo.side || executor.side || config.side));
+
+  // custom_info wins: a CLMM position is snapped to the venue's bins, so the
+  // on-chain bounds are not the requested ones, and the box has to show where the
+  // liquidity actually sits. Same precedence handlers/dex/liquidity.py applies when
+  // it reads positions back.
+  const num = (v: unknown) => {
+    const n = Number(v);
+    return Number.isFinite(n) ? n : 0;
+  };
+  const lower = num(customInfo.lower_price ?? customInfo.price_lower ?? config.lower_price);
+  const upper = num(customInfo.upper_price ?? customInfo.price_upper ?? config.upper_price);
+  const upperLimit = num(customInfo.upper_limit_price ?? config.upper_limit_price);
+  const lowerLimit = num(customInfo.lower_limit_price ?? config.lower_limit_price);
+
+  const start = executor.timestamp > 0 ? executor.timestamp : Math.floor(Date.now() / 1000);
+  const end = executor.close_timestamp > 0 ? executor.close_timestamp : Math.floor(Date.now() / 1000);
+
+  let gridBox: GridBox | undefined;
+  if (lower > 0 && upper > 0 && start > 0) {
+    gridBox = {
+      startTime: start,
+      endTime: end,
+      // startPrice is the box's dashed edge and endPrice its solid one; the grid
+      // overlay puts start_price (the far bound) first, so upper goes first here.
+      startPrice: upper,
+      endPrice: lower,
+      limitPrice: upperLimit > 0 ? upperLimit : undefined,
+      color: pnlHexColor(executor.pnl >= 0 ? 1 : -1),
+    };
+  }
+
+  // Both triggers, as full-width lines. TradeChart only draws these for a running
+  // or selected executor, which is exactly when they are actionable.
+  const lines: PriceLine[] = [];
+  if (upperLimit > 0) {
+    lines.push({ price: upperLimit, label: "Upper limit", color: getThemeColors().red, style: "dotted" });
+  }
+  if (lowerLimit > 0) {
+    lines.push({ price: lowerLimit, label: "Lower limit", color: getThemeColors().red, style: "dotted" });
+  }
+
+  return {
+    executorId: executor.id,
+    type: "lp",
+    side,
+    status: executor.status,
+    closeType: executor.close_type,
+    pnl: executor.pnl,
+    pnlPct: executor.net_pnl_pct,
+    volume: executor.volume,
+    fees: executor.cum_fees_quote,
+    priceLines: lines,
+    markers: [],
+    gridBox,
+    timeRange: { start, end },
+    config: executor.config,
+    entryPrice: lower,
+    exitPrice: upper,
+  };
+}
+
 // ── Order Executor Overlay ──
 
 function computeOrderOverlay(executor: ExecutorInfo): ExecutorOverlay {
@@ -487,6 +563,8 @@ export function computeExecutorOverlay(executor: ExecutorInfo): ExecutorOverlay
       return computeGridOverlay(executor);
     case "order":
       return computeOrderOverlay(executor);
+    case "lp":
+      return computeLpOverlay(executor);
     default:
       return computeGenericOverlay(executor);
   }
diff --git a/frontend/src/pages/CreateExecutor.tsx b/frontend/src/pages/CreateExecutor.tsx
index 51e925a6..3603bdfc 100644
--- a/frontend/src/pages/CreateExecutor.tsx
+++ b/frontend/src/pages/CreateExecutor.tsx
@@ -7,6 +7,7 @@ import {
   BarChart3,
   CheckCircle,
   Copy,
+  Droplets,
   Grid3X3,
   Layers,
   List,
@@ -28,6 +29,7 @@ import { GridConfigPanel, useGridValidation } from "@/components/grid/GridConfig
 import { PositionConfigPanel, usePositionConfig } from "@/components/executor/PositionConfigPanel";
 import { OrderConfigPanel, useOrderConfig } from "@/components/executor/OrderConfigPanel";
 import { DCAConfigPanel, useDCAConfig } from "@/components/executor/DCAConfigPanel";
+import { LPConfigPanel, useLpConfig } from "@/components/executor/LPConfigPanel";
 import { TradeBottomPane } from "@/components/trade/TradeBottomPane";
 import { useCandleStore } from "@/hooks/useCandleStore";
 import { useServer } from "@/hooks/useServer";
@@ -56,6 +58,7 @@ const TYPE_TABS: { value: ExecutorType; label: string; icon: React.ReactNode }[]
   { value: "position", label: "Position", icon: <TrendingUp className="h-3.5 w-3.5" /> },
   { value: "grid", label: "Grid", icon: <Grid3X3 className="h-3.5 w-3.5" /> },
   { value: "dca", label: "DCA", icon: <Layers className="h-3.5 w-3.5" /> },
+  { value: "lp", label: "LP", icon: <Droplets className="h-3.5 w-3.5" /> },
 ];
 
 const TYPE_LABELS: Record<ExecutorType, string> = {
@@ -63,6 +66,7 @@ const TYPE_LABELS: Record<ExecutorType, string> = {
   position: "Position Executor",
   order: "Order Executor",
   dca: "DCA Executor",
+  lp: "LP Executor",
 };
 
 // ── Page ──
@@ -175,6 +179,11 @@ export function CreateExecutor() {
     [connector, gatewayNetworks],
   );
 
+  // Pool resolution only means something for a gateway network, so the query is off
+  // for a CEX rather than asking about a pair that has no pool. Declared above the
+  // connector/pair propagation effects that dispatch into it.
+  const lpConfig = useLpConfig(server ?? null, connector, pair, caps.kind === "dex");
+
   // WS for executor data (candle streams are managed by candleStore)
   const wsChannels = useMemo(
     () => server ? [`executors:${server}`] : [],
@@ -241,12 +250,14 @@ export function CreateExecutor() {
     positionConfig.dispatch({ type: "SET_CONNECTOR", value: connector });
     orderConfig.dispatch({ type: "SET_CONNECTOR", value: connector });
     dcaConfig.dispatch({ type: "SET_CONNECTOR", value: connector });
+    lpConfig.dispatch({ type: "SET_CONNECTOR", value: connector });
   }, [connector]); // eslint-disable-line react-hooks/exhaustive-deps
 
   useEffect(() => {
     positionConfig.dispatch({ type: "SET_PAIR", value: pair });
     orderConfig.dispatch({ type: "SET_PAIR", value: pair });
     dcaConfig.dispatch({ type: "SET_PAIR", value: pair });
+    lpConfig.dispatch({ type: "SET_PAIR", value: pair });
   }, [pair]); // eslint-disable-line react-hooks/exhaustive-deps
 
   // Current price. /market/prices is a Hummingbot API call with no DEX answer, so a
@@ -272,6 +283,7 @@ export function CreateExecutor() {
       ? (sharedCandles[sharedCandles.length - 1]?.close ?? null)
       : (priceData?.mid_price ?? null);
 
+
   // Price precision
   const pricePrecision = useMemo(() => {
     if (!rulesData?.rules) return undefined;
@@ -293,8 +305,9 @@ export function CreateExecutor() {
       case "position": return positionConfig.validation;
       case "order": return orderConfig.validation;
       case "dca": return dcaConfig.validation;
+      case "lp": return lpConfig.validation;
     }
-  }, [executorType, gridValidation, positionConfig.validation, orderConfig.validation, dcaConfig.validation]);
+  }, [executorType, gridValidation, positionConfig.validation, orderConfig.validation, dcaConfig.validation, lpConfig.validation]);
 
   // Chart props depend on active type
   const chartProps = useMemo(() => {
@@ -311,8 +324,9 @@ export function CreateExecutor() {
       case "position": return positionConfig.chartProps;
       case "order": return orderConfig.chartProps;
       case "dca": return dcaConfig.chartProps;
+      case "lp": return lpConfig.chartProps;
     }
-  }, [executorType, gridState, positionConfig.chartProps, orderConfig.chartProps, dcaConfig.chartProps]);
+  }, [executorType, gridState, positionConfig.chartProps, orderConfig.chartProps, dcaConfig.chartProps, lpConfig.chartProps]);
 
   // Chart price set handler
   const handlePriceSet = useMemo(
@@ -331,6 +345,9 @@ export function CreateExecutor() {
         case "dca":
           dcaConfig.handleChartPriceSet(field, price);
           break;
+        case "lp":
+          lpConfig.handleChartPriceSet(field, price);
+          break;
       }
     },
     [executorType], // eslint-disable-line react-hooks/exhaustive-deps
@@ -381,6 +398,10 @@ export function CreateExecutor() {
         case "dca":
           payload = dcaConfig.buildPayload(connector, pair, isSpot);
           break;
+        case "lp":
+          // No isSpot: an LP position has no leverage, and connector is the network.
+          payload = lpConfig.buildPayload(connector, pair);
+          break;
       }
 
       return api.createExecutor(server, payload);
@@ -392,6 +413,7 @@ export function CreateExecutor() {
         case "position": positionConfig.save(); break;
         case "order": orderConfig.save(); break;
         case "dca": dcaConfig.save(); break;
+        case "lp": lpConfig.save(); break;
       }
       // Show success modal
       setSuccessInfo({ id: data.executor_id, type: executorType, connector, pair });
@@ -633,6 +655,9 @@ export function CreateExecutor() {
                 {executorType === "dca" && (
                   <DCAConfigPanel state={dcaConfig.state} dispatch={dcaConfig.dispatch} validation={dcaConfig.validation} currentPrice={currentPrice} isSpot={isSpot} pair={pair} />
                 )}
+                {executorType === "lp" && (
+                  <LPConfigPanel state={lpConfig.state} dispatch={lpConfig.dispatch} validation={lpConfig.validation} currentPrice={currentPrice} pair={pair} pool={lpConfig.pool} poolFetching={lpConfig.poolFetching} />
+                )}
               </div>
 
               {/* Sticky Create Footer */}

From 5e16abb004b5c578272a0c6eb049b26d9b93e10d Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Tue, 11 Aug 2026 14:48:39 +0300
Subject: [PATCH 005/116] (arch) normalize backtest sides server-side, drop the
 TypeScript copy (ARCH-121)

The backtest payload was the one executor wire that never ran through
normalize_executor_side, so the dashboard carried its own TypeScript
reimplementation of the rule (normalizeSide) plus a partial inline copy in
TradeBottomPane. normalize_backtest_task now applies the canonical normalizer at
every boundary where a backtest envelope enters Condor -- the poll loop and the
three web reads -- so old saved results normalize on the way out too, and the
frontend just reads the side.
---
 condor/backtesting.py                         | 30 ++++++++-
 condor/web/routes/backtesting.py              |  9 +--
 .../src/components/trade/TradeBottomPane.tsx  |  2 +-
 frontend/src/lib/backtest.ts                  | 14 +---
 tests/test_side_normalization.py              | 67 +++++++++++++++++++
 5 files changed, 105 insertions(+), 17 deletions(-)

diff --git a/condor/backtesting.py b/condor/backtesting.py
index 5a099816..28aa7e07 100644
--- a/condor/backtesting.py
+++ b/condor/backtesting.py
@@ -15,6 +15,8 @@
 import time
 from typing import Any
 
+from condor.fetchers.executors import normalize_executor_side
+
 logger = logging.getLogger(__name__)
 
 # Polling defaults for run_and_save. The timeout is deliberately generous: a caller
@@ -57,6 +59,32 @@ def coerce_controller_config(config: dict) -> dict:
     return out
 
 
+def normalize_backtest_task(task: Any) -> Any:
+    """Normalize the executor sides inside a backtest envelope, in place.
+
+    The backtesting engine reports a side the way the raw API does -- ``1``,
+    ``TradeType.BUY``, ``LONG`` -- and this payload is the one wire that never went
+    through :func:`condor.fetchers.executors.normalize_executor_side`, so the
+    dashboard carried a TypeScript reimplementation of the rule to render a backtest
+    (ARCH-121). Applying the canonical normalizer here makes the backtest wire match
+    the executor wire, leaving exactly one definition of the rule.
+
+    Accepts either the task envelope (``{status, config, result, ...}``) or a bare
+    result payload, and only rewrites a ``side`` that is actually present, so it adds
+    nothing to the raw payload the dashboard also renders as JSON.
+    """
+    if not isinstance(task, dict):
+        return task
+    result = task.get("result")
+    payload = result if isinstance(result, dict) else task
+    executors = payload.get("executors")
+    if isinstance(executors, list):
+        for ex in executors:
+            if isinstance(ex, dict) and "side" in ex:
+                ex["side"] = normalize_executor_side(ex["side"])
+    return task
+
+
 async def run_and_save(
     client,
     server: str,
@@ -130,7 +158,7 @@ async def _poll_task(
                 f"Backtest {task_id} returned an unreadable task: {task}"
             )
         if task.get("status") in _TERMINAL:
-            return task
+            return normalize_backtest_task(task)
         if time.monotonic() >= deadline:
             raise BacktestError(
                 f"Backtest {task_id} is still {task.get('status') or 'running'} after "
diff --git a/condor/web/routes/backtesting.py b/condor/web/routes/backtesting.py
index eace66f7..d43d82d4 100644
--- a/condor/web/routes/backtesting.py
+++ b/condor/web/routes/backtesting.py
@@ -6,7 +6,7 @@
 from pydantic import BaseModel
 
 from condor.backtest_store import get_backtest_store
-from condor.backtesting import coerce_controller_config
+from condor.backtesting import coerce_controller_config, normalize_backtest_task
 from condor.web.auth import get_current_user
 from condor.web.models import WebUser
 from config_manager import get_config_manager
@@ -96,6 +96,7 @@ async def list_backtest_tasks(
             tid = task.get("task_id", "")
             if store.get_result(tid):
                 task["saved"] = True
+            normalize_backtest_task(task)
 
     return live_tasks
 
@@ -122,14 +123,14 @@ async def get_backtest_task(
             store.save_result(name, task_id, result)
             result["saved"] = True
 
-        return result
+        return normalize_backtest_task(result)
     except Exception:
         pass
 
     # Fallback to saved
     saved = store.get_result(task_id)
     if saved:
-        return {**saved, "saved": True}
+        return normalize_backtest_task({**saved, "saved": True})
 
     raise HTTPException(status_code=404, detail="Task not found")
 
@@ -168,7 +169,7 @@ async def list_saved_results(
         raise HTTPException(status_code=403, detail="No access")
 
     store = get_backtest_store()
-    return store.list_results(name)
+    return [normalize_backtest_task(entry) for entry in store.list_results(name)]
 
 
 @router.delete("/servers/{name}/backtesting/saved/{task_id}")
diff --git a/frontend/src/components/trade/TradeBottomPane.tsx b/frontend/src/components/trade/TradeBottomPane.tsx
index b9e4995f..ae3b307f 100644
--- a/frontend/src/components/trade/TradeBottomPane.tsx
+++ b/frontend/src/components/trade/TradeBottomPane.tsx
@@ -496,7 +496,7 @@ export function TradeBottomPane({
                       const active = isExecutorActive(ex.status);
                       const stopping = stoppingIds.has(ex.id);
                       const side = ex.side?.toUpperCase();
-                      const isBuy = side === "BUY" || side === "1";
+                      const isBuy = side === "BUY";
                       const borderColor = active ? "var(--color-primary)" : ex.pnl >= 0 ? "var(--color-green)" : "var(--color-red)";
                       const isSelected = selectedExecutorId === ex.id;
                       const entry = getEntryPrice(ex);
diff --git a/frontend/src/lib/backtest.ts b/frontend/src/lib/backtest.ts
index 8a718ac8..68642d6f 100644
--- a/frontend/src/lib/backtest.ts
+++ b/frontend/src/lib/backtest.ts
@@ -168,7 +168,9 @@ export function extractResults(taskResults: Record<string, unknown>): BacktestDa
           id: String(e.id ?? e.executor_id ?? ""),
           timestamp: (e.timestamp ?? 0) as number,
           closeTimestamp: (e.close_timestamp ?? 0) as number,
-          side: normalizeSide(e.side),
+          // Already canonical BUY/SELL: the backtest route runs the payload through
+          // the same `normalize_executor_side` the executor wire uses (ARCH-121).
+          side: String(e.side ?? ""),
           closeType: String(e.close_type ?? ""),
           netPnlQuote: (e.net_pnl_quote ?? 0) as number,
           filledAmountQuote: (e.filled_amount_quote ?? 0) as number,
@@ -215,13 +217,3 @@ export function extractResults(taskResults: Record<string, unknown>): BacktestDa
     raw: taskResults,
   };
 }
-
-export function normalizeSide(side: unknown): string {
-  if (typeof side === "string") {
-    if (side === "1" || side.toUpperCase() === "BUY" || side === "TradeType.BUY") return "BUY";
-    if (side === "2" || side.toUpperCase() === "SELL" || side === "TradeType.SELL") return "SELL";
-    return side;
-  }
-  if (typeof side === "number") return side === 1 ? "BUY" : "SELL";
-  return String(side ?? "");
-}
diff --git a/tests/test_side_normalization.py b/tests/test_side_normalization.py
index ef2d5b3a..5714c8c2 100644
--- a/tests/test_side_normalization.py
+++ b/tests/test_side_normalization.py
@@ -13,6 +13,7 @@
 import pytest
 
 from condor.agents.performance import _executor_row
+from condor.backtesting import normalize_backtest_task
 from condor.fetchers.executors import normalize_executor_side
 
 REPO_ROOT = pathlib.Path(__file__).resolve().parent.parent
@@ -85,3 +86,69 @@ def test_no_private_side_normalizer_survives():
     ]
 
     assert offenders == []
+
+
+# ── ARCH-121: the backtest wire carries the same normalized side ──
+
+
+def test_backtest_task_sides_are_normalized_in_the_envelope():
+    """The dashboard reads ``task["result"]["executors"][i]["side"]`` verbatim now."""
+    task = {
+        "task_id": "t1",
+        "status": "completed",
+        "result": {
+            "executors": [
+                {"id": "e1", "side": "TradeType.BUY"},
+                {"id": "e2", "side": 2},
+                {"id": "e3", "side": "SHORT"},
+                {"id": "e4", "side": "1"},
+            ]
+        },
+    }
+
+    normalize_backtest_task(task)
+
+    assert [e["side"] for e in task["result"]["executors"]] == [
+        "BUY",
+        "SELL",
+        "SELL",
+        "BUY",
+    ]
+
+
+def test_backtest_payload_without_an_envelope_is_normalized_too():
+    """A bare result payload — what a caller holding only ``result`` passes in."""
+    payload = {"executors": [{"id": "e1", "side": "sell"}]}
+
+    assert normalize_backtest_task(payload)["executors"][0]["side"] == "SELL"
+
+
+def test_backtest_normalization_adds_no_side_key():
+    """The raw payload is rendered as JSON in the dashboard: do not invent fields."""
+    task = {"result": {"executors": [{"id": "e1"}]}}
+
+    normalize_backtest_task(task)
+
+    assert task["result"]["executors"] == [{"id": "e1"}]
+
+
+@pytest.mark.parametrize("task", [None, "nope", {}, {"result": {"executors": "nope"}}])
+def test_backtest_normalization_tolerates_a_payload_without_executors(task):
+    """A pending/failed task has no executors list; the route still returns it."""
+    assert normalize_backtest_task(task) == task
+
+
+def test_no_typescript_copy_of_the_side_rule_survives():
+    """ARCH-121: ``normalizeSide`` was a second definition of the rule, in TypeScript.
+
+    Deleted once the backtest route started emitting a normalized side. If it comes
+    back, the rule has two definitions in two languages again, free to drift.
+    """
+    src = REPO_ROOT / "frontend" / "src"
+    offenders = [
+        str(path.relative_to(REPO_ROOT))
+        for path in src.rglob("*.ts*")
+        if "function normalizeSide" in path.read_text()
+    ]
+
+    assert offenders == []

From 476764ae0dee3add185d42a5003986e94c51a651 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Tue, 11 Aug 2026 17:27:08 +0300
Subject: [PATCH 006/116] Serve venue traits instead of a CEX/DEX binary

`fetch_gateway_networks` handed the trade panel one fact -- "this connector is a
chartable gateway network" -- and the panel used it to answer four different
questions: which executor tabs exist, which execution strategies exist, whether
the Hummingbot market endpoints are called, and where the current price comes
from. Those questions do not have a common answer.

`xrpl` is the proof. It is a first-class Hummingbot connector with a real order
book whose charts nonetheless come from GeckoTerminal, so it lives in
NETWORK_TO_GECKO -- one of the two sets the gateway list was intersected from.
It classifies correctly today only because Gateway happens not to report it; the
day a Gateway version does, it would silently lose its order book, its trading
rules, its pair list and every strategy but MARKET, and gain an LP tab its AMM
cannot honor. Nothing failed loudly when that happened, and nothing prevented it.

`fetch_venues` replaces it with the traits themselves, one authority each:
`hummingbot_market_data` from the credentialed connector list (credentials are
per connector, so a venue in both lists IS a Hummingbot connector -- that is the
xrpl guarantee, expressed in exactly one place), and `clmm_lp` from
`network_has_clmm` over FEAT-042's _CLMM_VENUES rather than from gateway
membership. The candle source stays server-side, where it already forks and where
no UI decision needs it.

`GET /market/venues` and ServerDataType.VENUES replace the gateway-networks
endpoint and data type shipped two commits ago; the trade panel was their only
consumer. The VENUES cadence follows CONNECTORS, not the "chains change ~never"
one, because the credentialed list is now an input and changes when keys are added.

A gateway failure degrades to the credentialed venues instead of re-raising:
losing the DEX half must not empty the whole dropdown. It re-raises under strict
only when that would leave nothing, so an empty list is still never cached.
---
 condor/fetchers/__init__.py            |   4 +-
 condor/fetchers/connectors.py          | 100 +++++--
 condor/server_data_service.py          |  17 +-
 condor/web/routes/market.py            |  27 +-
 handlers/dex/pool_data.py              |  14 +
 tests/test_fetcher_gateway_networks.py | 184 ------------
 tests/test_fetcher_venues.py           | 395 +++++++++++++++++++++++++
 7 files changed, 515 insertions(+), 226 deletions(-)
 delete mode 100644 tests/test_fetcher_gateway_networks.py
 create mode 100644 tests/test_fetcher_venues.py

diff --git a/condor/fetchers/__init__.py b/condor/fetchers/__init__.py
index 6241959d..defd2589 100644
--- a/condor/fetchers/__init__.py
+++ b/condor/fetchers/__init__.py
@@ -41,7 +41,7 @@
 from condor.fetchers.connectors import (
     fetch_connectors,
     fetch_available_cex_connectors,
-    fetch_gateway_networks,
+    fetch_venues,
     is_cex_connector,
 )
 from condor.fetchers.executors import (
@@ -75,7 +75,7 @@
     "fetch_trading_rules",
     "fetch_connectors",
     "fetch_available_cex_connectors",
-    "fetch_gateway_networks",
+    "fetch_venues",
     "is_cex_connector",
     "fetch_executors",
     "fetch_all_executors",
diff --git a/condor/fetchers/connectors.py b/condor/fetchers/connectors.py
index 0f4a975b..d15db9f5 100644
--- a/condor/fetchers/connectors.py
+++ b/condor/fetchers/connectors.py
@@ -1,7 +1,7 @@
 """Fetch connector information from Hummingbot API."""
 
 import logging
-from typing import List
+from typing import Dict, List
 
 from condor.fetchers._identifiers import validate_identifier
 
@@ -35,34 +35,25 @@ def _network_id(item) -> str:
     return str(item)
 
 
-async def fetch_gateway_networks(client, strict: bool = False, **_kw) -> List[str]:
-    """Gateway networks that Condor can chart (subset of ``NETWORK_TO_GECKO``).
+async def _chartable_gateway_networks(client) -> List[str]:
+    """Gateway networks Condor can chart: ``list_networks()`` ∩ ``NETWORK_TO_GECKO``.
 
     The intersection is the point: a network is only offered to the trade panel if
     ``dex_candles.uses_gecko_candles`` will answer for it, so selecting one can
     never produce an empty chart. Do not widen this to every gateway network.
 
-    Args:
-        strict: Raise when the gateway request itself fails, instead of reporting
-            that no networks exist. Callers that cache the answer want the
-            distinction: an unreachable gateway is worth retrying, and must not be
-            cached as "this server has no DEX".
+    Raises whatever the gateway request raises — the caller decides how much of the
+    answer a gateway failure is allowed to take down.
     """
     # Lazy, like condor.dex_candles.uses_gecko_candles — condor.fetchers must not
     # import handlers at module scope.
     from handlers.dex.pool_data import NETWORK_TO_GECKO
 
-    try:
-        response = await client.gateway.list_networks()
-        networks = (response or {}).get("networks") or []
-        return sorted(
-            {n for n in (_network_id(i) for i in networks) if n in NETWORK_TO_GECKO}
-        )
-    except Exception as e:
-        if strict:
-            raise
-        logger.error("Error fetching gateway networks: %s", e, exc_info=True)
-        return []
+    response = await client.gateway.list_networks()
+    networks = (response or {}).get("networks") or []
+    return sorted(
+        {n for n in (_network_id(i) for i in networks) if n in NETWORK_TO_GECKO}
+    )
 
 
 async def fetch_available_cex_connectors(
@@ -103,3 +94,74 @@ async def fetch_available_cex_connectors(
             raise
         logger.error("Error fetching connectors: %s", e, exc_info=True)
         return []
+
+
+async def fetch_venues(
+    client, account_name: str = "master_account", strict: bool = False, **_kw
+) -> List[Dict]:
+    """Venues the trade panel can offer, each with its independent traits.
+
+    Returns ``[{"name", "hummingbot_market_data", "clmm_lp"}, ...]`` sorted by name.
+    The two traits are *independent facts about the venue*, each with exactly one
+    authority, because the panel's four decisions (which executor tabs, which
+    execution strategies, whether the order-book/rules/price endpoints are called,
+    where the current price comes from) are four different questions. Answering them
+    from a single ``cex``/``dex`` membership test is what this shape replaces.
+
+    ``hummingbot_market_data``: the venue came from the credentialed connector list.
+    Credentials are per Hummingbot connector, so ``solana-mainnet-beta`` can never
+    appear there and presence is positive evidence that ``/market/trading-rules``,
+    ``/market/order-book``, ``/market/tickers`` and ``/market/prices`` answer.
+    **A venue in both input lists is a Hummingbot connector.** That is the ``xrpl``
+    guarantee and this is the only place it is expressed: ``xrpl`` is a first-class
+    connector with a real order book whose *charts* come from GeckoTerminal, so it
+    sits in ``NETWORK_TO_GECKO`` and would appear in the gateway half the day a
+    Gateway version reports it — without this rule it would silently lose its order
+    book, its trading rules and every strategy but MARKET.
+
+    ``clmm_lp``: the venue is a gateway network *and* its gecko chain hosts a CLMM
+    venue (``pool_data.network_has_clmm``), not merely that it is a gateway network.
+    That is what keeps an order-book venue from being offered an LP tab it cannot
+    honor.
+
+    The candle source (CandlesFactory vs GeckoTerminal) is deliberately *not* a
+    field: the server already forks on it internally and no UI decision needs it.
+
+    Args:
+        strict: Raise instead of reporting a venue-less server, so a failure is
+            never cached as "there is nothing here". Credentials are load-bearing,
+            so their failure always re-raises under ``strict``. A gateway failure
+            only re-raises when it would leave the list empty: losing the DEX half
+            must not empty the whole dropdown, and a list that still carries the
+            credentialed venues is not a cached lie.
+    """
+    from handlers.dex.pool_data import network_has_clmm
+
+    # Credentials first: under strict this raises, and there is no point asking the
+    # gateway about a server we cannot describe at all.
+    connectors = await fetch_available_cex_connectors(
+        client, account_name=account_name, strict=strict
+    )
+
+    gateway_error = None
+    networks: List[str] = []
+    try:
+        networks = await _chartable_gateway_networks(client)
+    except Exception as e:
+        gateway_error = e
+        logger.error("Error fetching gateway networks: %s", e, exc_info=True)
+
+    credentialed = set(connectors)
+    gateway = set(networks)
+    venues = [
+        {
+            "name": name,
+            "hummingbot_market_data": name in credentialed,
+            "clmm_lp": name in gateway and network_has_clmm(name),
+        }
+        for name in sorted(credentialed | gateway)
+    ]
+
+    if strict and gateway_error is not None and not venues:
+        raise gateway_error
+    return venues
diff --git a/condor/server_data_service.py b/condor/server_data_service.py
index 2d747fa9..7223432d 100644
--- a/condor/server_data_service.py
+++ b/condor/server_data_service.py
@@ -45,7 +45,7 @@ class ServerDataType(Enum):
     CANDLE_CONNECTORS = "candle_connectors"
     SERVER_STATUS = "server_status"
     ALL_CONNECTORS = "all_connectors"
-    GATEWAY_NETWORKS = "gateway_networks"
+    VENUES = "venues"
     TICKERS = "tickers"
     TICKER_POOL = "ticker_pool"
 
@@ -84,11 +84,10 @@ class DataTypeDefaults:
     ServerDataType.ALL_CONNECTORS: DataTypeDefaults(
         interval=300, ttl=600, stale_threshold=30
     ),
-    # Gateway networks change ~never (a chain is added to the gateway config by
-    # hand), so a read is served from cache for half an hour.
-    ServerDataType.GATEWAY_NETWORKS: DataTypeDefaults(
-        interval=300, ttl=1800, stale_threshold=300
-    ),
+    # Venue traits follow the CONNECTORS cadence, not the "chains change ~never"
+    # one: the credentialed connector list is one of the inputs, so the answer
+    # changes the moment a user adds API keys.
+    ServerDataType.VENUES: DataTypeDefaults(interval=300, ttl=600, stale_threshold=30),
     ServerDataType.TICKERS: DataTypeDefaults(interval=60, ttl=180, stale_threshold=30),
     # Whole-server ticker pool: one poll feeds every per-connector ticker view and
     # all currency conversion, so reads never hit the network.
@@ -854,13 +853,13 @@ def register_default_fetches() -> None:
         fetch_connectors,
         fetch_current_price,
         fetch_executors,
-        fetch_gateway_networks,
         fetch_portfolio,
         fetch_positions,
         fetch_server_status,
         fetch_ticker_pool,
         fetch_tickers,
         fetch_trading_rules,
+        fetch_venues,
     )
 
     sds = get_server_data_service()
@@ -881,9 +880,7 @@ def register_default_fetches() -> None:
         ServerDataType.CONNECTORS, partial(fetch_available_cex_connectors, strict=True)
     )
     sds.register_fetch(ServerDataType.ALL_CONNECTORS, fetch_connectors)
-    sds.register_fetch(
-        ServerDataType.GATEWAY_NETWORKS, partial(fetch_gateway_networks, strict=True)
-    )
+    sds.register_fetch(ServerDataType.VENUES, partial(fetch_venues, strict=True))
     sds.register_fetch(ServerDataType.BOTS_STATUS, fetch_bots_status)
     sds.register_fetch(ServerDataType.EXECUTORS, fetch_executors)
     sds.register_fetch(ServerDataType.BOT_RUNS, fetch_bot_runs)
diff --git a/condor/web/routes/market.py b/condor/web/routes/market.py
index a3c2def6..680f0eb3 100644
--- a/condor/web/routes/market.py
+++ b/condor/web/routes/market.py
@@ -103,13 +103,18 @@ async def get_connected_exchanges(name: str, user: WebUser = Depends(get_current
     return result or []
 
 
-@router.get("/servers/{name}/market/gateway-networks")
-async def get_gateway_networks(name: str, user: WebUser = Depends(get_current_user)):
-    """Gateway networks the trade panel can offer (chartable DEX venues).
-
-    Answers ``{"networks": []}`` rather than a 502 when the gateway container is
-    down: the panel then simply shows no DEX. The fetcher runs ``strict=True``, so
-    the failure is never cached as an empty list and the next request retries.
+@router.get("/servers/{name}/market/venues")
+async def get_venues(name: str, user: WebUser = Depends(get_current_user)):
+    """Venues the trade panel can offer, each with its independent traits.
+
+    ``{"venues": [{"name", "hummingbot_market_data", "clmm_lp"}, ...]}``. The panel
+    maps traits to UI decisions itself — which tabs and strategies to render is a
+    product decision, not a server fact; only the facts they rest on come from here.
+
+    Answers ``{"venues": []}`` rather than a 502 when the server cannot be described
+    at all, so the panel renders its empty state. The fetcher runs ``strict=True``,
+    so that failure is never cached; a gateway-only failure degrades inside the
+    fetcher and still reports the credentialed venues.
     """
     cm = get_config_manager()
     if not cm.has_server_access(user.id, name):
@@ -119,12 +124,12 @@ async def get_gateway_networks(name: str, user: WebUser = Depends(get_current_us
 
     try:
         result = await get_server_data_service().get_or_fetch(
-            name, ServerDataType.GATEWAY_NETWORKS
+            name, ServerDataType.VENUES
         )
     except Exception as e:
-        logger.warning("Gateway networks unavailable for %s: %s", name, e)
-        return {"networks": []}
-    return {"networks": result or []}
+        logger.warning("Venues unavailable for %s: %s", name, e)
+        return {"venues": []}
+    return {"venues": result or []}
 
 
 _NO_POOL = {
diff --git a/handlers/dex/pool_data.py b/handlers/dex/pool_data.py
index 3c31ba64..c343c434 100644
--- a/handlers/dex/pool_data.py
+++ b/handlers/dex/pool_data.py
@@ -489,6 +489,20 @@ async def resolve_pool_info(
     return info
 
 
+def network_has_clmm(network: str) -> bool:
+    """Whether any known CLMM venue exists on this network's gecko chain.
+
+    This is the authority for "can a venue on this network take an ``lp_executor``
+    position", and it is deliberately *not* "is this a gateway network". ``xrpl`` is
+    a gateway-adjacent id that lives in ``NETWORK_TO_GECKO`` for charting only — its
+    AMM is not concentrated-liquidity, so it answers ``False`` here whether or not
+    Gateway ever reports it in ``list_networks()``. Deriving the trait from
+    ``_CLMM_VENUES`` instead of from gateway membership is what keeps that true.
+    """
+    gecko = get_gecko_network(network)
+    return any(gecko in networks for _brand, _qualifiers, networks in _CLMM_VENUES)
+
+
 def lp_provider_for_dex(dex_id: str, network: str) -> Optional[str]:
     """``"meteora/clmm"``-style LP provider for a GeckoTerminal dex id, or ``None``.
 
diff --git a/tests/test_fetcher_gateway_networks.py b/tests/test_fetcher_gateway_networks.py
deleted file mode 100644
index a3dd7a6f..00000000
--- a/tests/test_fetcher_gateway_networks.py
+++ /dev/null
@@ -1,184 +0,0 @@
-"""Tests for FEAT-041: ``fetch_gateway_networks`` normalizes and gates the list.
-
-The trade panel learns "this connector is a DEX" from this fetcher's output, so
-two properties matter. First, gateway has returned ``list_networks`` entries as
-plain strings and as ``network_id`` / ``id`` dicts across versions, and all three
-have to reduce to the same id. Second, the result is intersected with
-``NETWORK_TO_GECKO``: a network Condor cannot chart must never be offered, or the
-user picks it and gets an empty chart (``dex_candles.uses_gecko_candles`` is an
-exact-match membership test on that same dict).
-"""
-
-import asyncio
-
-import pytest
-
-from condor.fetchers.connectors import fetch_gateway_networks
-
-
-class FakeClient:
-    """Client whose ``gateway.list_networks`` replays one scripted response."""
-
-    def __init__(self, response=None, error=None):
-        self.calls = 0
-        self.gateway = self._Gateway(self)
-        self._response = response
-        self._error = error
-
-    class _Gateway:
-        def __init__(self, outer):
-            self._outer = outer
-
-        async def list_networks(self):
-            self._outer.calls += 1
-            if self._outer._error is not None:
-                raise self._outer._error
-            return self._outer._response
-
-
-def _fetch(response, **kwargs):
-    return asyncio.run(fetch_gateway_networks(FakeClient(response), **kwargs))
-
-
-def test_accepts_plain_string_entries():
-    result = _fetch({"networks": ["solana-mainnet-beta", "base-mainnet"]})
-    assert result == ["base-mainnet", "solana-mainnet-beta"]
-
-
-def test_accepts_network_id_dicts():
-    result = _fetch({"networks": [{"network_id": "solana-mainnet-beta"}]})
-    assert result == ["solana-mainnet-beta"]
-
-
-def test_accepts_id_dicts():
-    result = _fetch({"networks": [{"id": "ethereum-mainnet"}]})
-    assert result == ["ethereum-mainnet"]
-
-
-def test_mixed_shapes_normalize_to_the_same_ids():
-    result = _fetch(
-        {
-            "networks": [
-                "solana-mainnet-beta",
-                {"network_id": "base-mainnet"},
-                {"id": "polygon-mainnet"},
-            ]
-        }
-    )
-    assert result == ["base-mainnet", "polygon-mainnet", "solana-mainnet-beta"]
-
-
-def test_drops_networks_condor_cannot_chart():
-    """A network absent from NETWORK_TO_GECKO would 502 on the candle path."""
-    result = _fetch(
-        {
-            "networks": [
-                "solana-mainnet-beta",
-                "solana-devnet",
-                "base-sepolia",
-                {"network_id": "not-a-chain"},
-            ]
-        }
-    )
-    assert result == ["solana-mainnet-beta"]
-
-
-def test_deduplicates_and_sorts():
-    result = _fetch(
-        {"networks": ["base-mainnet", {"network_id": "base-mainnet"}, "solana"]}
-    )
-    assert result == ["base-mainnet", "solana"]
-
-
-def test_tolerates_missing_and_empty_payloads():
-    assert _fetch({}) == []
-    assert _fetch({"networks": None}) == []
-    assert _fetch(None) == []
-
-
-def test_strict_reraises_so_the_failure_is_not_cached():
-    """A cached empty list would tell the panel "this server has no DEX"."""
-    client = FakeClient(error=RuntimeError("gateway down"))
-    with pytest.raises(RuntimeError):
-        asyncio.run(fetch_gateway_networks(client, strict=True))
-
-
-def test_non_strict_swallows_the_failure():
-    client = FakeClient(error=RuntimeError("gateway down"))
-    assert asyncio.run(fetch_gateway_networks(client)) == []
-
-
-# ── The REST route ────────────────────────────────────────────────────────────
-#
-# The panel merges this endpoint's answer into its connector dropdown, so a
-# server whose gateway container is down must degrade to "no DEX offered" rather
-# than break the whole selector with a 502.
-
-
-class _FakeSds:
-    """Stands in for ServerDataService.get_or_fetch."""
-
-    def __init__(self, value=None, error=None):
-        self.value = value
-        self.error = error
-        self.calls = 0
-
-    async def get_or_fetch(self, name, data_type, **params):
-        self.calls += 1
-        if self.error is not None:
-            raise self.error
-        return self.value
-
-
-def _call_route(monkeypatch, sds):
-    from condor import server_data_service
-    from condor.web.models import WebUser
-    from condor.web.routes.market import get_gateway_networks
-
-    monkeypatch.setattr(
-        server_data_service, "get_server_data_service", lambda: sds, raising=True
-    )
-
-    class _Cm:
-        def has_server_access(self, user_id, name):
-            return True
-
-    monkeypatch.setattr(
-        "condor.web.routes.market.get_config_manager", lambda: _Cm(), raising=True
-    )
-    return asyncio.run(get_gateway_networks("srv", user=WebUser(id=1, role="user")))
-
-
-def test_route_returns_the_networks(monkeypatch):
-    sds = _FakeSds(value=["base-mainnet", "solana-mainnet-beta"])
-    assert _call_route(monkeypatch, sds) == {
-        "networks": ["base-mainnet", "solana-mainnet-beta"]
-    }
-
-
-def test_route_returns_empty_list_when_the_gateway_is_down(monkeypatch):
-    """Not a 500: the panel just shows no DEX."""
-    sds = _FakeSds(error=RuntimeError("gateway down"))
-    assert _call_route(monkeypatch, sds) == {"networks": []}
-
-
-def test_route_normalizes_a_none_answer(monkeypatch):
-    assert _call_route(monkeypatch, _FakeSds(value=None)) == {"networks": []}
-
-
-def test_route_rejects_a_caller_without_access(monkeypatch):
-    from fastapi import HTTPException
-
-    from condor.web.models import WebUser
-    from condor.web.routes.market import get_gateway_networks
-
-    class _Cm:
-        def has_server_access(self, user_id, name):
-            return False
-
-    monkeypatch.setattr(
-        "condor.web.routes.market.get_config_manager", lambda: _Cm(), raising=True
-    )
-    with pytest.raises(HTTPException) as e:
-        asyncio.run(get_gateway_networks("srv", user=WebUser(id=1, role="user")))
-    assert e.value.status_code == 403
diff --git a/tests/test_fetcher_venues.py b/tests/test_fetcher_venues.py
new file mode 100644
index 00000000..517e63e2
--- /dev/null
+++ b/tests/test_fetcher_venues.py
@@ -0,0 +1,395 @@
+"""Tests for FEAT-043: ``fetch_venues`` reports independent venue traits.
+
+The trade panel used to learn one fact — "this connector is a gateway network" —
+and use it to answer four different questions. This fetcher replaces that with two
+independent traits, each with a single authority, and the property that matters
+most is the one the binary could not express:
+
+``xrpl`` is a first-class Hummingbot connector with a real order book whose
+*charts* come from GeckoTerminal, so it lives in ``NETWORK_TO_GECKO`` — one of the
+two sets the gateway half is built from. If a Gateway version ever reports ``xrpl``
+in ``list_networks()``, it must still keep ``hummingbot_market_data: true`` (order
+book, trading rules, LIMIT strategies) and must still be denied ``clmm_lp`` (its
+AMM is not concentrated-liquidity). No reachable Gateway reports it today, which is
+exactly why it is pinned here rather than clicked.
+
+The gateway half also still has to normalize ``list_networks`` entries (plain
+strings and ``network_id`` / ``id`` dicts across versions) and drop any network
+Condor cannot chart, or the user picks one and gets an empty chart.
+"""
+
+import asyncio
+
+import pytest
+
+from condor.fetchers.connectors import fetch_venues
+from handlers.dex.pool_data import network_has_clmm
+
+
+class FakeClient:
+    """Client replaying one scripted ``list_networks`` + credential answer."""
+
+    def __init__(
+        self,
+        networks=None,
+        networks_error=None,
+        credentials=None,
+        credentials_error=None,
+        available=None,
+    ):
+        self.gateway_calls = 0
+        self.gateway = self._Gateway(self)
+        self.accounts = self._Accounts(self)
+        self.connectors = self._Connectors(self)
+        self._networks = networks
+        self._networks_error = networks_error
+        self._credentials = credentials if credentials is not None else []
+        self._credentials_error = credentials_error
+        # None means "every credentialed connector is available", which is what the
+        # intersection in fetch_available_cex_connectors degrades to.
+        self._available = available
+
+    class _Gateway:
+        def __init__(self, outer):
+            self._outer = outer
+
+        async def list_networks(self):
+            self._outer.gateway_calls += 1
+            if self._outer._networks_error is not None:
+                raise self._outer._networks_error
+            return self._outer._networks
+
+    class _Accounts:
+        def __init__(self, outer):
+            self._outer = outer
+
+        async def list_account_credentials(self, account_name):
+            if self._outer._credentials_error is not None:
+                raise self._outer._credentials_error
+            return list(self._outer._credentials)
+
+    class _Connectors:
+        def __init__(self, outer):
+            self._outer = outer
+
+        async def list_connectors(self):
+            if self._outer._available is None:
+                raise RuntimeError("connector list unavailable")
+            return list(self._outer._available)
+
+
+def _fetch(**kwargs):
+    strict = kwargs.pop("strict", False)
+    return asyncio.run(fetch_venues(FakeClient(**kwargs), strict=strict))
+
+
+def _by_name(venues):
+    return {v["name"]: v for v in venues}
+
+
+# ── network_has_clmm: the clmm_lp authority ───────────────────────────────────
+
+
+def test_network_has_clmm_is_true_for_chains_hosting_a_clmm_venue():
+    assert network_has_clmm("solana") is True
+    assert network_has_clmm("solana-mainnet-beta") is True
+    assert network_has_clmm("ethereum") is True
+    assert network_has_clmm("ethereum-mainnet") is True
+    assert network_has_clmm("base") is True
+    assert network_has_clmm("base-mainnet") is True
+    assert network_has_clmm("binance-smart-chain") is True
+
+
+def test_network_has_clmm_is_false_for_xrpl():
+    """The whole point: xrpl charts like a DEX but has no CLMM position model."""
+    assert network_has_clmm("xrpl") is False
+
+
+def test_network_has_clmm_is_false_for_a_chain_with_no_known_clmm_venue():
+    assert network_has_clmm("avalanche") is False
+
+
+def test_network_has_clmm_is_false_for_an_unknown_network():
+    assert network_has_clmm("not-a-chain") is False
+    assert network_has_clmm("") is False
+
+
+# ── The xrpl regression this feature exists for ───────────────────────────────
+
+
+def test_xrpl_in_both_lists_keeps_its_hummingbot_market_data():
+    """A venue in both input lists is a Hummingbot connector, not a DEX.
+
+    If Gateway starts reporting ``xrpl``, the panel must not strip its order book,
+    its trading rules and its LIMIT strategies, and must not offer it an LP tab.
+    """
+    venues = _by_name(
+        _fetch(
+            credentials=["binance", "xrpl"],
+            available=["binance", "xrpl"],
+            networks={"networks": ["xrpl", "solana-mainnet-beta"]},
+        )
+    )
+    assert venues["xrpl"] == {
+        "name": "xrpl",
+        "hummingbot_market_data": True,
+        "clmm_lp": False,
+    }
+    # And the real gateway network in the same answer is unaffected.
+    assert venues["solana-mainnet-beta"] == {
+        "name": "solana-mainnet-beta",
+        "hummingbot_market_data": False,
+        "clmm_lp": True,
+    }
+
+
+def test_xrpl_credentialed_and_absent_from_gateway_is_a_plain_connector():
+    """Today's world: the traits must be identical to the both-lists case."""
+    venues = _by_name(
+        _fetch(
+            credentials=["xrpl"],
+            available=["xrpl"],
+            networks={"networks": ["solana-mainnet-beta"]},
+        )
+    )
+    assert venues["xrpl"]["hummingbot_market_data"] is True
+    assert venues["xrpl"]["clmm_lp"] is False
+
+
+# ── Trait composition ─────────────────────────────────────────────────────────
+
+
+def test_a_credentialed_connector_has_market_data_and_no_lp():
+    venues = _by_name(
+        _fetch(
+            credentials=["binance", "binance_perpetual"],
+            available=["binance", "binance_perpetual"],
+            networks={"networks": []},
+        )
+    )
+    assert venues["binance"] == {
+        "name": "binance",
+        "hummingbot_market_data": True,
+        "clmm_lp": False,
+    }
+    assert venues["binance_perpetual"]["hummingbot_market_data"] is True
+
+
+def test_a_gateway_network_has_lp_and_no_market_data():
+    venues = _by_name(_fetch(networks={"networks": ["solana-mainnet-beta"]}))
+    assert venues["solana-mainnet-beta"] == {
+        "name": "solana-mainnet-beta",
+        "hummingbot_market_data": False,
+        "clmm_lp": True,
+    }
+
+
+def test_a_gateway_network_with_no_clmm_venue_gets_no_lp():
+    """``avalanche`` is chartable but hosts none of the CLMM venues."""
+    venues = _by_name(_fetch(networks={"networks": ["avalanche"]}))
+    assert venues["avalanche"] == {
+        "name": "avalanche",
+        "hummingbot_market_data": False,
+        "clmm_lp": False,
+    }
+
+
+def test_venues_are_sorted_and_deduplicated():
+    venues = _fetch(
+        credentials=["kucoin", "binance"],
+        available=["kucoin", "binance"],
+        networks={"networks": ["solana-mainnet-beta", {"id": "base-mainnet"}]},
+    )
+    assert [v["name"] for v in venues] == [
+        "base-mainnet",
+        "binance",
+        "kucoin",
+        "solana-mainnet-beta",
+    ]
+
+
+# ── The gateway half still normalizes and gates ───────────────────────────────
+
+
+def test_accepts_plain_strings_and_network_id_and_id_dicts():
+    names = [
+        v["name"]
+        for v in _fetch(
+            networks={
+                "networks": [
+                    "solana-mainnet-beta",
+                    {"network_id": "base-mainnet"},
+                    {"id": "polygon-mainnet"},
+                ]
+            }
+        )
+    ]
+    assert names == ["base-mainnet", "polygon-mainnet", "solana-mainnet-beta"]
+
+
+def test_drops_networks_condor_cannot_chart():
+    """A network absent from NETWORK_TO_GECKO would 502 on the candle path."""
+    names = [
+        v["name"]
+        for v in _fetch(
+            networks={
+                "networks": [
+                    "solana-mainnet-beta",
+                    "solana-devnet",
+                    "base-sepolia",
+                    {"network_id": "not-a-chain"},
+                ]
+            }
+        )
+    ]
+    assert names == ["solana-mainnet-beta"]
+
+
+def test_tolerates_missing_and_empty_gateway_payloads():
+    assert _fetch(networks={}) == []
+    assert _fetch(networks={"networks": None}) == []
+    assert _fetch(networks=None) == []
+
+
+# ── strict: what a failure is allowed to take down ────────────────────────────
+
+
+def test_a_gateway_failure_still_yields_the_credentialed_venues():
+    """Losing the DEX half must not empty the whole dropdown."""
+    venues = _by_name(
+        _fetch(
+            credentials=["binance"],
+            available=["binance"],
+            networks_error=RuntimeError("gateway down"),
+            strict=True,
+        )
+    )
+    assert venues["binance"]["hummingbot_market_data"] is True
+    assert len(venues) == 1
+
+
+def test_strict_reraises_a_gateway_failure_that_would_leave_nothing():
+    """An empty list must never be cached as "this server has no venues"."""
+    client = FakeClient(
+        credentials=[], available=[], networks_error=RuntimeError("gateway down")
+    )
+    with pytest.raises(RuntimeError):
+        asyncio.run(fetch_venues(client, strict=True))
+
+
+def test_non_strict_swallows_a_total_failure():
+    client = FakeClient(
+        credentials=[], available=[], networks_error=RuntimeError("gateway down")
+    )
+    assert asyncio.run(fetch_venues(client)) == []
+
+
+def test_strict_reraises_a_credentials_failure():
+    """Credentials are load-bearing: without them there is no venue at all."""
+    client = FakeClient(
+        credentials_error=RuntimeError("server down"),
+        networks={"networks": ["solana-mainnet-beta"]},
+    )
+    with pytest.raises(RuntimeError):
+        asyncio.run(fetch_venues(client, strict=True))
+
+
+def test_non_strict_credentials_failure_degrades_to_the_gateway_half():
+    venues = _by_name(
+        asyncio.run(
+            fetch_venues(
+                FakeClient(
+                    credentials_error=RuntimeError("server down"),
+                    networks={"networks": ["solana-mainnet-beta"]},
+                )
+            )
+        )
+    )
+    assert venues["solana-mainnet-beta"]["clmm_lp"] is True
+
+
+def test_rejects_an_unsafe_account_name():
+    from condor.fetchers._identifiers import IdentifierError
+
+    with pytest.raises(IdentifierError):
+        asyncio.run(fetch_venues(FakeClient(), account_name="../etc"))
+
+
+# ── The REST route ────────────────────────────────────────────────────────────
+#
+# The panel's connector dropdown is this endpoint's answer, so a server that
+# cannot be described must degrade to an empty list rather than a 502.
+
+
+class _FakeSds:
+    """Stands in for ServerDataService.get_or_fetch."""
+
+    def __init__(self, value=None, error=None):
+        self.value = value
+        self.error = error
+        self.calls = 0
+
+    async def get_or_fetch(self, name, data_type, **params):
+        self.calls += 1
+        if self.error is not None:
+            raise self.error
+        return self.value
+
+
+def _call_route(monkeypatch, sds):
+    from condor import server_data_service
+    from condor.web.models import WebUser
+    from condor.web.routes.market import get_venues
+
+    monkeypatch.setattr(
+        server_data_service, "get_server_data_service", lambda: sds, raising=True
+    )
+
+    class _Cm:
+        def has_server_access(self, user_id, name):
+            return True
+
+    monkeypatch.setattr(
+        "condor.web.routes.market.get_config_manager", lambda: _Cm(), raising=True
+    )
+    return asyncio.run(get_venues("srv", user=WebUser(id=1, role="user")))
+
+
+def test_route_returns_the_venues(monkeypatch):
+    payload = [
+        {"name": "binance", "hummingbot_market_data": True, "clmm_lp": False},
+        {
+            "name": "solana-mainnet-beta",
+            "hummingbot_market_data": False,
+            "clmm_lp": True,
+        },
+    ]
+    assert _call_route(monkeypatch, _FakeSds(value=payload)) == {"venues": payload}
+
+
+def test_route_returns_an_empty_list_when_the_server_is_undescribable(monkeypatch):
+    """Not a 500: the panel renders its empty state."""
+    sds = _FakeSds(error=RuntimeError("server down"))
+    assert _call_route(monkeypatch, sds) == {"venues": []}
+
+
+def test_route_normalizes_a_none_answer(monkeypatch):
+    assert _call_route(monkeypatch, _FakeSds(value=None)) == {"venues": []}
+
+
+def test_route_rejects_a_caller_without_access(monkeypatch):
+    from fastapi import HTTPException
+
+    from condor.web.models import WebUser
+    from condor.web.routes.market import get_venues
+
+    class _Cm:
+        def has_server_access(self, user_id, name):
+            return False
+
+    monkeypatch.setattr(
+        "condor.web.routes.market.get_config_manager", lambda: _Cm(), raising=True
+    )
+    with pytest.raises(HTTPException) as e:
+        asyncio.run(get_venues("srv", user=WebUser(id=1, role="user")))
+    assert e.value.status_code == 403

From 5cc1fb30f8cec7bf08aa721fdc2aa70b590887f4 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Tue, 11 Aug 2026 17:27:20 +0300
Subject: [PATCH 007/116] Decide the trade panel from venue traits, not from
 DEX-ness

connector-capabilities.ts keeps its role -- the one place that maps facts to UI
decisions -- but the input becomes traits instead of a `kind: "cex" | "dex"`
binary, and each UI consequence is traced to the trait that justifies it.
`hummingbotMarketData` grants the order book, the trading rules, REST prices, the
LIMIT family and the position/grid/dca tabs; `clmmLp` grants the LP tab, read
independently, which is what stops an order-book venue from being offered an LP
tab and a swap venue from being denied one.

The four conflated call sites in CreateExecutor now each read the trait they
actually need: useLpConfig takes `supportsLp` instead of `kind === "dex"`, the
price query and the price source take `hasRestPrice` instead of `kind`, and
PriceTicker takes `hasRestPrice` instead of standing in order-book-ness for it.

Two connector queries collapse to one: the server dedups with a defined winner,
so the merge and the `binance-smart-chain`-could-be-in-both worry both go away.
Order-book venues are listed first so the reset fallback stays a tradable venue.
ExchangeSelector's DEX grouping is fed by `!hummingbotMarketData`, so `xrpl` sits
in the exchange group and reads as `Xrpl` -- which is how you actually trade it.

An unknown venue, and every venue before the query resolves, keeps full
Hummingbot capabilities: the pending state must not flash DEX-restricted UI.

Verified offline with a throwaway tsx script (34 assertions, the frontend has no
test runner and this is not the feature that adds one): xrpl present in both
server input lists yields all four tabs, all four strategies, REST prices and no
LP tab; a chartable gateway network yields Order+LP, MARKET only, no book;
binance is byte-identical to before.
---
 .../components/market/ExchangeSelector.tsx    |  7 +-
 frontend/src/lib/api.ts                       | 23 ++++-
 frontend/src/lib/connector-capabilities.ts    | 99 ++++++++++++-------
 frontend/src/pages/CreateExecutor.tsx         | 75 +++++++-------
 4 files changed, 128 insertions(+), 76 deletions(-)

diff --git a/frontend/src/components/market/ExchangeSelector.tsx b/frontend/src/components/market/ExchangeSelector.tsx
index 6eac9957..8d394e63 100644
--- a/frontend/src/components/market/ExchangeSelector.tsx
+++ b/frontend/src/components/market/ExchangeSelector.tsx
@@ -5,7 +5,12 @@ interface ExchangeSelectorProps {
   connectors: string[];
   value: string;
   onChange: (v: string) => void;
-  /** Connectors that are gateway DEX networks — listed under their own heading. */
+  /**
+   * Venues with no Hummingbot market feed — listed under their own heading and
+   * formatted as chain ids. Fed by `!hummingbotMarketData`, not by gateway-network
+   * membership: `xrpl` is a gateway-adjacent id that trades through a real order
+   * book, so it belongs in the exchange group and reads as `Xrpl`.
+   */
   dexConnectors?: string[];
 }
 
diff --git a/frontend/src/lib/api.ts b/frontend/src/lib/api.ts
index 9982cd7b..2cb06de5 100644
--- a/frontend/src/lib/api.ts
+++ b/frontend/src/lib/api.ts
@@ -267,6 +267,13 @@ export interface MarketPrice {
  * a pool address by hand. `current_price` is the base priced in quote — the scale
  * every LP bound is expressed in — and is null when GeckoTerminal reports no price.
  */
+/** Wire shape of `GET /market/venues`; mapped to `VenueTraits` on the way in. */
+interface WireVenue {
+  name: string;
+  hummingbot_market_data: boolean;
+  clmm_lp: boolean;
+}
+
 export interface DexPoolInfo {
   pool_address: string | null;
   dex_id: string | null;
@@ -1198,11 +1205,17 @@ export const api = {
   getConnectedExchanges: (server: string) =>
     apiFetch<string[]>(`/api/v1/servers/${encodeURIComponent(server)}/market/connected-exchanges`),
 
-  /** Chartable gateway DEX networks — the trade panel's DEX half of the dropdown. */
-  getGatewayNetworks: (server: string) =>
-    apiFetch<{ networks: string[] }>(
-      `/api/v1/servers/${encodeURIComponent(server)}/market/gateway-networks`,
-    ).then((r) => r.networks),
+  /** Venues the trade panel can offer, with the traits each UI decision rests on. */
+  getVenues: (server: string) =>
+    apiFetch<{ venues: WireVenue[] }>(
+      `/api/v1/servers/${encodeURIComponent(server)}/market/venues`,
+    ).then((r) =>
+      (r.venues ?? []).map((v) => ({
+        name: v.name,
+        hummingbotMarketData: !!v.hummingbot_market_data,
+        clmmLp: !!v.clmm_lp,
+      })),
+    ),
 
   getDexPool: (server: string, connector: string, pair: string) =>
     apiFetch<DexPoolInfo>(
diff --git a/frontend/src/lib/connector-capabilities.ts b/frontend/src/lib/connector-capabilities.ts
index 3d79c2fa..6939b796 100644
--- a/frontend/src/lib/connector-capabilities.ts
+++ b/frontend/src/lib/connector-capabilities.ts
@@ -1,26 +1,38 @@
 import type { ExecutorType } from "@/components/executor/types";
 
 /**
- * What a connector can do in the trade panel.
+ * What a venue can do in the trade panel.
  *
- * DEX-ness is **not** guessed from the name here. The backend already carries four
- * mutually inconsistent connector predicates (prefix lists, substring lists, live
- * gateway lookups) that disagree on cases like `binance-smart-chain`; a fifth one
- * in the frontend would silently drift the same way, and the symptom would be "the
- * chart is blank and Grid is offered on a DEX". Instead the server tells us which
- * connectors are gateway networks (`GET /market/gateway-networks`, already
- * intersected with the set Condor can chart) and this module classifies by
- * membership in that list.
+ * This is the one place that maps *facts about a venue* to *UI decisions*, and the
+ * facts arrive from the server as independent traits (`GET /market/venues`) rather
+ * than being guessed here. Nothing about a venue is inferred from its name: the
+ * backend already carries four mutually inconsistent connector predicates (prefix
+ * lists, substring lists, live gateway lookups) that disagree on cases like
+ * `binance-smart-chain`, and a fifth one in the frontend would drift the same way.
+ *
+ * It is also not inferred from *one* trait standing in for several. The panel asks
+ * four different questions — which executor tabs exist, which execution strategies
+ * exist, whether the Hummingbot market endpoints are called, and where the current
+ * price comes from — and they do not have a common answer. `xrpl` is the venue that
+ * proves it: a first-class Hummingbot connector with a real order book whose charts
+ * nonetheless come from GeckoTerminal. A `cex`/`dex` binary keyed on chart source
+ * silently strips its book; two independent traits cannot.
  *
  * The executor-type and strategy maps below *are* frontend literals, deliberately:
  * they are a UI product decision about which tabs and options to render, not a
  * server fact, and they are changed by whoever changes the tabs.
  */
 
-export type ConnectorKind = "cex" | "dex";
+/** A venue's independent traits, as `GET /market/venues` reports them. */
+export interface VenueTraits {
+  name: string;
+  /** `/market/trading-rules`, `/market/order-book`, `/market/tickers`, `/market/prices` answer. */
+  hummingbotMarketData: boolean;
+  /** This venue can take an `lp_executor` CLMM position. */
+  clmmLp: boolean;
+}
 
 export interface ConnectorCapabilities {
-  kind: ConnectorKind;
   /** Executor types this venue supports. */
   executorTypes: ExecutorType[];
   /** Allowed `execution_strategy` values (subset of OrderConfigPanel's options). */
@@ -29,37 +41,56 @@ export interface ConnectorCapabilities {
   hasOrderBook: boolean;
   /** Whether `/market/trading-rules` answers — pair list + price precision. */
   hasTradingRules: boolean;
+  /** Whether `/market/prices` answers — otherwise the price comes off the candle stream. */
+  hasRestPrice: boolean;
+  /** Whether the LP tab is offered. */
+  supportsLp: boolean;
 }
 
-const CEX_CAPABILITIES: ConnectorCapabilities = {
-  kind: "cex",
-  executorTypes: ["order", "position", "grid", "dca"],
-  orderStrategies: ["MARKET", "LIMIT", "LIMIT_MAKER", "LIMIT_CHASER"],
-  hasOrderBook: true,
-  hasTradingRules: true,
-};
-
-// A gateway swap has no resting order book to post to, so MARKET is the only
-// execution strategy that means anything. `lp` is the CLMM liquidity position —
-// the second, and only other, executor a gateway network supports.
-const DEX_CAPABILITIES: ConnectorCapabilities = {
-  kind: "dex",
-  executorTypes: ["order", "lp"],
-  orderStrategies: ["MARKET"],
-  hasOrderBook: false,
-  hasTradingRules: false,
+/**
+ * The traits assumed for a venue we have no answer for — including every venue
+ * before the query resolves. Full Hummingbot capabilities: the status quo for every
+ * venue the panel handled before DEX support existed, so the pending state never
+ * flashes DEX-restricted UI.
+ */
+const UNKNOWN_VENUE: VenueTraits = {
+  name: "",
+  hummingbotMarketData: true,
+  clmmLp: false,
 };
 
 /**
- * Capabilities of `connector`, given the gateway networks this server exposes.
+ * Capabilities of `connector`, given what the server says about the venues.
  *
- * An unknown connector — or any connector at all before the gateway-networks
- * query resolves — is treated as a CEX, which is the status quo behavior for
- * every venue the panel handled before DEX support existed.
+ * Each UI consequence is traced to the single trait that justifies it, and the two
+ * traits are read independently — that is what stops an order-book venue from being
+ * offered an LP tab, and a swap venue from being denied one.
  */
 export function connectorCapabilities(
   connector: string,
-  gatewayNetworks: string[],
+  venues: VenueTraits[] | Map<string, VenueTraits>,
 ): ConnectorCapabilities {
-  return gatewayNetworks.includes(connector) ? DEX_CAPABILITIES : CEX_CAPABILITIES;
+  const traits =
+    (venues instanceof Map
+      ? venues.get(connector)
+      : venues.find((v) => v.name === connector)) ?? UNKNOWN_VENUE;
+
+  // Without a Hummingbot market feed there is no resting order book to post to, so
+  // MARKET is the only execution strategy that means anything, and the executors
+  // that manage resting orders (position/grid/dca) have nothing to manage.
+  const executorTypes: ExecutorType[] = traits.hummingbotMarketData
+    ? ["order", "position", "grid", "dca"]
+    : ["order"];
+  if (traits.clmmLp) executorTypes.push("lp");
+
+  return {
+    executorTypes,
+    orderStrategies: traits.hummingbotMarketData
+      ? ["MARKET", "LIMIT", "LIMIT_MAKER", "LIMIT_CHASER"]
+      : ["MARKET"],
+    hasOrderBook: traits.hummingbotMarketData,
+    hasTradingRules: traits.hummingbotMarketData,
+    hasRestPrice: traits.hummingbotMarketData,
+    supportsLp: traits.clmmLp,
+  };
 }
diff --git a/frontend/src/pages/CreateExecutor.tsx b/frontend/src/pages/CreateExecutor.tsx
index 3603bdfc..d58b41db 100644
--- a/frontend/src/pages/CreateExecutor.tsx
+++ b/frontend/src/pages/CreateExecutor.tsx
@@ -147,42 +147,46 @@ export function CreateExecutor() {
     cursor: "row-resize",
   });
 
-  const { data: connectors = [], isPending: connectorsPending } = useQuery({
-    queryKey: ["connected-exchanges", server],
-    queryFn: () => api.getConnectedExchanges(server!),
-    enabled: !!server,
-  });
-
-  // `connected-exchanges` is CEX-only by contract and has other callers, so the
-  // gateway networks arrive on their own endpoint and the panel merges the two.
-  const { data: gatewayNetworks = [], isPending: networksPending } = useQuery({
-    queryKey: ["gateway-networks", server],
-    queryFn: () => api.getGatewayNetworks(server!),
+  // One query, one answer: every venue the panel can offer, each with the traits
+  // the UI decisions below rest on. The server dedups (a venue in both of its input
+  // lists is a Hummingbot connector), so there is no merge to get wrong here.
+  const { data: venues = [], isPending: venuesPending } = useQuery({
+    queryKey: ["venues", server],
+    queryFn: () => api.getVenues(server!),
     enabled: !!server,
     staleTime: 5 * 60 * 1000,
   });
 
-  // Both halves of the dropdown have to be in before the panel may *correct* a
-  // selection: judging a persisted DEX network against the CEX list alone would
-  // bounce it to connectors[0] on every reload, and switch its tab to Order.
-  const listsReady = !!server && !connectorsPending && !networksPending;
+  // The list has to be in before the panel may *correct* a selection: judging a
+  // persisted venue against an empty list would bounce it on every reload and
+  // switch its tab to Order.
+  const listsReady = !!server && !venuesPending;
 
-  // Deduplicated: `is_cex_connector` still calls `binance-smart-chain` a CEX, so a
-  // network can legitimately appear in both lists.
+  // Order-book venues first, then swap-only ones — the grouping ExchangeSelector
+  // renders, and it keeps allConnectors[0] (the reset fallback) a tradable venue
+  // rather than whichever chain sorts first alphabetically.
   const allConnectors = useMemo(
-    () => [...new Set([...connectors, ...gatewayNetworks])],
-    [connectors, gatewayNetworks],
+    () => [
+      ...venues.filter((v) => v.hummingbotMarketData).map((v) => v.name),
+      ...venues.filter((v) => !v.hummingbotMarketData).map((v) => v.name),
+    ],
+    [venues],
+  );
+
+  const dexConnectors = useMemo(
+    () => venues.filter((v) => !v.hummingbotMarketData).map((v) => v.name),
+    [venues],
   );
 
   const caps = useMemo(
-    () => connectorCapabilities(connector, gatewayNetworks),
-    [connector, gatewayNetworks],
+    () => connectorCapabilities(connector, venues),
+    [connector, venues],
   );
 
-  // Pool resolution only means something for a gateway network, so the query is off
-  // for a CEX rather than asking about a pair that has no pool. Declared above the
-  // connector/pair propagation effects that dispatch into it.
-  const lpConfig = useLpConfig(server ?? null, connector, pair, caps.kind === "dex");
+  // Pool resolution only means something where an LP position can exist, so the
+  // query is off elsewhere rather than asking about a pair that has no pool.
+  // Declared above the connector/pair propagation effects that dispatch into it.
+  const lpConfig = useLpConfig(server ?? null, connector, pair, caps.supportsLp);
 
   // WS for executor data (candle streams are managed by candleStore)
   const wsChannels = useMemo(
@@ -218,8 +222,8 @@ export function CreateExecutor() {
     setSelectedExecutorId(null);
   }, [connector, pair]);
 
-  // Sync connector to the merged list. Validating against the CEX list alone would
-  // bounce a selected DEX network back to connectors[0] on every render.
+  // Sync connector to the offered venues. A venue the server no longer reports
+  // cannot stay selected, or the panel queries endpoints for a venue that is gone.
   useEffect(() => {
     if (listsReady && allConnectors.length && !allConnectors.includes(connector)) {
       gridDispatch({ type: "SET_CONNECTOR", value: allConnectors[0] });
@@ -260,14 +264,14 @@ export function CreateExecutor() {
     lpConfig.dispatch({ type: "SET_PAIR", value: pair });
   }, [pair]); // eslint-disable-line react-hooks/exhaustive-deps
 
-  // Current price. /market/prices is a Hummingbot API call with no DEX answer, so a
-  // gateway network reads the last close off the candle stream instead. The store is
+  // Current price. /market/prices only answers for a Hummingbot connector, so a
+  // venue without that trait reads the last close off the candle stream instead. The store is
   // a singleton over one shared channel and TradeChart already subscribes with these
   // exact arguments, so this costs no extra connection.
   const { data: priceData } = useQuery({
     queryKey: ["price", server, connector, pair],
     queryFn: () => api.getPrice(server!, connector, pair),
-    enabled: !!server && !!connector && !!pair && caps.kind === "cex",
+    enabled: !!server && !!connector && !!pair && caps.hasRestPrice,
     refetchInterval: 5000,
   });
 
@@ -278,10 +282,9 @@ export function CreateExecutor() {
     gridState.interval,
   );
 
-  const currentPrice =
-    caps.kind === "dex"
-      ? (sharedCandles[sharedCandles.length - 1]?.close ?? null)
-      : (priceData?.mid_price ?? null);
+  const currentPrice = !caps.hasRestPrice
+    ? (sharedCandles[sharedCandles.length - 1]?.close ?? null)
+    : (priceData?.mid_price ?? null);
 
 
   // Price precision
@@ -455,14 +458,14 @@ export function CreateExecutor() {
               connectors={allConnectors}
               value={connector}
               onChange={(v) => gridDispatch({ type: "SET_CONNECTOR", value: v })}
-              dexConnectors={gatewayNetworks}
+              dexConnectors={dexConnectors}
             />
           </div>
         </div>
 
         {/* Price ticker */}
         <div className="flex flex-1 items-center px-4 py-2">
-          <PriceTicker server={server} connector={connector} pair={pair} hasRestPrice={caps.hasOrderBook} />
+          <PriceTicker server={server} connector={connector} pair={pair} hasRestPrice={caps.hasRestPrice} />
         </div>
 
         {/* Interval + Range */}

From 3fa941fa3e49fb647b94916b92d11e481e7b7fdd Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Tue, 11 Aug 2026 23:01:14 +0300
Subject: [PATCH 008/116] (style) mechanical format sweep: isort then black
 over the Python tree
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`CLAUDE.md` documents `uv run black .` and `uv run isort .` as this repo's format
commands, but neither passed on a clean tree: 69 files failed `black --check` and
42 failed `isort --check-only`. That made the check ungateable — any change
touching a drifted file had to choose between burying its real diff in unrelated
reflow or leaving the repo's own documented command failing, and every item in
the 2026-08-06 sweep chose the second.

This commit is `uv run isort .` followed by `uv run black .` and nothing else, so
its diff is trivially reviewable as pure reflow and `git blame` readers can skip
it. isort runs first so black settles the result.

Every hunk is whitespace, wrapping or import ordering. Verified by comparing the
AST of each file before and after: the nine files whose node sets differ at all
differ only by isort splitting a combined `from X import (a as b, c)` into one
statement per name, or reordering names — including one function-level import in
`condor/web/routes/settings.py`. No non-import node changed anywhere.

`uv run pytest` is 1538 passed before and after, and both `--check` commands now
exit 0.

READ-133
---
 .../routines/hip3_dn_pair_monitor.py          |   1 +
 .../routines/hip3_pairs_backtest.py           |   3 +
 .../routines/ema_research_charts.py           | 177 ++++++++++---
 .../routines/hip3_market_scanner.py           |   1 +
 .../routines/market_analyzer.py               |   5 +-
 .../routines/mm_dashboard.py                  |   2 +
 .../routines/damm_v2_scanner.py               | 119 ++++++---
 .../routines/easya_graduation_monitor.py      | 122 ++++++---
 .../routines/launch_safety_check.py           | 129 +++++++--
 .../smart_money_flow/routines/onchain_flow.py | 137 +++++++---
 .../routines/lp_scanner.py                    |   4 +-
 .../routines/xrpl_mm_quote_planner.py         |  95 +++++--
 condor/acp/__init__.py                        |  10 +-
 condor/acp/jsonrpc.py                         |  19 +-
 condor/backtest_store.py                      |  21 +-
 condor/cache.py                               |   4 +-
 condor/fetchers/__init__.py                   |  28 +-
 condor/fetchers/connectors.py                 |   8 +-
 condor/fetchers/executors.py                  |  16 +-
 condor/fetchers/trading_rules.py              |   7 +-
 condor/persistence.py                         |   4 +-
 condor/preferences.py                         |   3 +-
 condor/web/routes/archived.py                 |  66 +++--
 condor/web/routes/executors.py                |  33 ++-
 condor/web/routes/positions.py                |  19 +-
 condor/web/routes/reports.py                  |   2 +-
 condor/web/routes/settings.py                 |  93 ++++---
 condor/web/routes/transcribe.py               |   3 +-
 handlers/admin/__init__.py                    |   6 +-
 handlers/admin/update.py                      |  80 ++++--
 handlers/agents/openrouter_models.py          |   4 +-
 handlers/bots/__init__.py                     |   4 +-
 handlers/bots/controller_handlers.py          |   9 +-
 handlers/bots/menu.py                         |   4 +-
 handlers/config/gateway/menu.py               |   3 +-
 handlers/config/gateway/networks.py           |  14 +-
 handlers/config/gateway/pools.py              |  11 +-
 handlers/config/gateway/rpc_providers.py      | 250 +++++++++++-------
 handlers/config/gateway/tokens.py             |  14 +-
 handlers/config/gateway/wallets.py            |  18 +-
 handlers/delegations.py                       |   6 +-
 handlers/dex/_shared.py                       |  26 +-
 handlers/executors/__init__.py                |  18 +-
 handlers/executors/grid.py                    |  28 +-
 handlers/executors/menu.py                    |  38 ++-
 handlers/executors/position.py                |  73 +++--
 mcp_servers/condor/tools/context.py           |   9 +-
 mcp_servers/condor/tools/servers.py           |  16 +-
 .../hummingbot_api/executor_preferences.py    |  33 ++-
 .../hummingbot_api/formatters/__init__.py     |  28 +-
 mcp_servers/hummingbot_api/formatters/base.py |  19 +-
 mcp_servers/hummingbot_api/formatters/bots.py |  30 ++-
 .../hummingbot_api/formatters/executors.py    |  90 +++++--
 .../hummingbot_api/formatters/gateway.py      |  12 +-
 .../hummingbot_api/formatters/market_data.py  |   1 +
 .../hummingbot_api/formatters/portfolio.py    |  15 +-
 .../formatters/table_builder.py               |  26 +-
 .../hummingbot_api/formatters/trading.py      |  30 ++-
 .../hummingbot_api/hummingbot_client.py       |  22 +-
 mcp_servers/hummingbot_api/middleware.py      |  17 +-
 mcp_servers/hummingbot_api/schemas.py         |  71 +++--
 mcp_servers/hummingbot_api/server.py          |   4 +-
 .../hummingbot_api/tools/bot_management.py    |  58 +++-
 .../hummingbot_api/tools/controllers.py       | 128 ++++++---
 mcp_servers/hummingbot_api/tools/executors.py |  92 +++++--
 mcp_servers/hummingbot_api/tools/gateway.py   | 129 +++++----
 .../hummingbot_api/tools/gateway_amm.py       |  69 +++--
 .../hummingbot_api/tools/gateway_clmm.py      |  35 +--
 .../hummingbot_api/tools/gateway_swap.py      |  36 +--
 .../hummingbot_api/tools/geckoterminal.py     | 139 +++++++---
 mcp_servers/hummingbot_api/tools/history.py   |  46 ++--
 .../hummingbot_api/tools/market_data.py       |   5 +-
 mcp_servers/hummingbot_api/tools/portfolio.py | 217 +++++++++------
 mcp_servers/hummingbot_api/tools/trading.py   |  10 +-
 routines/market_scanner.py                    |   1 +
 tests/test_custom_provider.py                 |  32 ++-
 tests/test_executor_mutation_errors.py        |   5 +-
 tests/test_executor_row_shared.py             |   5 +-
 tests/test_executors_period_summary.py        |  19 +-
 tests/test_instance_history_pagination.py     |   4 +-
 tests/test_reports_attribution.py             |   4 +-
 utils/auth.py                                 |   6 +-
 utils/deeplink.py                             |  16 +-
 utils/transcribe.py                           |   9 +-
 utils/updater.py                              |  47 +++-
 85 files changed, 2210 insertions(+), 1062 deletions(-)

diff --git a/agents/delta_neutral_funding_agent/routines/hip3_dn_pair_monitor.py b/agents/delta_neutral_funding_agent/routines/hip3_dn_pair_monitor.py
index ccdda545..ed131e1e 100644
--- a/agents/delta_neutral_funding_agent/routines/hip3_dn_pair_monitor.py
+++ b/agents/delta_neutral_funding_agent/routines/hip3_dn_pair_monitor.py
@@ -8,6 +8,7 @@
 import aiohttp
 from pydantic import BaseModel, Field
 from telegram.ext import ContextTypes
+
 from config_manager import get_client
 
 logger = logging.getLogger(__name__)
diff --git a/agents/delta_neutral_funding_agent/routines/hip3_pairs_backtest.py b/agents/delta_neutral_funding_agent/routines/hip3_pairs_backtest.py
index 3e12513b..0a217535 100644
--- a/agents/delta_neutral_funding_agent/routines/hip3_pairs_backtest.py
+++ b/agents/delta_neutral_funding_agent/routines/hip3_pairs_backtest.py
@@ -8,6 +8,7 @@
 import aiohttp
 from pydantic import BaseModel, Field
 from telegram.ext import ContextTypes
+
 from config_manager import get_client
 
 logger = logging.getLogger(__name__)
@@ -889,6 +890,7 @@ def _fmt_signal(name: str, r: dict, flags: list) -> str:
 
     # ── 7. ReportBuilder ──────────────────────────────────────────────────────
     import plotly.graph_objects as go
+
     from condor.reports import ReportBuilder
 
     builder = ReportBuilder(
@@ -1258,6 +1260,7 @@ def _fmt(label, r, beta, r2):
 
     # ── 9. ReportBuilder ──────────────────────────────────────────────────────
     import plotly.graph_objects as go
+
     from condor.reports import ReportBuilder
 
     builder = ReportBuilder(f"HIP-3 Pairs Backtest: {issuer_upper}")
diff --git a/agents/directional_trader/routines/ema_research_charts.py b/agents/directional_trader/routines/ema_research_charts.py
index 45b6a81e..b6bb0106 100644
--- a/agents/directional_trader/routines/ema_research_charts.py
+++ b/agents/directional_trader/routines/ema_research_charts.py
@@ -26,27 +26,41 @@
 
 # bars per calendar day for each supported timeframe
 BARS_PER_DAY = {
-    "1m": 1440, "3m": 480, "5m": 288, "15m": 96,
-    "30m": 48, "1h": 24, "4h": 6, "1d": 1,
+    "1m": 1440,
+    "3m": 480,
+    "5m": 288,
+    "15m": 96,
+    "30m": 48,
+    "1h": 24,
+    "4h": 6,
+    "1d": 1,
 }
 
 
 class Config(BaseModel):
     """EMA trend research — sweep EMA combos, score by Sharpe × persistence, show current signal state."""
 
-    connector: str = Field(default="binance_perpetual", description="Exchange connector")
+    connector: str = Field(
+        default="binance_perpetual", description="Exchange connector"
+    )
     pairs: str = Field(
         default="BTC-USDT,ETH-USDT,SOL-USDT",
         description="Comma-separated trading pairs",
     )
-    timeframe: str = Field(default="15m", description="Candle interval (1m/3m/15m/1h/4h)")
+    timeframe: str = Field(
+        default="15m", description="Candle interval (1m/3m/15m/1h/4h)"
+    )
     days: int = Field(default=30, description="Days of history to fetch")
-    hold_bars: int = Field(default=5, description="Bars ahead to measure post-signal move")
+    hold_bars: int = Field(
+        default=5, description="Bars ahead to measure post-signal move"
+    )
     fast_min: int = Field(default=5, description="Min fast EMA period")
     fast_max: int = Field(default=21, description="Max fast EMA period")
     slow_min: int = Field(default=21, description="Min slow EMA period")
     slow_max: int = Field(default=89, description="Max slow EMA period")
-    adx_filter: int = Field(default=0, description="Min ADX for a signal to count (0=disabled)")
+    adx_filter: int = Field(
+        default=0, description="Min ADX for a signal to count (0=disabled)"
+    )
     top_n: int = Field(default=5, description="Top N combos to show per pair")
 
 
@@ -308,7 +322,9 @@ def _grid(lo, hi, n=5):
     # ── Fetch ─────────────────────────────────────────────────────────────────
     data = {}
     for pair in pairs:
-        df = await _fetch_df(client, config.connector, pair, config.timeframe, config.days)
+        df = await _fetch_df(
+            client, config.connector, pair, config.timeframe, config.days
+        )
         if df is not None and len(df) >= min_bars:
             data[pair] = df
             logger.info(f"  {pair}/{config.timeframe}: {len(df)} candles")
@@ -344,7 +360,9 @@ def _grid(lo, hi, n=5):
             "adx_pct_trending": float((adx_s > 25).mean() * 100),
             "autocorr_lag1": round(autocorr, 4),
             "regime": (
-                "trend" if autocorr > 0.05 else ("mean-rev" if autocorr < -0.05 else "random")
+                "trend"
+                if autocorr > 0.05
+                else ("mean-rev" if autocorr < -0.05 else "random")
             ),
         }
 
@@ -371,9 +389,7 @@ def _grid(lo, hi, n=5):
     top3 = all_scored[:3]
 
     best_per_pair = {
-        pair: sweep_results[pair][0]
-        for pair in active_pairs
-        if sweep_results.get(pair)
+        pair: sweep_results[pair][0] for pair in active_pairs if sweep_results.get(pair)
     }
     current_signals = {
         pair: {
@@ -388,7 +404,9 @@ def _grid(lo, hi, n=5):
     fig.patch.set_facecolor("#0f172a")
     fig.suptitle(
         f"Returns Distribution & Realized Volatility — {config.days}d, {config.timeframe}",
-        fontsize=13, fontweight="bold", color="white",
+        fontsize=13,
+        fontweight="bold",
+        color="white",
     )
     for ci, pair in enumerate(active_pairs):
         df = data[pair]
@@ -399,21 +417,31 @@ def _grid(lo, hi, n=5):
         ax_h = axes[0, ci]
         _style_ax(ax_h)
         ax_h.hist(ret, bins=100, color=color, alpha=0.75, density=True)
-        ax_h.axvline(ret.mean(), color="white", linestyle="--", linewidth=1,
-                     label=f"μ={ret.mean():.4f}%")
+        ax_h.axvline(
+            ret.mean(),
+            color="white",
+            linestyle="--",
+            linewidth=1,
+            label=f"μ={ret.mean():.4f}%",
+        )
         ax_h.set_title(
             f"{pair}\nskew={s['ret_skew']:.2f}  kurt={s['ret_kurt']:.2f}",
-            fontsize=9, color="white",
+            fontsize=9,
+            color="white",
         )
         ax_h.set_xlabel("Return %", color="white", fontsize=7)
         ax_h.legend(fontsize=7, facecolor="#1e293b", labelcolor="white")
 
         ax_v = axes[1, ci]
         _style_ax(ax_v)
-        rvol = (ret.rolling(bars_per_day * 5).std() * math.sqrt(252 * bars_per_day)).dropna()
-        dt_slice = df["datetime"].iloc[-len(rvol):]
+        rvol = (
+            ret.rolling(bars_per_day * 5).std() * math.sqrt(252 * bars_per_day)
+        ).dropna()
+        dt_slice = df["datetime"].iloc[-len(rvol) :]
         ax_v.plot(dt_slice.values, rvol.values, color=color, linewidth=0.8)
-        ax_v.set_title(f"{pair} Ann. RVol\nμ={rvol.mean():.1f}%", fontsize=9, color="white")
+        ax_v.set_title(
+            f"{pair} Ann. RVol\nμ={rvol.mean():.1f}%", fontsize=9, color="white"
+        )
         ax_v.set_ylabel("RVol %", color="white", fontsize=7)
         ax_v.xaxis.set_major_formatter(mdates.DateFormatter("%m/%d"))
         ax_v.tick_params(axis="x", rotation=45)
@@ -431,7 +459,9 @@ def _grid(lo, hi, n=5):
     fig.patch.set_facecolor("#0f172a")
     fig.suptitle(
         f"ADX Distribution — Trend Regime ({config.days}d, {config.timeframe})",
-        fontsize=13, fontweight="bold", color="white",
+        fontsize=13,
+        fontweight="bold",
+        color="white",
     )
     for ci, pair in enumerate(active_pairs):
         df = data[pair]
@@ -444,12 +474,16 @@ def _grid(lo, hi, n=5):
         ax.hist(adx_s, bins=60, color=color, alpha=0.75)
         ax.axvline(25, color="#ef4444", linestyle="--", linewidth=1.2, label="ADX=25")
         ax.axvline(
-            float(adx_s.median()), color="white", linestyle="-.", linewidth=1,
+            float(adx_s.median()),
+            color="white",
+            linestyle="-.",
+            linewidth=1,
             label=f"median={adx_s.median():.1f}",
         )
         ax.set_title(
             f"{pair}\n{s['adx_pct_trending']:.0f}% time ADX>25",
-            fontsize=9, color="white",
+            fontsize=9,
+            color="white",
         )
         ax.legend(fontsize=7, facecolor="#1e293b", labelcolor="white")
         ax.set_xlabel("ADX", color="white", fontsize=7)
@@ -467,7 +501,9 @@ def _grid(lo, hi, n=5):
     fig.patch.set_facecolor("#0f172a")
     fig.suptitle(
         f"Best EMA Combo per Pair — Last 500 bars ({config.timeframe})",
-        fontsize=12, fontweight="bold", color="white",
+        fontsize=12,
+        fontweight="bold",
+        color="white",
     )
     for ri, pair in enumerate(active_pairs):
         if pair not in best_per_pair:
@@ -482,26 +518,59 @@ def _grid(lo, hi, n=5):
 
         ax = axes[ri, 0]
         _style_ax(ax)
-        ax.plot(df_c["datetime"], df_c["close"], color="white", linewidth=0.6,
-                label="Close", zorder=2)
-        ax.plot(df_c["datetime"], df_c["ema_f"], color="#3b82f6", linewidth=1.3,
-                label=f"EMA{fp}", zorder=3)
-        ax.plot(df_c["datetime"], df_c["ema_s"], color="#f59e0b", linewidth=1.3,
-                label=f"EMA{sp}", zorder=3)
+        ax.plot(
+            df_c["datetime"],
+            df_c["close"],
+            color="white",
+            linewidth=0.6,
+            label="Close",
+            zorder=2,
+        )
+        ax.plot(
+            df_c["datetime"],
+            df_c["ema_f"],
+            color="#3b82f6",
+            linewidth=1.3,
+            label=f"EMA{fp}",
+            zorder=3,
+        )
+        ax.plot(
+            df_c["datetime"],
+            df_c["ema_s"],
+            color="#f59e0b",
+            linewidth=1.3,
+            label=f"EMA{sp}",
+            zorder=3,
+        )
 
         longs = df_c[df_c["cross"] & (df_c["sig"] == 1)]
         shorts = df_c[df_c["cross"] & (df_c["sig"] == -1)]
-        ax.scatter(longs["datetime"], longs["close"], marker="^", color="#22c55e",
-                   s=50, zorder=5, label="Long")
-        ax.scatter(shorts["datetime"], shorts["close"], marker="v", color="#ef4444",
-                   s=50, zorder=5, label="Short")
+        ax.scatter(
+            longs["datetime"],
+            longs["close"],
+            marker="^",
+            color="#22c55e",
+            s=50,
+            zorder=5,
+            label="Long",
+        )
+        ax.scatter(
+            shorts["datetime"],
+            shorts["close"],
+            marker="v",
+            color="#ef4444",
+            s=50,
+            zorder=5,
+            label="Short",
+        )
 
         sig_label = "▲ LONG" if best["current_signal"] == 1 else "▼ SHORT"
         ax.set_title(
             f"{pair} {config.timeframe} | EMA{fp}/{sp} | score={best['score']:.3f} | "
             f"win={best['win_rate']:.0f}% | sharpe={best['sharpe']:.2f} | "
             f"persist={best['avg_persistence']:.0f}b | NOW: {sig_label}",
-            fontsize=9, color="white",
+            fontsize=9,
+            color="white",
         )
         ax.legend(fontsize=8, facecolor="#1e293b", labelcolor="white")
         ax.xaxis.set_major_formatter(mdates.DateFormatter("%m/%d %H:%M"))
@@ -540,7 +609,8 @@ def _grid(lo, hi, n=5):
         ax.set_ylabel("Fast EMA", color="white", fontsize=9)
         ax.set_title(
             f"{pair_hm} — EMA Score Heatmap (Sharpe × Persistence)",
-            fontsize=11, color="white",
+            fontsize=11,
+            color="white",
         )
         cbar = plt.colorbar(im, ax=ax)
         cbar.ax.tick_params(colors="white")
@@ -550,11 +620,18 @@ def _grid(lo, hi, n=5):
             bfi, bsi = fi.get(best_hm["fast"]), si.get(best_hm["slow"])
             if bfi is not None and bsi is not None:
                 ax.add_patch(
-                    plt.Rectangle((bsi - 0.5, bfi - 0.5), 1, 1, fill=False,
-                                  edgecolor="white", linewidth=2)
+                    plt.Rectangle(
+                        (bsi - 0.5, bfi - 0.5),
+                        1,
+                        1,
+                        fill=False,
+                        edgecolor="white",
+                        linewidth=2,
+                    )
+                )
+                ax.text(
+                    bsi, bfi, "★", ha="center", va="center", color="white", fontsize=14
                 )
-                ax.text(bsi, bfi, "★", ha="center", va="center",
-                        color="white", fontsize=14)
 
         plt.tight_layout()
         await context.bot.send_photo(
@@ -569,7 +646,9 @@ def _grid(lo, hi, n=5):
     fig.patch.set_facecolor("#0f172a")
     fig.suptitle(
         "Normalized Distance: (close − EMA_slow) / ATR(14)",
-        fontsize=11, fontweight="bold", color="white",
+        fontsize=11,
+        fontweight="bold",
+        color="white",
     )
     for ci, pair in enumerate(active_pairs):
         if pair not in best_per_pair:
@@ -590,7 +669,8 @@ def _grid(lo, hi, n=5):
         ax.axvline(0, color="white", linestyle="-", linewidth=0.5)
         ax.set_title(
             f"{pair} | EMA{sp}\nμ={norm_dist.mean():.2f}  σ={norm_dist.std():.2f}",
-            fontsize=9, color="white",
+            fontsize=9,
+            color="white",
         )
         ax.legend(fontsize=7, facecolor="#1e293b", labelcolor="white")
         ax.set_xlabel("(close − EMA) / ATR", color="white", fontsize=7)
@@ -681,12 +761,23 @@ def _grid(lo, hi, n=5):
     rb.markdown("## Top EMA Combos\n")
     rb.table(
         top3,
-        ["pair", "fast", "slow", "score", "win_rate", "sharpe",
-         "avg_persistence", "signals_per_day", "current_signal"],
+        [
+            "pair",
+            "fast",
+            "slow",
+            "score",
+            "win_rate",
+            "sharpe",
+            "avg_persistence",
+            "signals_per_day",
+            "current_signal",
+        ],
     )
     if top3:
         rb.markdown(f"## Recommendation\n\n{lines[-1]}")
-    rb.tags(["ema", "research", "trend"] + [p.split("-")[0].lower() for p in active_pairs])
+    rb.tags(
+        ["ema", "research", "trend"] + [p.split("-")[0].lower() for p in active_pairs]
+    )
     await rb.save()
 
     return summary
diff --git a/agents/market_making_expert/routines/hip3_market_scanner.py b/agents/market_making_expert/routines/hip3_market_scanner.py
index bb01e222..a41c8544 100644
--- a/agents/market_making_expert/routines/hip3_market_scanner.py
+++ b/agents/market_making_expert/routines/hip3_market_scanner.py
@@ -7,6 +7,7 @@
 import aiohttp
 from pydantic import BaseModel, Field
 from telegram.ext import ContextTypes
+
 from config_manager import get_client
 
 logger = logging.getLogger(__name__)
diff --git a/agents/market_making_expert/routines/market_analyzer.py b/agents/market_making_expert/routines/market_analyzer.py
index 8c0d5bab..f9215531 100644
--- a/agents/market_making_expert/routines/market_analyzer.py
+++ b/agents/market_making_expert/routines/market_analyzer.py
@@ -2,10 +2,12 @@
 
 import logging
 import math
+
 from pydantic import BaseModel, Field
 from telegram.ext import ContextTypes
-from config_manager import get_client
+
 from condor.reports.footprint import build_estimated_footprint_figure, candle_timestamps
+from config_manager import get_client
 
 logger = logging.getLogger(__name__)
 
@@ -474,6 +476,7 @@ def _norm(c):
 
     # Generate report
     import plotly.graph_objects as go
+
     from condor.reports import ReportBuilder
 
     builder = ReportBuilder(f"Market Analysis: {pair}")
diff --git a/agents/market_making_expert/routines/mm_dashboard.py b/agents/market_making_expert/routines/mm_dashboard.py
index a1c5cd3f..8f53a950 100644
--- a/agents/market_making_expert/routines/mm_dashboard.py
+++ b/agents/market_making_expert/routines/mm_dashboard.py
@@ -17,8 +17,10 @@
 import logging
 from collections import Counter
 from datetime import datetime, timezone
+
 from pydantic import BaseModel, Field
 from telegram.ext import ContextTypes
+
 from config_manager import get_client
 
 logger = logging.getLogger(__name__)
diff --git a/agents/meteora_launch_lp/routines/damm_v2_scanner.py b/agents/meteora_launch_lp/routines/damm_v2_scanner.py
index 52ba7d53..2bf6b3e6 100644
--- a/agents/meteora_launch_lp/routines/damm_v2_scanner.py
+++ b/agents/meteora_launch_lp/routines/damm_v2_scanner.py
@@ -14,6 +14,7 @@
 The scanner deliberately skips pools with an active fee scheduler (base fee often starts near 99%
 and decays — a token-launch trap) unless include_launch_pools is set.
 """
+
 import logging
 
 import aiohttp
@@ -39,14 +40,28 @@
 class Config(BaseModel):
     """Rank Meteora DAMM v2 pools by fee yield (fees/TVL) for AMM LP entry."""
 
-    quote_asset: str = Field(default="SOL", description="Quote token to require on one side: SOL, USDC, or USDT")
-    query: str | None = Field(default=None, description="Optional search (token symbol/name/address), e.g. 'JUP'")
-    ranking_window: str = Field(default="24h", description="Fee-yield window: 1h, 2h, 4h, 12h, or 24h")
+    quote_asset: str = Field(
+        default="SOL",
+        description="Quote token to require on one side: SOL, USDC, or USDT",
+    )
+    query: str | None = Field(
+        default=None,
+        description="Optional search (token symbol/name/address), e.g. 'JUP'",
+    )
+    ranking_window: str = Field(
+        default="24h", description="Fee-yield window: 1h, 2h, 4h, 12h, or 24h"
+    )
     top_n: int = Field(default=10, description="Number of ranked pools to return")
     min_tvl_usd: float = Field(default=25000.0, description="Minimum pool TVL in USD")
-    include_launch_pools: bool = Field(default=False, description="Include active-fee-scheduler (launch) pools")
-    verified_only: bool = Field(default=True, description="Require both tokens verified")
-    exclude_pools: list[str] = Field(default=[], description="Pool addresses to exclude (already held)")
+    include_launch_pools: bool = Field(
+        default=False, description="Include active-fee-scheduler (launch) pools"
+    )
+    verified_only: bool = Field(
+        default=True, description="Require both tokens verified"
+    )
+    exclude_pools: list[str] = Field(
+        default=[], description="Pool addresses to exclude (already held)"
+    )
 
 
 async def run(config: Config, context: ContextTypes.DEFAULT_TYPE) -> str:
@@ -70,7 +85,9 @@ async def run(config: Config, context: ContextTypes.DEFAULT_TYPE) -> str:
 
     try:
         async with aiohttp.ClientSession() as session:
-            async with session.get(DAMM_V2_API, params=params, timeout=aiohttp.ClientTimeout(total=20)) as resp:
+            async with session.get(
+                DAMM_V2_API, params=params, timeout=aiohttp.ClientTimeout(total=20)
+            ) as resp:
                 if resp.status != 200:
                     return f"damm_v2_scanner: Meteora DAMM v2 API returned HTTP {resp.status}"
                 payload = await resp.json()
@@ -93,50 +110,69 @@ async def run(config: Config, context: ContextTypes.DEFAULT_TYPE) -> str:
         cfg = p.get("pool_config", {}) or {}
         if not config.include_launch_pools and cfg.get("is_fee_scheduler_active"):
             continue  # skip launch pools whose base fee starts ~99%
-        if config.verified_only and not (tx.get("is_verified") and ty.get("is_verified")):
+        if config.verified_only and not (
+            tx.get("is_verified") and ty.get("is_verified")
+        ):
             continue
 
         # Base = the side that is NOT the quote asset.
         base, quote_tok = (ty, tx) if tx.get("address") == quote_mint else (tx, ty)
         fee_yield = float((p.get("fee_tvl_ratio") or {}).get(window) or 0)
-        candidates.append({
-            "pool": p.get("address"),
-            "pair": p.get("name") or f"{base.get('symbol','?')}-{quote_tok.get('symbol','?')}",
-            "base_symbol": base.get("symbol") or base.get("address", "")[:6],
-            "quote_symbol": quote_tok.get("symbol") or quote,
-            "base_mint": base.get("address"),
-            "quote_mint": quote_tok.get("address"),
-            "base_fee_pct": float(cfg.get("base_fee_pct") or 0),
-            "tvl": float(p.get("tvl") or 0),
-            "vol_win": float((p.get("volume") or {}).get(window) or 0),
-            "fee_yield": fee_yield,
-            "price": float(p.get("current_price") or 0),
-        })
+        candidates.append(
+            {
+                "pool": p.get("address"),
+                "pair": p.get("name")
+                or f"{base.get('symbol','?')}-{quote_tok.get('symbol','?')}",
+                "base_symbol": base.get("symbol") or base.get("address", "")[:6],
+                "quote_symbol": quote_tok.get("symbol") or quote,
+                "base_mint": base.get("address"),
+                "quote_mint": quote_tok.get("address"),
+                "base_fee_pct": float(cfg.get("base_fee_pct") or 0),
+                "tvl": float(p.get("tvl") or 0),
+                "vol_win": float((p.get("volume") or {}).get(window) or 0),
+                "fee_yield": fee_yield,
+                "price": float(p.get("current_price") or 0),
+            }
+        )
 
     if not candidates:
-        return (f"damm_v2_scanner: no {quote}-quoted DAMM v2 pools passed the filters "
-                f"(min TVL ${config.min_tvl_usd:,.0f}, verified_only={config.verified_only}, "
-                f"launch_pools={config.include_launch_pools}).")
+        return (
+            f"damm_v2_scanner: no {quote}-quoted DAMM v2 pools passed the filters "
+            f"(min TVL ${config.min_tvl_usd:,.0f}, verified_only={config.verified_only}, "
+            f"launch_pools={config.include_launch_pools})."
+        )
 
     candidates.sort(key=lambda c: c["fee_yield"], reverse=True)
     ranked = candidates[: config.top_n]
 
-    columns = ["#", "Pair", "FeeYield", "BaseFee", "TVL", f"Vol{window}", "Price", "Pool", "BaseMint"]
+    columns = [
+        "#",
+        "Pair",
+        "FeeYield",
+        "BaseFee",
+        "TVL",
+        f"Vol{window}",
+        "Price",
+        "Pool",
+        "BaseMint",
+    ]
     rows = []
     for i, c in enumerate(ranked, 1):
-        rows.append({
-            "#": i,
-            "Pair": c["pair"],
-            "FeeYield": f"{c['fee_yield'] * 100:.3f}%",
-            "BaseFee": f"{c['base_fee_pct']:.3f}%",
-            "TVL": f"${c['tvl']:,.0f}",
-            f"Vol{window}": f"${c['vol_win']:,.0f}",
-            "Price": f"{c['price']:.4g}",
-            "Pool": c["pool"],
-            "BaseMint": c["base_mint"],
-            # manage_amm hints (constant across rows): connector=meteora, network=solana-mainnet-beta.
-            "quote_mint": c["quote_mint"],
-        })
+        rows.append(
+            {
+                "#": i,
+                "Pair": c["pair"],
+                "FeeYield": f"{c['fee_yield'] * 100:.3f}%",
+                "BaseFee": f"{c['base_fee_pct']:.3f}%",
+                "TVL": f"${c['tvl']:,.0f}",
+                f"Vol{window}": f"${c['vol_win']:,.0f}",
+                "Price": f"{c['price']:.4g}",
+                "Pool": c["pool"],
+                "BaseMint": c["base_mint"],
+                # manage_amm hints (constant across rows): connector=meteora, network=solana-mainnet-beta.
+                "quote_mint": c["quote_mint"],
+            }
+        )
 
     top = rows[0]
     summary = (
@@ -150,10 +186,13 @@ async def run(config: Config, context: ContextTypes.DEFAULT_TYPE) -> str:
 
     try:
         from routines.base import RoutineResult
+
         return RoutineResult(text=summary, table_data=rows, table_columns=columns)
     except Exception:
         lines = [summary, ""]
         for r in rows:
-            lines.append(f"{r['#']}. {r['Pair']} | yield {r['FeeYield']} | fee {r['BaseFee']} | "
-                         f"TVL {r['TVL']} | pool {r['Pool']} | base {r['BaseMint']}")
+            lines.append(
+                f"{r['#']}. {r['Pair']} | yield {r['FeeYield']} | fee {r['BaseFee']} | "
+                f"TVL {r['TVL']} | pool {r['Pool']} | base {r['BaseMint']}"
+            )
         return "\n".join(lines)
diff --git a/agents/meteora_launch_lp/routines/easya_graduation_monitor.py b/agents/meteora_launch_lp/routines/easya_graduation_monitor.py
index 1fb19615..602a726e 100644
--- a/agents/meteora_launch_lp/routines/easya_graduation_monitor.py
+++ b/agents/meteora_launch_lp/routines/easya_graduation_monitor.py
@@ -14,6 +14,7 @@
 Note: early LP here is directional-long the token (you must buy the base token to pair it with SOL),
 so size small and capped.
 """
+
 import logging
 import time
 
@@ -35,22 +36,40 @@
 class Config(BaseModel):
     """Detect fresh EasyA graduations into Meteora DAMM v2, ranked by fee yield."""
 
-    max_age_hours: float = Field(default=72.0, description="Only pools created within this many hours")
-    min_tvl_usd: float = Field(default=10000.0, description="Minimum pool TVL in USD (graduation liquidity floor)")
-    min_vol24h_usd: float = Field(default=3000.0, description="Minimum 24h volume in USD (real post-grad demand)")
-    verified_only: bool = Field(default=False, description="Require the graduated token to be verified")
-    require_static_fee: bool = Field(default=True, description="Exclude fee-scheduler pools (EasyA grads are static)")
+    max_age_hours: float = Field(
+        default=72.0, description="Only pools created within this many hours"
+    )
+    min_tvl_usd: float = Field(
+        default=10000.0,
+        description="Minimum pool TVL in USD (graduation liquidity floor)",
+    )
+    min_vol24h_usd: float = Field(
+        default=3000.0, description="Minimum 24h volume in USD (real post-grad demand)"
+    )
+    verified_only: bool = Field(
+        default=False, description="Require the graduated token to be verified"
+    )
+    require_static_fee: bool = Field(
+        default=True, description="Exclude fee-scheduler pools (EasyA grads are static)"
+    )
     top_n: int = Field(default=15, description="Number of ranked graduations to return")
 
 
 async def run(config: Config, context: ContextTypes.DEFAULT_TYPE) -> str:
     # No created_at sort on the API, so fetch a wide TVL-sorted page and filter locally.
     # EasyA pools graduate with ~$10k+ TVL, so they are within the top page by TVL.
-    params = {"page": 1, "page_size": 1000, "sort_by": "tvl:desc", "filter_by": "is_blacklisted=false"}
+    params = {
+        "page": 1,
+        "page_size": 1000,
+        "sort_by": "tvl:desc",
+        "filter_by": "is_blacklisted=false",
+    }
 
     try:
         async with aiohttp.ClientSession() as session:
-            async with session.get(DAMM_V2_API, params=params, timeout=aiohttp.ClientTimeout(total=25)) as resp:
+            async with session.get(
+                DAMM_V2_API, params=params, timeout=aiohttp.ClientTimeout(total=25)
+            ) as resp:
                 if resp.status != 200:
                     return f"easya_graduation_monitor: Meteora DAMM v2 API returned HTTP {resp.status}"
                 payload = await resp.json()
@@ -84,50 +103,70 @@ async def run(config: Config, context: ContextTypes.DEFAULT_TYPE) -> str:
         if float((p.get("volume") or {}).get("24h") or 0) < config.min_vol24h_usd:
             continue
         cfg = p.get("pool_config", {}) or {}
-        if config.require_static_fee and (cfg.get("is_fee_scheduler_active") or cfg.get("has_fee_scheduler")):
+        if config.require_static_fee and (
+            cfg.get("is_fee_scheduler_active") or cfg.get("has_fee_scheduler")
+        ):
             continue
         if config.verified_only and not easy_side.get("is_verified"):
             continue
 
-        candidates.append({
-            "pool": p.get("address"),
-            "pair": p.get("name") or f"{easy_side.get('symbol','?')}-SOL",
-            "token_symbol": easy_side.get("symbol") or easy_side.get("address", "")[:6],
-            "base_mint": easy_side.get("address"),
-            "verified": bool(easy_side.get("is_verified")),
-            "base_fee_pct": float(cfg.get("base_fee_pct") or 0),
-            "tvl": float(p.get("tvl") or 0),
-            "vol24h": float((p.get("volume") or {}).get("24h") or 0),
-            "fee_yield24h": float((p.get("fee_tvl_ratio") or {}).get("24h") or 0),
-            "age_h": age_h,
-            "price": float(p.get("current_price") or 0),
-        })
+        candidates.append(
+            {
+                "pool": p.get("address"),
+                "pair": p.get("name") or f"{easy_side.get('symbol','?')}-SOL",
+                "token_symbol": easy_side.get("symbol")
+                or easy_side.get("address", "")[:6],
+                "base_mint": easy_side.get("address"),
+                "verified": bool(easy_side.get("is_verified")),
+                "base_fee_pct": float(cfg.get("base_fee_pct") or 0),
+                "tvl": float(p.get("tvl") or 0),
+                "vol24h": float((p.get("volume") or {}).get("24h") or 0),
+                "fee_yield24h": float((p.get("fee_tvl_ratio") or {}).get("24h") or 0),
+                "age_h": age_h,
+                "price": float(p.get("current_price") or 0),
+            }
+        )
 
     if not candidates:
-        return (f"easya_graduation_monitor: no EasyA graduations in the last {config.max_age_hours:.0f}h "
-                f"passed the filters (min TVL ${config.min_tvl_usd:,.0f}, min vol24h ${config.min_vol24h_usd:,.0f}, "
-                f"verified_only={config.verified_only}).")
+        return (
+            f"easya_graduation_monitor: no EasyA graduations in the last {config.max_age_hours:.0f}h "
+            f"passed the filters (min TVL ${config.min_tvl_usd:,.0f}, min vol24h ${config.min_vol24h_usd:,.0f}, "
+            f"verified_only={config.verified_only})."
+        )
 
     # Rank by traction: 24h fee yield (fees/TVL) — the ones actually earning.
     candidates.sort(key=lambda c: c["fee_yield24h"], reverse=True)
     ranked = candidates[: config.top_n]
 
-    columns = ["#", "Pair", "Age(h)", "FeeYield", "TVL", "Vol24h", "Verified", "Price", "Pool", "BaseMint"]
+    columns = [
+        "#",
+        "Pair",
+        "Age(h)",
+        "FeeYield",
+        "TVL",
+        "Vol24h",
+        "Verified",
+        "Price",
+        "Pool",
+        "BaseMint",
+    ]
     rows = []
     for i, c in enumerate(ranked, 1):
-        rows.append({
-            "#": i,
-            "Pair": c["pair"],
-            "Age(h)": f"{c['age_h']:.1f}",
-            "FeeYield": f"{c['fee_yield24h'] * 100:.1f}%",
-            "TVL": f"${c['tvl']:,.0f}",
-            "Vol24h": f"${c['vol24h']:,.0f}",
-            "Verified": "yes" if c["verified"] else "no",
-            "Price": f"{c['price']:.4g}",
-            "Pool": c["pool"],
-            "BaseMint": c["base_mint"],
-            "quote_mint": SOL_MINT,
-        })
+        rows.append(
+            {
+                "#": i,
+                "Pair": c["pair"],
+                "Age(h)": f"{c['age_h']:.1f}",
+                "FeeYield": f"{c['fee_yield24h'] * 100:.1f}%",
+                "TVL": f"${c['tvl']:,.0f}",
+                "Vol24h": f"${c['vol24h']:,.0f}",
+                "Verified": "yes" if c["verified"] else "no",
+                "Price": f"{c['price']:.4g}",
+                "Pool": c["pool"],
+                "BaseMint": c["base_mint"],
+                "quote_mint": SOL_MINT,
+            }
+        )
 
     top = rows[0]
     summary = (
@@ -141,10 +180,13 @@ async def run(config: Config, context: ContextTypes.DEFAULT_TYPE) -> str:
 
     try:
         from routines.base import RoutineResult
+
         return RoutineResult(text=summary, table_data=rows, table_columns=columns)
     except Exception:
         lines = [summary, ""]
         for r in rows:
-            lines.append(f"{r['#']}. {r['Pair']} | age {r['Age(h)']}h | yield {r['FeeYield']} | "
-                         f"TVL {r['TVL']} | vol {r['Vol24h']} | verified {r['Verified']} | pool {r['Pool']}")
+            lines.append(
+                f"{r['#']}. {r['Pair']} | age {r['Age(h)']}h | yield {r['FeeYield']} | "
+                f"TVL {r['TVL']} | vol {r['Vol24h']} | verified {r['Verified']} | pool {r['Pool']}"
+            )
         return "\n".join(lines)
diff --git a/agents/meteora_launch_lp/routines/launch_safety_check.py b/agents/meteora_launch_lp/routines/launch_safety_check.py
index d7f27d7d..ed228db0 100644
--- a/agents/meteora_launch_lp/routines/launch_safety_check.py
+++ b/agents/meteora_launch_lp/routines/launch_safety_check.py
@@ -12,6 +12,7 @@
 RPC: defaults to the public mainnet endpoint (rate-limited but fine for occasional checks); override
 with rpc_url for a private endpoint. No credentials are hardcoded.
 """
+
 import logging
 
 import aiohttp
@@ -39,17 +40,32 @@ def _rpc_url_default(cls, v):
         # Callers (e.g. strategy configs) may pass an empty string meaning "no private RPC" —
         # fall back to the public endpoint instead of failing every RPC gate on an invalid URL.
         return v or DEFAULT_RPC
-    max_top10_holder_pct: float = Field(default=60.0, description="Fail if top-10 holders exceed this % of supply")
-    require_mint_renounced: bool = Field(default=True, description="Fail if the token mint authority is not renounced")
-    require_freeze_disabled: bool = Field(default=True, description="Fail if the freeze authority is not disabled")
-    require_verified: bool = Field(default=False, description="Fail if the token is not verified")
-    min_lock_pct: float = Field(default=0.0, description="Require locked+vested liquidity ≥ this % of TVL (0 = off)")
+
+    max_top10_holder_pct: float = Field(
+        default=60.0, description="Fail if top-10 holders exceed this % of supply"
+    )
+    require_mint_renounced: bool = Field(
+        default=True, description="Fail if the token mint authority is not renounced"
+    )
+    require_freeze_disabled: bool = Field(
+        default=True, description="Fail if the freeze authority is not disabled"
+    )
+    require_verified: bool = Field(
+        default=False, description="Fail if the token is not verified"
+    )
+    min_lock_pct: float = Field(
+        default=0.0,
+        description="Require locked+vested liquidity ≥ this % of TVL (0 = off)",
+    )
     min_tvl_usd: float = Field(default=10000.0, description="Fail below this TVL")
 
 
 async def _rpc(session, url, method, params):
-    async with session.post(url, json={"jsonrpc": "2.0", "id": 1, "method": method, "params": params},
-                            timeout=aiohttp.ClientTimeout(total=20)) as r:
+    async with session.post(
+        url,
+        json={"jsonrpc": "2.0", "id": 1, "method": method, "params": params},
+        timeout=aiohttp.ClientTimeout(total=20),
+    ) as r:
         if r.status != 200:
             raise RuntimeError(f"RPC {method} -> HTTP {r.status}")
         data = await r.json()
@@ -64,8 +80,11 @@ async def run(config: Config, context: ContextTypes.DEFAULT_TYPE) -> str:
     # 1. Pool + token metadata from the Meteora DAMM v2 API.
     try:
         async with aiohttp.ClientSession() as session:
-            async with session.get(DAMM_V2_API, params={"query": config.pool_address, "page_size": 1},
-                                   timeout=aiohttp.ClientTimeout(total=20)) as resp:
+            async with session.get(
+                DAMM_V2_API,
+                params={"query": config.pool_address, "page_size": 1},
+                timeout=aiohttp.ClientTimeout(total=20),
+            ) as resp:
                 if resp.status != 200:
                     return f"launch_safety_check: Meteora API HTTP {resp.status}"
                 pool = (await resp.json()).get("data", [{}])[0]
@@ -82,45 +101,99 @@ async def run(config: Config, context: ContextTypes.DEFAULT_TYPE) -> str:
     cfg = pool.get("pool_config", {}) or {}
 
     # Static gates from the API.
-    gates.append(("tvl", tvl >= config.min_tvl_usd, f"${tvl:,.0f} (min ${config.min_tvl_usd:,.0f})"))
+    gates.append(
+        (
+            "tvl",
+            tvl >= config.min_tvl_usd,
+            f"${tvl:,.0f} (min ${config.min_tvl_usd:,.0f})",
+        )
+    )
     if config.require_verified:
-        gates.append(("verified", bool(base.get("is_verified")), f"{base.get('symbol')} verified={base.get('is_verified')}"))
+        gates.append(
+            (
+                "verified",
+                bool(base.get("is_verified")),
+                f"{base.get('symbol')} verified={base.get('is_verified')}",
+            )
+        )
     if config.require_freeze_disabled:
-        gates.append(("freeze_disabled", bool(base.get("freeze_authority_disabled")),
-                      f"freeze_authority_disabled={base.get('freeze_authority_disabled')}"))
+        gates.append(
+            (
+                "freeze_disabled",
+                bool(base.get("freeze_authority_disabled")),
+                f"freeze_authority_disabled={base.get('freeze_authority_disabled')}",
+            )
+        )
     if config.min_lock_pct > 0:
         locked = float(pool.get("permanent_lock_liquidity") or 0)
-        vested = sum(float(v or 0) for v in (pool.get("vested_liquidity") or {}).values())
+        vested = sum(
+            float(v or 0) for v in (pool.get("vested_liquidity") or {}).values()
+        )
         lock_pct = (locked + vested) / tvl * 100 if tvl else 0.0
-        gates.append(("lp_lock", lock_pct >= config.min_lock_pct, f"{lock_pct:.1f}% locked/vested (min {config.min_lock_pct}%)"))
+        gates.append(
+            (
+                "lp_lock",
+                lock_pct >= config.min_lock_pct,
+                f"{lock_pct:.1f}% locked/vested (min {config.min_lock_pct}%)",
+            )
+        )
 
     # 2. On-chain gates via RPC: mint authority + top-holder concentration.
     try:
         async with aiohttp.ClientSession() as session:
             if config.require_mint_renounced:
-                info = await _rpc(session, config.rpc_url, "getAccountInfo",
-                                  [base_mint, {"encoding": "jsonParsed"}])
-                parsed = ((info or {}).get("value") or {}).get("data", {}).get("parsed", {}).get("info", {})
+                info = await _rpc(
+                    session,
+                    config.rpc_url,
+                    "getAccountInfo",
+                    [base_mint, {"encoding": "jsonParsed"}],
+                )
+                parsed = (
+                    ((info or {}).get("value") or {})
+                    .get("data", {})
+                    .get("parsed", {})
+                    .get("info", {})
+                )
                 mint_auth = parsed.get("mintAuthority")
-                gates.append(("mint_renounced", mint_auth is None, f"mintAuthority={mint_auth or 'null (renounced)'}"))
-
-            supply_res = await _rpc(session, config.rpc_url, "getTokenSupply", [base_mint])
+                gates.append(
+                    (
+                        "mint_renounced",
+                        mint_auth is None,
+                        f"mintAuthority={mint_auth or 'null (renounced)'}",
+                    )
+                )
+
+            supply_res = await _rpc(
+                session, config.rpc_url, "getTokenSupply", [base_mint]
+            )
             total = float((supply_res or {}).get("value", {}).get("uiAmount") or 0)
-            largest = await _rpc(session, config.rpc_url, "getTokenLargestAccounts", [base_mint])
+            largest = await _rpc(
+                session, config.rpc_url, "getTokenLargestAccounts", [base_mint]
+            )
             accounts = (largest or {}).get("value", [])
             top10 = sum(float(a.get("uiAmount") or 0) for a in accounts[:10])
             top10_pct = (top10 / total * 100) if total else 100.0
-            gates.append(("holder_concentration", top10_pct <= config.max_top10_holder_pct,
-                          f"top-10 hold {top10_pct:.1f}% (max {config.max_top10_holder_pct}%)"))
+            gates.append(
+                (
+                    "holder_concentration",
+                    top10_pct <= config.max_top10_holder_pct,
+                    f"top-10 hold {top10_pct:.1f}% (max {config.max_top10_holder_pct}%)",
+                )
+            )
     except Exception as e:
         gates.append(("rpc_checks", False, f"RPC checks failed: {e}"))
 
     passed_all = all(ok for _, ok, _ in gates)
-    lines = [f"Safety check for {base.get('symbol','?')} ({base_mint}) — pool {config.pool_address}",
-             f"VERDICT: {'PASS' if passed_all else 'FAIL'}", ""]
+    lines = [
+        f"Safety check for {base.get('symbol','?')} ({base_mint}) — pool {config.pool_address}",
+        f"VERDICT: {'PASS' if passed_all else 'FAIL'}",
+        "",
+    ]
     for name, ok, detail in gates:
         lines.append(f"  [{'PASS' if ok else 'FAIL'}] {name}: {detail}")
     lines.append("")
-    lines.append("NOTE: sellability (honeypot) is NOT checked here — round-trip a SELL and BUY quote via "
-                 "manage_amm(quote_swap) before entering. See the launch_safety_check skill.")
+    lines.append(
+        "NOTE: sellability (honeypot) is NOT checked here — round-trip a SELL and BUY quote via "
+        "manage_amm(quote_swap) before entering. See the launch_safety_check skill."
+    )
     return "\n".join(lines)
diff --git a/agents/smart_money_flow/routines/onchain_flow.py b/agents/smart_money_flow/routines/onchain_flow.py
index dd8b152b..99f7eb28 100644
--- a/agents/smart_money_flow/routines/onchain_flow.py
+++ b/agents/smart_money_flow/routines/onchain_flow.py
@@ -17,10 +17,13 @@
 Execution venue is independent of this signal: pair the read with Derive perps
 (`derive_perpetual`) — or any perp connector — via the agent's trading context.
 """
+
 import asyncio
 import logging
+
 from pydantic import BaseModel, Field
 from telegram.ext import ContextTypes
+
 from config_manager import get_client
 
 logger = logging.getLogger(__name__)
@@ -47,6 +50,7 @@
 
 class Config(BaseModel):
     """Compute the Smart-Money Flow composite: cross-market + Solana on-chain pulse."""
+
     context_assets: str = Field(
         default="bitcoin,ethereum,solana",
         description="Comma-separated CoinGecko ids for regime + per-asset flow read",
@@ -63,11 +67,14 @@ class Config(BaseModel):
         default="",
         description="OPTIONAL comma-separated XRPL addresses to watch (empty = skip)",
     )
-    top_n_trending: int = Field(default=7, description="Trending coins to factor into momentum")
+    top_n_trending: int = Field(
+        default=7, description="Trending coins to factor into momentum"
+    )
 
 
 # ── helpers ────────────────────────────────────────────────────────────────
 
+
 async def _get_json(url: str, timeout: float = 12) -> "dict | list | None":
     import httpx
 
@@ -96,6 +103,7 @@ def _num(v) -> float:
 
 # ── raw fetchers (pure async, importable) ──────────────────────────────────
 
+
 async def fetch_global() -> "dict | list | None":
     return await _get_json(f"{CG}/global")
 
@@ -125,7 +133,9 @@ async def fetch_solana_pulse(top_n: int = 10) -> dict | None:
     read. Solana carries materially deeper on-chain liquidity than XRPL, so it is
     the DEFAULT on-chain signal source.
     """
-    data = await _get_json(f"{GECKO}/networks/solana/tokens/{SOL_MINT}/pools?page=1&include=base_token,dex")
+    data = await _get_json(
+        f"{GECKO}/networks/solana/tokens/{SOL_MINT}/pools?page=1&include=base_token,dex"
+    )
     if not data:
         return None
     pools = []
@@ -135,13 +145,15 @@ async def fetch_solana_pulse(top_n: int = 10) -> dict | None:
         tvl = _num(a.get("reserve_in_usd"))
         if tvl < 50_000:  # skip dust/illiquid pools (meaningless momentum)
             continue
-        pools.append({
-            "name": a.get("name", "?"),
-            "dex": a.get("dex_id", ""),
-            "vol24h": vol,
-            "chg24h": _num(a.get("price_change_percentage", {}).get("h24")),
-            "tvl": tvl,
-        })
+        pools.append(
+            {
+                "name": a.get("name", "?"),
+                "dex": a.get("dex_id", ""),
+                "vol24h": vol,
+                "chg24h": _num(a.get("price_change_percentage", {}).get("h24")),
+                "tvl": tvl,
+            }
+        )
     if not pools:
         return None
     total_vol = sum(p["vol24h"] for p in pools)
@@ -165,8 +177,12 @@ async def fetch_xrpl_amm_pulse(issuer: str) -> dict | None:
         return None
     payload = {
         "method": "amm_info",
-        "params": [{"asset": {"currency": "XRP"},
-                    "asset2": {"currency": "RLUSD", "issuer": issuer}}],
+        "params": [
+            {
+                "asset": {"currency": "XRP"},
+                "asset2": {"currency": "RLUSD", "issuer": issuer},
+            }
+        ],
     }
     import httpx
 
@@ -185,18 +201,26 @@ async def fetch_xrpl_amm_pulse(issuer: str) -> dict | None:
                 xrp = 0.0
             return {"xrp_liquidity": xrp, "trading_fee_bps": amm.get("trading_fee")}
         except Exception as exc:
-            logger.warning("flow: xrpl amm pulse failed on %s: %s", node, type(exc).__name__)
+            logger.warning(
+                "flow: xrpl amm pulse failed on %s: %s", node, type(exc).__name__
+            )
             continue
     return None
 
 
 # ── synthesis (pure, importable) ───────────────────────────────────────────
 
+
 def synthesize(global_d, markets_d, trending_syms, solana_pulse, xrpl_amm) -> dict:
     """Turn raw fetches into a multi-asset flow composite. Returns a structured dict."""
     # --- risk regime from /global ---
-    regime = {"label": "NEUTRAL", "mcap_change_24h": 0.0, "btc_dominance": 0.0,
-              "eth_dominance": 0.0, "score": 0.0}
+    regime = {
+        "label": "NEUTRAL",
+        "mcap_change_24h": 0.0,
+        "btc_dominance": 0.0,
+        "eth_dominance": 0.0,
+        "score": 0.0,
+    }
     if global_d:
         g = global_d.get("data", {})
         mc = _num(g.get("market_cap_change_percentage_24h_usd"))
@@ -208,12 +232,16 @@ def synthesize(global_d, markets_d, trending_syms, solana_pulse, xrpl_amm) -> di
         regime["eth_dominance"] = round(eth_d, 2)
         risk_score = _clamp(mc / 5.0) - _clamp((btc_d - 50.0) / 10.0) * 0.3
         regime["score"] = round(_clamp(risk_score), 3)
-        regime["label"] = "RISK-ON" if regime["score"] > 0.15 else ("RISK-OFF" if regime["score"] < -0.15 else "NEUTRAL")
+        regime["label"] = (
+            "RISK-ON"
+            if regime["score"] > 0.15
+            else ("RISK-OFF" if regime["score"] < -0.15 else "NEUTRAL")
+        )
 
     # --- per-asset flow intensity from /coins/markets ---
     trending_set = {s.upper() for s in trending_syms}
     assets_out = []
-    for m in (markets_d or []):
+    for m in markets_d or []:
         sym = (m.get("symbol") or "").upper()
         mcap = _num(m.get("market_cap"))
         vol = _num(m.get("total_volume"))
@@ -226,14 +254,16 @@ def synthesize(global_d, markets_d, trending_syms, solana_pulse, xrpl_amm) -> di
         flow = _clamp(vol_mcap * 5.0, -0.5, 0.5) * 0.4 + _clamp(chg / 6.0) * 0.6
         if sym in trending_set:
             flow = _clamp(flow + 0.1)
-        assets_out.append({
-            "symbol": sym,
-            "pair": f"{sym}-USDC",
-            "flow_score": round(flow, 3),
-            "volume_to_mcap": round(vol_mcap, 3),
-            "price_change_24h": round(chg, 2),
-            "trending": sym in trending_set,
-        })
+        assets_out.append(
+            {
+                "symbol": sym,
+                "pair": f"{sym}-USDC",
+                "flow_score": round(flow, 3),
+                "volume_to_mcap": round(vol_mcap, 3),
+                "price_change_24h": round(chg, 2),
+                "trending": sym in trending_set,
+            }
+        )
     assets_out.sort(key=lambda a: abs(a["flow_score"]), reverse=True)
 
     # --- on-chain pulse (Solana default; XRPL optional) ---
@@ -276,25 +306,34 @@ def _format_verdict(sig: dict) -> str:
         f"- Verdict: **{sig['direction']}** ({sig['rationale']})",
     ]
     if best:
-        lines.append(f"- Best flow: **{best['symbol']}** score {best['flow_score']:+.2f} "
-                     f"(vol/mcap {best['volume_to_mcap']}, 24h {best['price_change_24h']:+.2f}%, trend={best['trending']})")
+        lines.append(
+            f"- Best flow: **{best['symbol']}** score {best['flow_score']:+.2f} "
+            f"(vol/mcap {best['volume_to_mcap']}, 24h {best['price_change_24h']:+.2f}%, trend={best['trending']})"
+        )
     sp = sig["onchain"].get("solana")
     if sp:
-        lines.append(f"- Solana on-chain pulse: flow {sp['flow_score']:+.2f}, "
-                     f"top-pool vol24h ${sp['total_vol24h']:,.0f}, median chg {sp['median_chg24h']:+.1f}%")
+        lines.append(
+            f"- Solana on-chain pulse: flow {sp['flow_score']:+.2f}, "
+            f"top-pool vol24h ${sp['total_vol24h']:,.0f}, median chg {sp['median_chg24h']:+.1f}%"
+        )
         for p in sp["pools"][:4]:
-            lines.append(f"    - {p['name'][:24]:24} vol ${p['vol24h']:,.0f} chg {p['chg24h']:+.1f}%")
+            lines.append(
+                f"    - {p['name'][:24]:24} vol ${p['vol24h']:,.0f} chg {p['chg24h']:+.1f}%"
+            )
     if sig["onchain"].get("xrpl"):
         lines.append(f"- XRPL AMM pulse: {sig['onchain']['xrpl']}")
     lines.append("- Per-asset:")
     for a in sig["assets"][:5]:
-        lines.append(f"    - {a['symbol']}: {a['flow_score']:+.2f}  "
-                     f"(vol/mcap {a['volume_to_mcap']}, 24h {a['price_change_24h']:+.2f}%, trend={a['trending']})")
+        lines.append(
+            f"    - {a['symbol']}: {a['flow_score']:+.2f}  "
+            f"(vol/mcap {a['volume_to_mcap']}, 24h {a['price_change_24h']:+.2f}%, trend={a['trending']})"
+        )
     return "\n".join(lines)
 
 
 # ── orchestration ──────────────────────────────────────────────────────────
 
+
 async def run(config: Config, context: ContextTypes.DEFAULT_TYPE) -> str:
     """Entry point invoked by manage_routines. Fetches, scores, reports, returns."""
     ids = [s.strip() for s in config.context_assets.split(",") if s.strip()]
@@ -305,7 +344,11 @@ async def run(config: Config, context: ContextTypes.DEFAULT_TYPE) -> str:
         fetch_markets(ids),
         fetch_solana_pulse(config.solana_top_n),
     )
-    xrpl_amm = await fetch_xrpl_amm_pulse(config.xrpl_amm_issuer) if config.xrpl_amm_issuer else None
+    xrpl_amm = (
+        await fetch_xrpl_amm_pulse(config.xrpl_amm_issuer)
+        if config.xrpl_amm_issuer
+        else None
+    )
 
     sig = synthesize(global_d, markets, trending, solana, xrpl_amm)
 
@@ -314,8 +357,13 @@ async def run(config: Config, context: ContextTypes.DEFAULT_TYPE) -> str:
         from condor.reports import ReportBuilder
 
         builder = ReportBuilder("Smart-Money Flow")
-        builder.source("routine", "onchain_flow").tags(["flow", "on-chain", "solana", "smart-money"])
-        builder.section("01 / RISK REGIME", "Cross-market risk-on/off from total mcap momentum and BTC dominance")
+        builder.source("routine", "onchain_flow").tags(
+            ["flow", "on-chain", "solana", "smart-money"]
+        )
+        builder.section(
+            "01 / RISK REGIME",
+            "Cross-market risk-on/off from total mcap momentum and BTC dominance",
+        )
         builder.kpi("Regime", sig["regime"]["label"])
         builder.kpi("Mcap 24h", f"{sig['regime']['mcap_change_24h']:+.2f}%")
         builder.kpi("BTC Dominance", f"{sig['regime']['btc_dominance']:.1f}%")
@@ -323,14 +371,29 @@ async def run(config: Config, context: ContextTypes.DEFAULT_TYPE) -> str:
         builder.kpi("Solana Flow", f"{sig['solana_flow']:+.2f}")
         sp = sig["onchain"].get("solana")
         if sp:
-            builder.section("02 / SOLANA ON-CHAIN PULSE", "SOL top pools by 24h volume — crypto-native flow")
+            builder.section(
+                "02 / SOLANA ON-CHAIN PULSE",
+                "SOL top pools by 24h volume — crypto-native flow",
+            )
             builder.kpi("Top-pool Vol 24h", f"${sp['total_vol24h']:,.0f}")
             builder.kpi("Median Chg 24h", f"{sp['median_chg24h']:+.1f}%")
             builder.kpi("On-chain Flow", f"{sp['flow_score']:+.2f}")
             builder.table(sp["pools"][:8], ["name", "dex", "vol24h", "chg24h", "tvl"])
         if sig["assets"]:
-            builder.section("03 / CROSS-MARKET CONTEXT", "Market-wide flow intensity (BTC/ETH/SOL)")
-            builder.table(sig["assets"][:6], ["symbol", "pair", "flow_score", "volume_to_mcap", "price_change_24h", "trending"])
+            builder.section(
+                "03 / CROSS-MARKET CONTEXT", "Market-wide flow intensity (BTC/ETH/SOL)"
+            )
+            builder.table(
+                sig["assets"][:6],
+                [
+                    "symbol",
+                    "pair",
+                    "flow_score",
+                    "volume_to_mcap",
+                    "price_change_24h",
+                    "trending",
+                ],
+            )
         builder.markdown(_format_verdict(sig))
         builder.manual_order()
         await builder.save()
diff --git a/agents/solana_dex_lp_expert/routines/lp_scanner.py b/agents/solana_dex_lp_expert/routines/lp_scanner.py
index f374459f..2a8ff926 100644
--- a/agents/solana_dex_lp_expert/routines/lp_scanner.py
+++ b/agents/solana_dex_lp_expert/routines/lp_scanner.py
@@ -16,12 +16,14 @@
 hold — the agent should never open a 2nd slot on the same pool or token.
 """
 
-import logging
 import asyncio
+import logging
 import re
+
 import aiohttp
 from pydantic import BaseModel, Field, field_validator
 from telegram.ext import ContextTypes
+
 from config_manager import get_client
 from handlers.dex.geckoterminal import _extract_pool_data
 
diff --git a/agents/xrpl_market_maker/routines/xrpl_mm_quote_planner.py b/agents/xrpl_market_maker/routines/xrpl_mm_quote_planner.py
index 8a5d7643..ce497905 100644
--- a/agents/xrpl_market_maker/routines/xrpl_mm_quote_planner.py
+++ b/agents/xrpl_market_maker/routines/xrpl_mm_quote_planner.py
@@ -1,4 +1,5 @@
 """Plan XRPL CLOB maker quotes: reference fair value, spread bounds, viability verdict."""
+
 import asyncio
 import logging
 import math
@@ -27,10 +28,30 @@
 # 733 days of Bitget perp 1H bars. Values are vol relative to the daily average.
 # Trough 04:00-11:00 UTC (Asia afternoon / pre-Europe); peak 13:00-15:00 UTC (US open).
 HOUR_VOL_MULT = {
-    0: 1.03, 1: 1.10, 2: 0.95, 3: 0.89, 4: 0.82, 5: 0.85,
-    6: 0.82, 7: 0.82, 8: 0.91, 9: 0.83, 10: 0.78, 11: 0.82,
-    12: 0.92, 13: 1.28, 14: 1.50, 15: 1.40, 16: 1.16, 17: 1.21,
-    18: 1.07, 19: 1.04, 20: 1.02, 21: 0.97, 22: 0.97, 23: 0.82,
+    0: 1.03,
+    1: 1.10,
+    2: 0.95,
+    3: 0.89,
+    4: 0.82,
+    5: 0.85,
+    6: 0.82,
+    7: 0.82,
+    8: 0.91,
+    9: 0.83,
+    10: 0.78,
+    11: 0.82,
+    12: 0.92,
+    13: 1.28,
+    14: 1.50,
+    15: 1.40,
+    16: 1.16,
+    17: 1.21,
+    18: 1.07,
+    19: 1.04,
+    20: 1.02,
+    21: 0.97,
+    22: 0.97,
+    23: 0.82,
 }
 MS_PER_HOUR = 3_600_000
 
@@ -38,11 +59,15 @@
 class Config(BaseModel):
     """Plan maker quotes for an XRPL CLOB pair against a CEX reference price."""
 
-    xrpl_pair: str = Field(default="RLUSD-XRP", description="Pair as the xrpl connector names it")
+    xrpl_pair: str = Field(
+        default="RLUSD-XRP", description="Pair as the xrpl connector names it"
+    )
     reference_connector: str = Field(
         default="bitget_perpetual", description="CEX connector supplying fair value"
     )
-    reference_pair: str = Field(default="XRP-USDT", description="Reference pair for XRP/USD")
+    reference_pair: str = Field(
+        default="XRP-USDT", description="Reference pair for XRP/USD"
+    )
     tick_interval_sec: int = Field(default=300, description="Seconds between LLM ticks")
     requote_interval_sec: int = Field(
         default=0,
@@ -51,9 +76,12 @@ class Config(BaseModel):
         "tick — the bot requotes without the agent, so the LLM tick must not set the floor",
     )
     levels_per_side: int = Field(default=3, description="Quote levels per side")
-    total_amount_quote: float = Field(default=100.0, description="Capital to deploy, USD")
+    total_amount_quote: float = Field(
+        default=100.0, description="Capital to deploy, USD"
+    )
     adverse_k: float = Field(
-        default=1.0, description="Multiplier on expected adverse move; higher = wider floor"
+        default=1.0,
+        description="Multiplier on expected adverse move; higher = wider floor",
     )
     use_vol_clock: bool = Field(
         default=True,
@@ -63,9 +91,12 @@ class Config(BaseModel):
         default=0.1, description="Assumed AMM fee %% if amm_info is unreachable"
     )
     amm_asset2_issuer: str = Field(
-        default="", description="Issuer address of the non-XRP asset (blank = skip amm_info)"
+        default="",
+        description="Issuer address of the non-XRP asset (blank = skip amm_info)",
+    )
+    amm_asset2_currency: str = Field(
+        default="RLUSD", description="Non-XRP asset currency code"
     )
-    amm_asset2_currency: str = Field(default="RLUSD", description="Non-XRP asset currency code")
 
 
 # ── helpers ──────────────────────────────────────────────────────────────────
@@ -115,7 +146,12 @@ async def _fetch_amm_fee_pct(currency: str, issuer: str) -> tuple[float | None,
         return None, "no issuer configured — amm_info skipped"
     payload = {
         "method": "amm_info",
-        "params": [{"asset": {"currency": "XRP"}, "asset2": {"currency": currency, "issuer": issuer}}],
+        "params": [
+            {
+                "asset": {"currency": "XRP"},
+                "asset2": {"currency": currency, "issuer": issuer},
+            }
+        ],
     }
     try:
         async with httpx.AsyncClient(timeout=10) as http:
@@ -180,9 +216,14 @@ async def run(config: Config, context: ContextTypes.DEFAULT_TYPE) -> str:
     try:
         candles_raw, ref_prices = await asyncio.gather(
             client.market_data.get_candles(
-                config.reference_connector, config.reference_pair, interval="1m", max_records=120
+                config.reference_connector,
+                config.reference_pair,
+                interval="1m",
+                max_records=120,
+            ),
+            client.market_data.get_prices(
+                config.reference_connector, [config.reference_pair]
             ),
-            client.market_data.get_prices(config.reference_connector, [config.reference_pair]),
         )
     except Exception as exc:
         return f"reference_price: ERROR fetching {config.reference_pair} — {exc}"
@@ -198,7 +239,9 @@ async def run(config: Config, context: ContextTypes.DEFAULT_TYPE) -> str:
     implied_xrpl_price = (1.0 / ref_mid) if ref_mid > 0 else 0.0
 
     out.append("=== REFERENCE (fair value source) ===")
-    out.append(f"reference_pair: {config.reference_pair} @ {config.reference_connector}")
+    out.append(
+        f"reference_pair: {config.reference_pair} @ {config.reference_connector}"
+    )
     out.append(f"reference_mid_usd: {ref_mid:.6f}")
     out.append(f"implied_{config.xrpl_pair}: {implied_xrpl_price:.6f}  (1 / XRP-USD)")
 
@@ -251,7 +294,9 @@ def _utc(ms: int) -> str:
         f"(UTC {_utc(now_ms)}-{_utc(fwd_end_ms)}, quote live window)"
     )
     out.append(f"vol_adjusted: {vol_adj * math.sqrt(60) * 100:.4f}% per minute")
-    out.append(f"tick_interval_sec: {config.tick_interval_sec}  (LLM reasoning cadence)")
+    out.append(
+        f"tick_interval_sec: {config.tick_interval_sec}  (LLM reasoning cadence)"
+    )
     out.append(
         f"requote_interval_sec: {requote_sec}  (quote exposure — THIS sets the floor)"
     )
@@ -281,7 +326,9 @@ def _utc(ms: int) -> str:
     out.append("")
     out.append("=== SPREAD CEILING (AMM fee to undercut) ===")
     out.append(f"amm_trading_fee_pct: {amm_fee_pct:.4f}%   ({fee_note})")
-    out.append(f"spread_ceiling_bps: {ceiling_bps:.2f}  (quote wider and flow routes to the AMM)")
+    out.append(
+        f"spread_ceiling_bps: {ceiling_bps:.2f}  (quote wider and flow routes to the AMM)"
+    )
 
     # 4. Viability — the load-bearing verdict.
     viable = floor_bps < ceiling_bps
@@ -345,7 +392,9 @@ def _utc(ms: int) -> str:
     # A controller's total_amount_quote is denominated in the pair's QUOTE asset. On
     # RLUSD-XRP that is XRP, not USD — passing a USD figure straight through oversizes
     # the deployment by the XRP price (~3x), silently breaching the risk limit.
-    quote_asset = config.xrpl_pair.split("-")[-1].upper() if "-" in config.xrpl_pair else ""
+    quote_asset = (
+        config.xrpl_pair.split("-")[-1].upper() if "-" in config.xrpl_pair else ""
+    )
     if quote_asset == "XRP" and ref_mid > 0:
         amount_in_quote = config.total_amount_quote / ref_mid
         out.append(
@@ -375,8 +424,12 @@ def _utc(ms: int) -> str:
         bids = (book or {}).get("bids") or []
         asks = (book or {}).get("asks") or []
         if bids and asks:
-            best_bid = float(bids[0][0] if isinstance(bids[0], (list, tuple)) else bids[0]["price"])
-            best_ask = float(asks[0][0] if isinstance(asks[0], (list, tuple)) else asks[0]["price"])
+            best_bid = float(
+                bids[0][0] if isinstance(bids[0], (list, tuple)) else bids[0]["price"]
+            )
+            best_ask = float(
+                asks[0][0] if isinstance(asks[0], (list, tuple)) else asks[0]["price"]
+            )
             mid = (best_bid + best_ask) / 2
             out.append(f"best_bid: {best_bid:.6f}")
             out.append(f"best_ask: {best_ask:.6f}")
@@ -391,6 +444,8 @@ def _utc(ms: int) -> str:
             out.append("status: EMPTY OR UNAVAILABLE — do not quote blind")
     except Exception as exc:
         out.append(f"status: ERROR — {exc}")
-        out.append("action: treat as a hard stop; do not place offers without live book state")
+        out.append(
+            "action: treat as a hard stop; do not place offers without live book state"
+        )
 
     return "\n".join(out)
diff --git a/condor/acp/__init__.py b/condor/acp/__init__.py
index 65c3804a..ffe6962d 100644
--- a/condor/acp/__init__.py
+++ b/condor/acp/__init__.py
@@ -1,14 +1,14 @@
 from .client import (
-    ACPClient,
     ACP_COMMANDS,
-    resolve_acp,
+    ACPClient,
+    ACPEvent,
+    Heartbeat,
     PermissionCallback,
+    PromptDone,
     TextChunk,
     ThoughtChunk,
     ToolCallEvent,
     ToolCallUpdate,
-    PromptDone,
-    Heartbeat,
-    ACPEvent,
+    resolve_acp,
 )
 from .pydantic_ai_client import PydanticAIClient, is_pydantic_ai_model
diff --git a/condor/acp/jsonrpc.py b/condor/acp/jsonrpc.py
index 5e9e0e5a..c1563553 100644
--- a/condor/acp/jsonrpc.py
+++ b/condor/acp/jsonrpc.py
@@ -23,7 +23,9 @@ def __init__(self, code: int, message: str, data: Any = None):
             detail = str(data.get("details") or data.get("message") or "") or str(data)
         elif data:
             detail = str(data)
-        super().__init__(f"[{code}] {message}" + (f": {detail[:300]}" if detail else ""))
+        super().__init__(
+            f"[{code}] {message}" + (f": {detail[:300]}" if detail else "")
+        )
 
 
 # Standard JSON-RPC 2.0 error codes
@@ -91,7 +93,9 @@ async def handle_line(self, line: str, writer: asyncio.StreamWriter) -> None:
                 if "error" in data:
                     err = data["error"]
                     future.set_exception(
-                        JSONRPCError(err.get("code", -1), err.get("message", ""), err.get("data"))
+                        JSONRPCError(
+                            err.get("code", -1), err.get("message", ""), err.get("data")
+                        )
                     )
                 else:
                     future.set_result(data.get("result"))
@@ -108,7 +112,10 @@ async def handle_line(self, line: str, writer: asyncio.StreamWriter) -> None:
             if msg_id is not None:
                 resp = {
                     "jsonrpc": "2.0",
-                    "error": {"code": METHOD_NOT_FOUND, "message": f"Method not found: {method}"},
+                    "error": {
+                        "code": METHOD_NOT_FOUND,
+                        "message": f"Method not found: {method}",
+                    },
                     "id": msg_id,
                 }
                 writer.write((json.dumps(resp) + "\n").encode())
@@ -116,7 +123,11 @@ async def handle_line(self, line: str, writer: asyncio.StreamWriter) -> None:
             return
 
         try:
-            result = handler(**params) if not asyncio.iscoroutinefunction(handler) else await handler(**params)
+            result = (
+                handler(**params)
+                if not asyncio.iscoroutinefunction(handler)
+                else await handler(**params)
+            )
         except Exception as e:
             log.exception("Handler error for %s", method)
             if msg_id is not None:
diff --git a/condor/backtest_store.py b/condor/backtest_store.py
index 77174a03..8aa5cc65 100644
--- a/condor/backtest_store.py
+++ b/condor/backtest_store.py
@@ -3,6 +3,7 @@
 Each backtest is stored as an individual JSON file under data/backtests/.
 A lightweight index (_index.json) tracks task_id -> server mapping for fast listing.
 """
+
 from __future__ import annotations
 
 import json
@@ -23,7 +24,9 @@ class BacktestStore:
     def __init__(self, data_dir: Path = _DATA_DIR) -> None:
         self._dir = data_dir
         self._index_path = data_dir / "_index.json"
-        self._index: dict[str, dict[str, str]] = {}  # task_id -> {server, ...light meta}
+        self._index: dict[str, dict[str, str]] = (
+            {}
+        )  # task_id -> {server, ...light meta}
         self._dir.mkdir(parents=True, exist_ok=True)
         self._load_index()
         self._migrate_legacy()
@@ -111,7 +114,11 @@ def _rebuild_index(self) -> None:
                 task_id = path.stem
                 self._index[task_id] = {
                     "server": data.get("server", ""),
-                    "config": data.get("config", {}).get("id", "") if isinstance(data.get("config"), dict) else "",
+                    "config": (
+                        data.get("config", {}).get("id", "")
+                        if isinstance(data.get("config"), dict)
+                        else ""
+                    ),
                 }
             except Exception:
                 logger.warning("Skipping corrupt backtest file %s", path)
@@ -126,13 +133,19 @@ def _migrate_legacy(self) -> None:
             if not isinstance(legacy_data, dict) or not legacy_data:
                 _LEGACY_FILE.unlink()
                 return
-            logger.info("Migrating %d backtest results from legacy store", len(legacy_data))
+            logger.info(
+                "Migrating %d backtest results from legacy store", len(legacy_data)
+            )
             for task_id, entry in legacy_data.items():
                 server = entry.pop("server", "")
                 self._write_file(task_id, {"server": server, **entry})
                 self._index[task_id] = {
                     "server": server,
-                    "config": entry.get("config", {}).get("id", "") if isinstance(entry.get("config"), dict) else "",
+                    "config": (
+                        entry.get("config", {}).get("id", "")
+                        if isinstance(entry.get("config"), dict)
+                        else ""
+                    ),
                 }
             self._persist_index()
             # Remove legacy file after successful migration
diff --git a/condor/cache.py b/condor/cache.py
index ce1262e6..783a0cfa 100644
--- a/condor/cache.py
+++ b/condor/cache.py
@@ -125,9 +125,7 @@ def evict_expired(
         del cache[k]
 
     if stale_keys:
-        logger.debug(
-            "Evicted %d stale entries from '%s'", len(stale_keys), namespace
-        )
+        logger.debug("Evicted %d stale entries from '%s'", len(stale_keys), namespace)
     return len(stale_keys)
 
 
diff --git a/condor/fetchers/__init__.py b/condor/fetchers/__init__.py
index defd2589..ad80054a 100644
--- a/condor/fetchers/__init__.py
+++ b/condor/fetchers/__init__.py
@@ -34,39 +34,39 @@
     façade consumer; they are not the package's public surface.
 """
 
-from condor.fetchers.portfolio import fetch_portfolio
-from condor.fetchers.positions import fetch_positions
-from condor.fetchers.orders import fetch_active_orders
-from condor.fetchers.trading_rules import fetch_trading_rules
+from condor.fetchers.bots import fetch_bot_runs, fetch_bots_status
 from condor.fetchers.connectors import (
-    fetch_connectors,
     fetch_available_cex_connectors,
+    fetch_connectors,
     fetch_venues,
     is_cex_connector,
 )
 from condor.fetchers.executors import (
-    fetch_executors,
-    fetch_all_executors,
     create_executor,
-    stop_executor,
     describe_executor_error,
+    extract_executors_list,
+    fetch_all_executors,
+    fetch_executors,
     get_executor_detail,
-    get_executor_type,
+    get_executor_fees,
     get_executor_pnl,
+    get_executor_type,
     get_executor_volume,
-    get_executor_fees,
-    extract_executors_list,
+    stop_executor,
 )
-from condor.fetchers.bots import fetch_bots_status, fetch_bot_runs
 from condor.fetchers.market_data import (
-    fetch_current_price,
-    fetch_candles,
     fetch_candle_connectors,
+    fetch_candles,
+    fetch_current_price,
     fetch_rates,
     fetch_ticker_pool,
     fetch_tickers,
 )
+from condor.fetchers.orders import fetch_active_orders
+from condor.fetchers.portfolio import fetch_portfolio
+from condor.fetchers.positions import fetch_positions
 from condor.fetchers.server_status import fetch_server_status
+from condor.fetchers.trading_rules import fetch_trading_rules
 
 __all__ = [
     "fetch_portfolio",
diff --git a/condor/fetchers/connectors.py b/condor/fetchers/connectors.py
index d15db9f5..bbba72af 100644
--- a/condor/fetchers/connectors.py
+++ b/condor/fetchers/connectors.py
@@ -8,7 +8,13 @@
 logger = logging.getLogger(__name__)
 
 _DEX_PREFIXES = (
-    "solana", "ethereum", "polygon", "arbitrum", "base", "optimism", "avalanche",
+    "solana",
+    "ethereum",
+    "polygon",
+    "arbitrum",
+    "base",
+    "optimism",
+    "avalanche",
 )
 
 
diff --git a/condor/fetchers/executors.py b/condor/fetchers/executors.py
index 3142ea35..e47422a1 100644
--- a/condor/fetchers/executors.py
+++ b/condor/fetchers/executors.py
@@ -47,7 +47,12 @@ def get_executor_type(executor: Dict[str, Any]) -> str:
     for source in (config, executor):
         ex_type = source.get("type", "") or source.get("executor_type", "")
         if isinstance(ex_type, str) and ex_type:
-            label = ex_type.lower().replace("_executor", "").replace("executor", "").strip("_")
+            label = (
+                ex_type.lower()
+                .replace("_executor", "")
+                .replace("executor", "")
+                .strip("_")
+            )
             if label:
                 return label
     if "start_price" in config and "end_price" in config:
@@ -86,8 +91,13 @@ def normalize_executor_side(raw: Any) -> str:
 def get_executor_pnl(executor: Dict[str, Any]) -> float:
     """Extract PnL from an executor response."""
     for key in (
-        "net_pnl_quote", "pnl_quote", "unrealized_pnl_quote",
-        "realized_pnl_quote", "net_pnl", "pnl", "close_pnl",
+        "net_pnl_quote",
+        "pnl_quote",
+        "unrealized_pnl_quote",
+        "realized_pnl_quote",
+        "net_pnl",
+        "pnl",
+        "close_pnl",
     ):
         val = executor.get(key)
         if val is not None and val != 0:
diff --git a/condor/fetchers/trading_rules.py b/condor/fetchers/trading_rules.py
index 809bdb9d..c10b26af 100644
--- a/condor/fetchers/trading_rules.py
+++ b/condor/fetchers/trading_rules.py
@@ -43,11 +43,14 @@ async def fetch_trading_rules(
         if "404" in error_str or "401" in error_str or "not found" in error_str.lower():
             logger.debug(
                 "Connector '%s' not available for trading rules: %s",
-                connector_name, e,
+                connector_name,
+                e,
             )
         else:
             logger.error(
                 "Error fetching trading rules for %s: %s",
-                connector_name, e, exc_info=True,
+                connector_name,
+                e,
+                exc_info=True,
             )
         return {}
diff --git a/condor/persistence.py b/condor/persistence.py
index bf023c21..f7db4e1e 100644
--- a/condor/persistence.py
+++ b/condor/persistence.py
@@ -124,9 +124,7 @@ def _load_singlefile(self) -> None:
             self.conversations = data.get("conversations", {})
             self.user_data = data.get("user_data", {})
             self.chat_data = data.get("chat_data", {})
-            self.bot_data = data.get(
-                "bot_data", self.context_types.bot_data()
-            )
+            self.bot_data = data.get("bot_data", self.context_types.bot_data())
             self.callback_data = data.get("callback_data", None)
         else:
             # Both files missing or corrupt – start fresh
diff --git a/condor/preferences.py b/condor/preferences.py
index c9c2acbe..73ac5b9c 100644
--- a/condor/preferences.py
+++ b/condor/preferences.py
@@ -1220,7 +1220,8 @@ def remove_custom_provider(user_data: Dict, name: str) -> bool:
 def unique_provider_name(user_data: Dict, suggested: str) -> str:
     """Return ``suggested`` (sanitized), suffixed with -2, -3, ... if taken."""
     existing = {
-        sanitize_provider_name(p.get("name", "")) for p in get_custom_providers(user_data)
+        sanitize_provider_name(p.get("name", ""))
+        for p in get_custom_providers(user_data)
     }
     base = sanitize_provider_name(suggested)
     if base not in existing:
diff --git a/condor/web/routes/archived.py b/condor/web/routes/archived.py
index d1df8566..5264a59f 100644
--- a/condor/web/routes/archived.py
+++ b/condor/web/routes/archived.py
@@ -7,7 +7,6 @@
 
 from fastapi import APIRouter, Depends, HTTPException, Query
 
-from config_manager import get_config_manager
 from condor.fetchers.executors import normalize_executor_side
 from condor.web.auth import get_current_user
 from condor.web.models import (
@@ -18,6 +17,7 @@
     PnlPoint,
     WebUser,
 )
+from config_manager import get_config_manager
 
 logger = logging.getLogger(__name__)
 
@@ -66,6 +66,7 @@ def _parse_json_field(val: Any) -> dict:
         return val
     if isinstance(val, str) and val.strip().startswith("{"):
         import json
+
         try:
             return json.loads(val)
         except Exception:
@@ -105,10 +106,7 @@ def _normalize_executors(raw: list[dict]) -> list[NormalizedExecutor]:
         )
 
         # Resolve trading pair
-        trading_pair = str(
-            ex.get("trading_pair", "")
-            or config.get("trading_pair", "")
-        )
+        trading_pair = str(ex.get("trading_pair", "") or config.get("trading_pair", ""))
 
         # Resolve prices
         entry_price = float(
@@ -129,26 +127,32 @@ def _normalize_executors(raw: list[dict]) -> list[NormalizedExecutor]:
         volume = float(ex.get("filled_amount_quote", 0) or ex.get("volume", 0) or 0)
         net_pnl_pct = float(ex.get("net_pnl_pct", 0) or 0)
 
-        result.append(NormalizedExecutor(
-            id=str(ex.get("id", "") or ex.get("executor_id", "")),
-            type=str(ex.get("type", "") or ex.get("executor_type", "") or config.get("type", "position")),
-            connector=connector,
-            trading_pair=trading_pair,
-            side=normalize_executor_side(side_raw),
-            status=str(ex.get("status", "") or "closed"),
-            close_type=str(ex.get("close_type", "") or ""),
-            pnl=pnl,
-            volume=volume,
-            timestamp=_to_epoch_seconds(ex.get("timestamp")),
-            close_timestamp=_to_epoch_seconds(ex.get("close_timestamp")),
-            entry_price=entry_price,
-            current_price=close_price,
-            cum_fees_quote=fees,
-            net_pnl_pct=net_pnl_pct,
-            controller_id=str(ex.get("controller_id", "")),
-            custom_info=custom_info,
-            config=config,
-        ))
+        result.append(
+            NormalizedExecutor(
+                id=str(ex.get("id", "") or ex.get("executor_id", "")),
+                type=str(
+                    ex.get("type", "")
+                    or ex.get("executor_type", "")
+                    or config.get("type", "position")
+                ),
+                connector=connector,
+                trading_pair=trading_pair,
+                side=normalize_executor_side(side_raw),
+                status=str(ex.get("status", "") or "closed"),
+                close_type=str(ex.get("close_type", "") or ""),
+                pnl=pnl,
+                volume=volume,
+                timestamp=_to_epoch_seconds(ex.get("timestamp")),
+                close_timestamp=_to_epoch_seconds(ex.get("close_timestamp")),
+                entry_price=entry_price,
+                current_price=close_price,
+                cum_fees_quote=fees,
+                net_pnl_pct=net_pnl_pct,
+                controller_id=str(ex.get("controller_id", "")),
+                custom_info=custom_info,
+                config=config,
+            )
+        )
     return result
 
 
@@ -237,7 +241,9 @@ async def _fetch_and_cache_performance(
     _executors_cache[cache_key] = executors
 
     # Derive primary connector and trading pair
-    primary_connector, primary_trading_pair = _derive_primary_pair(executors, exchanges, trading_pairs)
+    primary_connector, primary_trading_pair = _derive_primary_pair(
+        executors, exchanges, trading_pairs
+    )
 
     # Calculate PnL from trades
     from condor.archived_pnl import calculate_pnl_from_trades
@@ -342,11 +348,15 @@ async def list_archived_bots(name: str, user: WebUser = Depends(get_current_user
     return {"bots": bots}
 
 
-@router.get("/servers/{name}/archived/performance", response_model=ArchivedBotPerformance)
+@router.get(
+    "/servers/{name}/archived/performance", response_model=ArchivedBotPerformance
+)
 async def get_archived_performance(
     name: str,
     db_path: str = Query(..., description="Database path"),
-    include_executors: bool = Query(False, description="Include full executor list in response"),
+    include_executors: bool = Query(
+        False, description="Include full executor list in response"
+    ),
     user: WebUser = Depends(get_current_user),
 ):
     cm = get_config_manager()
diff --git a/condor/web/routes/executors.py b/condor/web/routes/executors.py
index 9038f461..b81d9d34 100644
--- a/condor/web/routes/executors.py
+++ b/condor/web/routes/executors.py
@@ -8,7 +8,13 @@
 logger = logging.getLogger(__name__)
 
 
-from config_manager import get_config_manager
+from condor.fetchers.executors import (
+    EXECUTORS_POLL_MAX,
+    MAX_EXECUTORS_FETCH,
+    describe_executor_error,
+)
+from condor.fetchers.executors import extract_executors_list as _extract_executors_list
+from condor.fetchers.executors import fetch_all_executors, summarize_executors_by_quote
 from condor.web.auth import get_current_user
 from condor.web.models import (
     CreateExecutorRequest,
@@ -16,14 +22,7 @@
     ExecutorPeriodSummary,
     WebUser,
 )
-from condor.fetchers.executors import (
-    describe_executor_error,
-    fetch_all_executors,
-    extract_executors_list as _extract_executors_list,
-    summarize_executors_by_quote,
-    EXECUTORS_POLL_MAX,
-    MAX_EXECUTORS_FETCH,
-)
+from config_manager import get_config_manager
 
 router = APIRouter(tags=["executors"])
 
@@ -71,7 +70,12 @@ async def list_executors(
     trading_pair: str = Query(default="", description="Filter by trading pair"),
     status: str = Query(default="", description="Filter by status"),
     controller_id: str = Query(default="", description="Filter by controller id"),
-    limit: int = Query(default=0, ge=0, le=MAX_EXECUTORS_FETCH, description="Max executors to return (0 = default SDS cache)"),
+    limit: int = Query(
+        default=0,
+        ge=0,
+        le=MAX_EXECUTORS_FETCH,
+        description="Max executors to return (0 = default SDS cache)",
+    ),
     user: WebUser = Depends(get_current_user),
 ):
     cm = get_config_manager()
@@ -105,7 +109,9 @@ async def list_executors(
             raise _executor_error("Failed to fetch executors", e)
     else:
         try:
-            result = await get_server_data_service().get_or_fetch(name, ServerDataType.EXECUTORS)
+            result = await get_server_data_service().get_or_fetch(
+                name, ServerDataType.EXECUTORS
+            )
         except Exception as e:
             logger.exception("Failed to fetch executors for server %s", name)
             raise _executor_error("Failed to fetch executors", e)
@@ -399,7 +405,10 @@ async def get_positions_held(
     else:
         positions = []
 
-    return {"positions": positions, "summary": result if isinstance(result, dict) else {}}
+    return {
+        "positions": positions,
+        "summary": result if isinstance(result, dict) else {},
+    }
 
 
 @router.delete("/servers/{name}/executors/positions/{connector}/{pair}")
diff --git a/condor/web/routes/positions.py b/condor/web/routes/positions.py
index fa4abb96..c3845044 100644
--- a/condor/web/routes/positions.py
+++ b/condor/web/routes/positions.py
@@ -5,9 +5,9 @@
 
 from fastapi import APIRouter, Depends, HTTPException
 
-from config_manager import get_config_manager
 from condor.web.auth import get_current_user
 from condor.web.models import WebUser
+from config_manager import get_config_manager
 
 logger = logging.getLogger(__name__)
 
@@ -30,7 +30,9 @@ def _normalize_position(pos: dict, source: str, source_name: str) -> dict:
         "entry_price": entry_price,
         "notional_value": notional_value,
         "current_price": pos.get("current_price") or 0,
-        "unrealized_pnl": pos.get("unrealized_pnl_quote") or pos.get("unrealized_pnl") or 0,
+        "unrealized_pnl": pos.get("unrealized_pnl_quote")
+        or pos.get("unrealized_pnl")
+        or 0,
         "leverage": pos.get("leverage") or 1,
         "controller_id": pos.get("controller_id") or "",
         "realized_pnl": pos.get("realized_pnl_quote") or 0,
@@ -72,7 +74,9 @@ async def fetch_executor_positions():
 
     async def fetch_bot_positions():
         try:
-            result = await get_server_data_service().get_or_fetch(name, ServerDataType.BOTS_STATUS)
+            result = await get_server_data_service().get_or_fetch(
+                name, ServerDataType.BOTS_STATUS
+            )
             if result is None:
                 return []
 
@@ -81,7 +85,11 @@ async def fetch_bot_positions():
             if isinstance(result, dict):
                 data = result.get("data", {})
                 if isinstance(data, dict):
-                    bots_list = [{"bot_name": k, **v} for k, v in data.items() if isinstance(v, dict)]
+                    bots_list = [
+                        {"bot_name": k, **v}
+                        for k, v in data.items()
+                        if isinstance(v, dict)
+                    ]
                 elif isinstance(data, list):
                     bots_list = [b for b in data if isinstance(b, dict)]
             elif isinstance(result, list):
@@ -121,8 +129,7 @@ async def fetch_bot_positions():
     ]
 
     bot_positions = [
-        _normalize_position(pos, "bot", source_name)
-        for pos, source_name in bot_raw
+        _normalize_position(pos, "bot", source_name) for pos, source_name in bot_raw
     ]
 
     # Enrich positions missing current_price (the positions_summary endpoint doesn't provide it)
diff --git a/condor/web/routes/reports.py b/condor/web/routes/reports.py
index ae62b2ab..af3ed597 100644
--- a/condor/web/routes/reports.py
+++ b/condor/web/routes/reports.py
@@ -13,7 +13,7 @@
     list_reports_grouped,
 )
 from condor.web.auth import get_current_user
-from condor.web.models import ReportSummary, ReportsListResponse, WebUser
+from condor.web.models import ReportsListResponse, ReportSummary, WebUser
 
 router = APIRouter(prefix="/reports", tags=["reports"])
 
diff --git a/condor/web/routes/settings.py b/condor/web/routes/settings.py
index 63b0cdf2..b7408a5f 100644
--- a/condor/web/routes/settings.py
+++ b/condor/web/routes/settings.py
@@ -5,7 +5,6 @@
 
 from fastapi import APIRouter, Depends, HTTPException, Query
 
-from config_manager import ServerPermission, get_config_manager
 from condor.web.auth import get_current_user
 from condor.web.models import (
     AddCredentialRequest,
@@ -17,6 +16,7 @@
     UpdateServerRequest,
     WebUser,
 )
+from config_manager import ServerPermission, get_config_manager
 
 logger = logging.getLogger(__name__)
 
@@ -48,6 +48,7 @@ async def list_settings_servers(user: WebUser = Depends(get_current_user)):
     accessible = cm.list_accessible_servers(user.id)
 
     from condor.server_data_service import ServerDataType, get_server_data_service
+
     sds = get_server_data_service()
 
     # Fetch status for all servers concurrently (uses SDS cache, instant if warm)
@@ -61,13 +62,15 @@ async def _get_status(name: str) -> dict:
     for (name, cfg), status in zip(accessible.items(), statuses):
         perm = cm.get_server_permission(user.id, name)
         online = status.get("status") == "online"
-        results.append(ServerInfo(
-            name=name,
-            host=cfg.get("host", ""),
-            port=cfg.get("port", 0),
-            online=online,
-            permission=perm.value if perm else "trader",
-        ))
+        results.append(
+            ServerInfo(
+                name=name,
+                host=cfg.get("host", ""),
+                port=cfg.get("port", 0),
+                online=online,
+                permission=perm.value if perm else "trader",
+            )
+        )
 
     return sorted(results, key=lambda s: (not s.online, s.name))
 
@@ -206,10 +209,12 @@ async def gateway_start(
         raise HTTPException(status_code=403, detail="No access")
     client = await _get_client(cm, server)
     try:
-        result = await client.gateway.start({
-            "image": req.image,
-            "port": req.port,
-        })
+        result = await client.gateway.start(
+            {
+                "image": req.image,
+                "port": req.port,
+            }
+        )
         return {"started": True, "result": result}
     except Exception as e:
         raise HTTPException(status_code=500, detail=str(e))
@@ -271,12 +276,16 @@ async def get_voice_settings(user: WebUser = Depends(get_current_user)):
     """Get voice/transcription preferences for the current user."""
     cm = get_config_manager()
     prefs = cm.get_user_preferences(user.id)
-    voice = prefs.get("voice", {
-        "whisper_model": "small",
-        "language": None,
-        "auto_send": True,
-    })
-    from condor.preferences import WHISPER_MODELS, VOICE_LANGUAGES
+    voice = prefs.get(
+        "voice",
+        {
+            "whisper_model": "small",
+            "language": None,
+            "auto_send": True,
+        },
+    )
+    from condor.preferences import VOICE_LANGUAGES, WHISPER_MODELS
+
     return {
         "voice": voice,
         "available_models": WHISPER_MODELS,
@@ -292,11 +301,14 @@ async def update_voice_settings(
     """Update voice/transcription preferences."""
     cm = get_config_manager()
     prefs = cm.get_user_preferences(user.id)
-    voice = prefs.get("voice", {
-        "whisper_model": "small",
-        "language": None,
-        "auto_send": True,
-    })
+    voice = prefs.get(
+        "voice",
+        {
+            "whisper_model": "small",
+            "language": None,
+            "auto_send": True,
+        },
+    )
     allowed_keys = {"whisper_model", "language", "auto_send"}
     for key in allowed_keys:
         if key in body:
@@ -304,6 +316,7 @@ async def update_voice_settings(
 
     # Validate whisper_model
     from condor.preferences import WHISPER_MODELS
+
     if voice.get("whisper_model") not in WHISPER_MODELS:
         voice["whisper_model"] = "base"
 
@@ -336,10 +349,16 @@ async def list_credentials(
                 if isinstance(item, str):
                     credentials.append({"connector_name": item, "connector_type": ""})
                 elif isinstance(item, dict):
-                    credentials.append({
-                        "connector_name": item.get("connector_name", item.get("name", "")),
-                        "connector_type": item.get("connector_type", item.get("type", "")),
-                    })
+                    credentials.append(
+                        {
+                            "connector_name": item.get(
+                                "connector_name", item.get("name", "")
+                            ),
+                            "connector_type": item.get(
+                                "connector_type", item.get("type", "")
+                            ),
+                        }
+                    )
         return {"credentials": credentials}
     except Exception as e:
         raise HTTPException(status_code=500, detail=str(e))
@@ -360,16 +379,28 @@ async def list_connectors(
     sds = get_server_data_service()
     raw = await sds.get_or_fetch(server, ServerDataType.ALL_CONNECTORS)
     if raw is None:
-        raise HTTPException(status_code=502, detail="Cannot fetch connectors from server")
+        raise HTTPException(
+            status_code=502, detail="Cannot fetch connectors from server"
+        )
 
     # API returns plain strings — filter out testnet/gateway connectors
-    names = [c for c in raw if isinstance(c, str) and "testnet" not in c.lower() and "sandbox" not in c.lower() and "/" not in c]
+    names = [
+        c
+        for c in raw
+        if isinstance(c, str)
+        and "testnet" not in c.lower()
+        and "sandbox" not in c.lower()
+        and "/" not in c
+    ]
     if type:
         if type.lower() == "perpetual":
             names = [c for c in names if "perpetual" in c.lower()]
         else:
             names = [c for c in names if "perpetual" not in c.lower()]
-    connectors = [{"name": c, "type": "perpetual" if "perpetual" in c.lower() else "spot"} for c in names]
+    connectors = [
+        {"name": c, "type": "perpetual" if "perpetual" in c.lower() else "spot"}
+        for c in names
+    ]
     return {"connectors": connectors}
 
 
@@ -408,6 +439,7 @@ async def add_credential(
         )
         # Invalidate configured connectors cache
         from condor.server_data_service import ServerDataType, get_server_data_service
+
         get_server_data_service().invalidate(server, ServerDataType.CONNECTORS)
         return {"added": True, "result": result}
     except Exception as e:
@@ -431,6 +463,7 @@ async def delete_credential(
         )
         # Invalidate configured connectors + portfolio caches so the removed key disappears immediately
         from condor.server_data_service import ServerDataType, get_server_data_service
+
         sds = get_server_data_service()
         sds.invalidate(server, ServerDataType.CONNECTORS)
         sds.invalidate(server, ServerDataType.PORTFOLIO)
diff --git a/condor/web/routes/transcribe.py b/condor/web/routes/transcribe.py
index 170898be..fb534719 100644
--- a/condor/web/routes/transcribe.py
+++ b/condor/web/routes/transcribe.py
@@ -2,7 +2,7 @@
 
 import logging
 
-from fastapi import APIRouter, Depends, Form, UploadFile, File, HTTPException
+from fastapi import APIRouter, Depends, File, Form, HTTPException, UploadFile
 
 from condor.web.auth import get_current_user
 from condor.web.models import WebUser
@@ -39,6 +39,7 @@ async def transcribe_audio(
     if effective_lang is None or effective_model is None:
         try:
             from config_manager import get_config_manager
+
             cm = get_config_manager()
             voice_prefs = cm.get_user_preferences(user.id).get("voice", {})
             if effective_lang is None:
diff --git a/handlers/admin/__init__.py b/handlers/admin/__init__.py
index dacee375..c70e57ca 100644
--- a/handlers/admin/__init__.py
+++ b/handlers/admin/__init__.py
@@ -9,11 +9,7 @@
 from telegram import InlineKeyboardButton, InlineKeyboardMarkup, Update
 from telegram.ext import ContextTypes
 
-from config_manager import (
-    ServerPermission,
-    UserRole,
-    get_config_manager,
-)
+from config_manager import ServerPermission, UserRole, get_config_manager
 from utils.auth import admin_required
 from utils.telegram_formatters import escape_markdown_v2
 
diff --git a/handlers/admin/update.py b/handlers/admin/update.py
index 679c5885..5668c8d6 100644
--- a/handlers/admin/update.py
+++ b/handlers/admin/update.py
@@ -52,8 +52,7 @@ async def _check_and_show(message_or_query, context: ContextTypes.DEFAULT_TYPE)
 
     if condor_info["error"]:
         sections.append(
-            f"*Condor*\n"
-            f"Error: `{escape_markdown_v2(condor_info['error'])}`"
+            f"*Condor*\n" f"Error: `{escape_markdown_v2(condor_info['error'])}`"
         )
     else:
         local = escape_markdown_v2(condor_info["local_commit"])
@@ -114,7 +113,9 @@ async def _check_and_show(message_or_query, context: ContextTypes.DEFAULT_TYPE)
                 hb_remote = escape_markdown_v2(hb_git["remote_commit"])
                 hb_behind = hb_git["commits_behind"]
                 hb_log_lines = hb_git["commit_log"].split("\n")[:5]
-                hb_log_display = "\n".join(escape_markdown_v2_code(l) for l in hb_log_lines)
+                hb_log_display = "\n".join(
+                    escape_markdown_v2_code(l) for l in hb_log_lines
+                )
                 if hb_behind > 5:
                     hb_log_display += f"\n_\\.\\.\\.and {hb_behind - 5} more_"
                 sections.append(
@@ -130,29 +131,51 @@ async def _check_and_show(message_or_query, context: ContextTypes.DEFAULT_TYPE)
     keyboard = []
 
     if condor_has_update and hb_has_update:
-        keyboard.append([InlineKeyboardButton("Update All", callback_data="admin:update_all")])
-        keyboard.append([
-            InlineKeyboardButton("Update Condor", callback_data="admin:update_pull"),
-            InlineKeyboardButton("Update HB API", callback_data="admin:update_hb"),
-        ])
+        keyboard.append(
+            [InlineKeyboardButton("Update All", callback_data="admin:update_all")]
+        )
+        keyboard.append(
+            [
+                InlineKeyboardButton(
+                    "Update Condor", callback_data="admin:update_pull"
+                ),
+                InlineKeyboardButton("Update HB API", callback_data="admin:update_hb"),
+            ]
+        )
     elif condor_has_update:
-        keyboard.append([InlineKeyboardButton("Update Condor & Restart", callback_data="admin:update_pull")])
+        keyboard.append(
+            [
+                InlineKeyboardButton(
+                    "Update Condor & Restart", callback_data="admin:update_pull"
+                )
+            ]
+        )
     elif hb_has_update:
-        keyboard.append([InlineKeyboardButton("Update HB API", callback_data="admin:update_hb")])
+        keyboard.append(
+            [InlineKeyboardButton("Update HB API", callback_data="admin:update_hb")]
+        )
 
-    keyboard.append([InlineKeyboardButton("Refresh", callback_data="admin:update_check")])
-    keyboard.append([InlineKeyboardButton("Force Restart", callback_data="admin:update_restart")])
+    keyboard.append(
+        [InlineKeyboardButton("Refresh", callback_data="admin:update_check")]
+    )
+    keyboard.append(
+        [InlineKeyboardButton("Force Restart", callback_data="admin:update_restart")]
+    )
     keyboard.append([InlineKeyboardButton("Back", callback_data="admin:back")])
 
     reply_markup = InlineKeyboardMarkup(keyboard)
 
     if is_callback:
         await message_or_query.edit_message_text(
-            text, parse_mode="MarkdownV2", reply_markup=reply_markup,
+            text,
+            parse_mode="MarkdownV2",
+            reply_markup=reply_markup,
         )
     else:
         await msg.edit_text(
-            text, parse_mode="MarkdownV2", reply_markup=reply_markup,
+            text,
+            parse_mode="MarkdownV2",
+            reply_markup=reply_markup,
         )
 
 
@@ -226,12 +249,18 @@ async def _fail(
     keyboard = []
     if retry_restart:
         keyboard.append(
-            [InlineKeyboardButton("Restart Anyway", callback_data="admin:update_restart")]
+            [
+                InlineKeyboardButton(
+                    "Restart Anyway", callback_data="admin:update_restart"
+                )
+            ]
         )
     keyboard.append([InlineKeyboardButton("Back", callback_data="admin:update_check")])
 
     await query.edit_message_text(
-        text, parse_mode="MarkdownV2", reply_markup=InlineKeyboardMarkup(keyboard),
+        text,
+        parse_mode="MarkdownV2",
+        reply_markup=InlineKeyboardMarkup(keyboard),
     )
 
 
@@ -263,7 +292,9 @@ async def _update_condor(query) -> bool:
     success, dep_msg = await install_dependencies()
     if not success:
         await _fail(
-            query, "Dependencies failed", dep_msg,
+            query,
+            "Dependencies failed",
+            dep_msg,
             note="Code was pulled but deps failed. Fix it manually before restarting.",
             retry_restart=True,
         )
@@ -276,7 +307,9 @@ async def _update_condor(query) -> bool:
         success, build_msg = await build_frontend()
         if not success:
             await _fail(
-                query, "Dashboard build failed", build_msg,
+                query,
+                "Dashboard build failed",
+                build_msg,
                 note=(
                     "Code and deps are updated, but the dashboard would come back "
                     "on the previous bundle."
@@ -324,7 +357,8 @@ async def _do_update_hb(query, context: ContextTypes.DEFAULT_TYPE) -> None:
         [InlineKeyboardButton("Back", callback_data="admin:update_check")],
     ]
     await query.edit_message_text(
-        text, parse_mode="MarkdownV2",
+        text,
+        parse_mode="MarkdownV2",
         reply_markup=InlineKeyboardMarkup(keyboard),
     )
 
@@ -338,7 +372,9 @@ async def _do_update_all(query, context: ContextTypes.DEFAULT_TYPE) -> None:
     await _progress(query, "Updating hummingbot-api...")
     hb_ok, hb_msg = await update_hb_api()
     if not hb_ok:
-        await _fail(query, "HB API update failed", hb_msg, note="Condor update skipped.")
+        await _fail(
+            query, "HB API update failed", hb_msg, note="Condor update skipped."
+        )
         return
 
     if await _update_condor(query):
@@ -427,6 +463,4 @@ def schedule_update_checks(application) -> None:
         first=30,  # first check 30s after startup
         name=UPDATE_CHECK_JOB,
     )
-    logger.info(
-        "Scheduled update checks every %ds", UPDATE_CHECK_INTERVAL
-    )
+    logger.info("Scheduled update checks every %ds", UPDATE_CHECK_INTERVAL)
diff --git a/handlers/agents/openrouter_models.py b/handlers/agents/openrouter_models.py
index 698ec2e8..8a7b17b5 100644
--- a/handlers/agents/openrouter_models.py
+++ b/handlers/agents/openrouter_models.py
@@ -24,8 +24,8 @@
 
 @dataclass(frozen=True)
 class OpenRouterModel:
-    slug: str            # e.g. "anthropic/claude-sonnet-4-5"
-    name: str            # human-friendly name from the API
+    slug: str  # e.g. "anthropic/claude-sonnet-4-5"
+    name: str  # human-friendly name from the API
     context_length: int  # tokens
     prompt_price: float  # USD per 1M input tokens, 0 if free
     completion_price: float
diff --git a/handlers/bots/__init__.py b/handlers/bots/__init__.py
index 3ef6e6b3..48d12484 100644
--- a/handlers/bots/__init__.py
+++ b/handlers/bots/__init__.py
@@ -108,8 +108,6 @@
     handle_pv1_wizard_connector,
     handle_pv1_wizard_pair,
     handle_pv1_wizard_spreads,
-    process_pv1_wizard_input,
-    show_new_pmm_v1_form,
     handle_save_config,
     handle_select_all,
     handle_select_connector,
@@ -128,6 +126,7 @@
     process_gs_wizard_input,
     process_instance_name_input,
     process_pmm_wizard_input,
+    process_pv1_wizard_input,
     show_cfg_edit_form,
     show_config_form,
     show_configs_by_type,
@@ -139,6 +138,7 @@
     show_deploy_menu,
     show_new_grid_strike_form,
     show_new_pmm_mister_form,
+    show_new_pmm_v1_form,
     show_type_selector,
     show_upload_config_prompt,
 )
diff --git a/handlers/bots/controller_handlers.py b/handlers/bots/controller_handlers.py
index e6d65a35..9786ebc3 100644
--- a/handlers/bots/controller_handlers.py
+++ b/handlers/bots/controller_handlers.py
@@ -29,8 +29,6 @@
 )
 from utils.telegram_formatters import escape_markdown_v2, format_error_message
 
-from .controllers import get_controller_info, get_supported_controller_types
-
 from ._shared import (
     GRID_STRIKE_DEFAULTS,
     GRID_STRIKE_FIELD_ORDER,
@@ -56,6 +54,7 @@
     init_new_controller_config,
     set_controller_config,
 )
+from .controllers import get_controller_info, get_supported_controller_types
 from .controllers.grid_strike.grid_analysis import (
     calculate_natr,
     generate_theoretical_grid,
@@ -8016,11 +8015,11 @@ async def _pmm_show_advanced(context, chat_id, message_id, config):
 # PMM V1 WIZARD
 # ============================================
 
-from .controllers.pmm_v1 import generate_id as pv1_generate_id
-from .controllers.pmm_v1 import validate_config as pv1_validate_config
-from .controllers.pmm_v1 import parse_spreads as pv1_parse_spreads
 from .controllers.pmm_v1 import FIELD_ORDER as PV1_FIELD_ORDER
 from .controllers.pmm_v1 import FIELDS as PV1_FIELDS
+from .controllers.pmm_v1 import generate_id as pv1_generate_id
+from .controllers.pmm_v1 import parse_spreads as pv1_parse_spreads
+from .controllers.pmm_v1 import validate_config as pv1_validate_config
 
 
 async def show_new_pmm_v1_form(
diff --git a/handlers/bots/menu.py b/handlers/bots/menu.py
index 3e895853..34df06a1 100644
--- a/handlers/bots/menu.py
+++ b/handlers/bots/menu.py
@@ -951,9 +951,7 @@ async def handle_confirm_stop_controller(
         keyboard = [
             [
                 InlineKeyboardButton("▶️ Restart", callback_data="bots:start_ctrl"),
-                InlineKeyboardButton(
-                    "⬅️ Back to Bot", callback_data="bots:back_to_bot"
-                ),
+                InlineKeyboardButton("⬅️ Back to Bot", callback_data="bots:back_to_bot"),
             ]
         ]
 
diff --git a/handlers/config/gateway/menu.py b/handlers/config/gateway/menu.py
index 1b5914a5..24299ac6 100644
--- a/handlers/config/gateway/menu.py
+++ b/handlers/config/gateway/menu.py
@@ -62,7 +62,8 @@ async def show_gateway_menu(query, context: ContextTypes.DEFAULT_TYPE) -> None:
                                 "🪙 Tokens", callback_data="gateway_tokens"
                             ),
                             InlineKeyboardButton(
-                                "📡 RPC Providers", callback_data="gateway_rpc_providers"
+                                "📡 RPC Providers",
+                                callback_data="gateway_rpc_providers",
                             ),
                         ],
                         [
diff --git a/handlers/config/gateway/networks.py b/handlers/config/gateway/networks.py
index 6c595ef2..6d17377d 100644
--- a/handlers/config/gateway/networks.py
+++ b/handlers/config/gateway/networks.py
@@ -6,7 +6,12 @@
 from telegram.ext import ContextTypes
 
 from ..user_preferences import get_active_server
-from ._shared import escape_markdown_v2, extract_network_id, get_default_networks, logger
+from ._shared import (
+    escape_markdown_v2,
+    extract_network_id,
+    get_default_networks,
+    logger,
+)
 
 
 async def show_networks_menu(query, context: ContextTypes.DEFAULT_TYPE) -> None:
@@ -218,10 +223,10 @@ async def show_network_details(
                 [
                     InlineKeyboardButton(
                         toggle_text,
-                        callback_data=f"gateway_network_toggle_default_{network_id}"
+                        callback_data=f"gateway_network_toggle_default_{network_id}",
                     )
                 ],
-                [InlineKeyboardButton("« Back", callback_data="gateway_networks")]
+                [InlineKeyboardButton("« Back", callback_data="gateway_networks")],
             ]
 
         reply_markup = InlineKeyboardMarkup(keyboard)
@@ -471,8 +476,7 @@ async def toggle_default_network(
 
         # Update the config
         await client.gateway.update_network_config(
-            network_id,
-            {"default_networks": default_networks}
+            network_id, {"default_networks": default_networks}
         )
 
         # Show success and refresh
diff --git a/handlers/config/gateway/pools.py b/handlers/config/gateway/pools.py
index 8f9e28e3..3069cbe1 100644
--- a/handlers/config/gateway/pools.py
+++ b/handlers/config/gateway/pools.py
@@ -57,7 +57,8 @@ async def show_pools_menu(
             else:
                 # Filter to only default networks
                 networks_to_show = [
-                    n for n in all_networks
+                    n
+                    for n in all_networks
                     if extract_network_id(n) in default_network_ids
                 ][:20]
                 showing_defaults = True
@@ -89,14 +90,14 @@ async def show_pools_menu(
                     [
                         InlineKeyboardButton(
                             f"🌐 All Networks ({len(all_networks)})",
-                            callback_data="gateway_pool_all_networks"
+                            callback_data="gateway_pool_all_networks",
                         )
                     ],
                     [
                         InlineKeyboardButton(
                             "« Back to Gateway", callback_data="config_gateway"
                         )
-                    ]
+                    ],
                 ]
             else:
                 count_escaped = escape_markdown_v2(str(len(all_networks)))
@@ -651,9 +652,7 @@ async def remove_pool(
             chat_id, preferred_server=get_active_server(context.user_data)
         )
         await client.gateway.delete_network_pool(
-            network_id=network_id,
-            address=pool_address,
-            pool_type=pool_type
+            network_id=network_id, address=pool_address, pool_type=pool_type
         )
 
         network_escaped = escape_markdown_v2(network_id)
diff --git a/handlers/config/gateway/rpc_providers.py b/handlers/config/gateway/rpc_providers.py
index f7760a6b..cf6ad62d 100644
--- a/handlers/config/gateway/rpc_providers.py
+++ b/handlers/config/gateway/rpc_providers.py
@@ -8,7 +8,6 @@
 from ..user_preferences import get_active_server
 from ._shared import escape_markdown_v2, logger
 
-
 # RPC Provider configuration
 # Maps provider name to chain and default network
 RPC_PROVIDERS = {
@@ -72,12 +71,13 @@ async def show_rpc_providers_menu(query, context: ContextTypes.DEFAULT_TYPE) ->
             chain_label = chain.capitalize()
             button_text = f"{status} {provider_info['name']} ({chain_label})"
 
-            provider_buttons.append([
-                InlineKeyboardButton(
-                    button_text,
-                    callback_data=f"gateway_rpc_{provider_key}"
-                )
-            ])
+            provider_buttons.append(
+                [
+                    InlineKeyboardButton(
+                        button_text, callback_data=f"gateway_rpc_{provider_key}"
+                    )
+                ]
+            )
 
         message_text = (
             "📡 *RPC Providers*\n\n"
@@ -88,8 +88,12 @@ async def show_rpc_providers_menu(query, context: ContextTypes.DEFAULT_TYPE) ->
         )
 
         keyboard = provider_buttons + [
-            [InlineKeyboardButton("🔗 Custom URL", callback_data="gateway_rpc_url_menu")],
-            [InlineKeyboardButton("« Back", callback_data="config_gateway")]
+            [
+                InlineKeyboardButton(
+                    "🔗 Custom URL", callback_data="gateway_rpc_url_menu"
+                )
+            ],
+            [InlineKeyboardButton("« Back", callback_data="config_gateway")],
         ]
 
         reply_markup = InlineKeyboardMarkup(keyboard)
@@ -182,7 +186,9 @@ async def show_provider_details(
         # API key status
         if has_key:
             # Mask the API key for display (show first 4 chars)
-            masked_key = current_key[:4] + "..." if len(current_key) > 4 else current_key
+            masked_key = (
+                current_key[:4] + "..." if len(current_key) > 4 else current_key
+            )
             key_status = f"🔑 API Key: `{escape_markdown_v2(masked_key)}`"
         else:
             key_status = "⬜ No API key configured"
@@ -207,40 +213,48 @@ async def show_provider_details(
 
         # API key button
         if has_key:
-            keyboard.append([
-                InlineKeyboardButton(
-                    "🔑 Update API Key",
-                    callback_data=f"gateway_rpc_setkey_{provider_key}"
-                )
-            ])
+            keyboard.append(
+                [
+                    InlineKeyboardButton(
+                        "🔑 Update API Key",
+                        callback_data=f"gateway_rpc_setkey_{provider_key}",
+                    )
+                ]
+            )
         else:
-            keyboard.append([
-                InlineKeyboardButton(
-                    "➕ Add API Key",
-                    callback_data=f"gateway_rpc_setkey_{provider_key}"
-                )
-            ])
+            keyboard.append(
+                [
+                    InlineKeyboardButton(
+                        "➕ Add API Key",
+                        callback_data=f"gateway_rpc_setkey_{provider_key}",
+                    )
+                ]
+            )
 
         # Activate/Deactivate button (only if has key)
         if has_key:
             if is_active:
-                keyboard.append([
-                    InlineKeyboardButton(
-                        "⬜ Deactivate (use custom URL)",
-                        callback_data=f"gateway_rpc_deactivate_{provider_key}"
-                    )
-                ])
+                keyboard.append(
+                    [
+                        InlineKeyboardButton(
+                            "⬜ Deactivate (use custom URL)",
+                            callback_data=f"gateway_rpc_deactivate_{provider_key}",
+                        )
+                    ]
+                )
             else:
-                keyboard.append([
-                    InlineKeyboardButton(
-                        "✅ Activate as RPC Provider",
-                        callback_data=f"gateway_rpc_activate_{provider_key}"
-                    )
-                ])
+                keyboard.append(
+                    [
+                        InlineKeyboardButton(
+                            "✅ Activate as RPC Provider",
+                            callback_data=f"gateway_rpc_activate_{provider_key}",
+                        )
+                    ]
+                )
 
-        keyboard.append([
-            InlineKeyboardButton("« Back", callback_data="gateway_rpc_providers")
-        ])
+        keyboard.append(
+            [InlineKeyboardButton("« Back", callback_data="gateway_rpc_providers")]
+        )
 
         reply_markup = InlineKeyboardMarkup(keyboard)
 
@@ -251,7 +265,9 @@ async def show_provider_details(
     except Exception as e:
         logger.error(f"Error showing provider details: {e}", exc_info=True)
         error_text = f"❌ Error: {escape_markdown_v2(str(e))}"
-        keyboard = [[InlineKeyboardButton("« Back", callback_data="gateway_rpc_providers")]]
+        keyboard = [
+            [InlineKeyboardButton("« Back", callback_data="gateway_rpc_providers")]
+        ]
         reply_markup = InlineKeyboardMarkup(keyboard)
         await query.message.edit_text(
             error_text, parse_mode="MarkdownV2", reply_markup=reply_markup
@@ -324,21 +340,24 @@ async def _handle_api_key_input(
     try:
         logger.info(f"Processing API key input for provider: {provider_key}")
 
-        api_key = update.message.text.strip() if update.message and update.message.text else ""
+        api_key = (
+            update.message.text.strip()
+            if update.message and update.message.text
+            else ""
+        )
         provider_info = RPC_PROVIDERS.get(provider_key)
 
         if not provider_info:
             logger.error(f"Unknown provider: {provider_key}")
             await update.get_bot().send_message(
                 chat_id=update.effective_chat.id,
-                text=f"❌ Unknown provider: {provider_key}"
+                text=f"❌ Unknown provider: {provider_key}",
             )
             return
 
         if not api_key:
             await update.get_bot().send_message(
-                chat_id=update.effective_chat.id,
-                text="❌ API key cannot be empty"
+                chat_id=update.effective_chat.id, text="❌ API key cannot be empty"
             )
             return
 
@@ -348,7 +367,7 @@ async def _handle_api_key_input(
                 await update.get_bot().edit_message_text(
                     chat_id=chat_id,
                     message_id=message_id,
-                    text=f"💾 Saving {provider_info['name']} API key..."
+                    text=f"💾 Saving {provider_info['name']} API key...",
                 )
             except Exception as edit_err:
                 logger.debug(f"Could not edit message: {edit_err}")
@@ -359,7 +378,7 @@ async def _handle_api_key_input(
         logger.info(f"Getting client for chat {update.effective_chat.id}")
         client = await get_config_manager().get_client_for_chat(
             update.effective_chat.id,
-            preferred_server=get_active_server(context.user_data)
+            preferred_server=get_active_server(context.user_data),
         )
 
         # Step 1: Update API key
@@ -371,8 +390,7 @@ async def _handle_api_key_input(
         network_id = provider_info["default_network"]
         logger.info(f"Setting rpc_provider to {provider_key} for {network_id}")
         config_result = await client.gateway.update_network_config(
-            network_id,
-            {"rpc_provider": provider_key}
+            network_id, {"rpc_provider": provider_key}
         )
         logger.info(f"Network config update result: {config_result}")
 
@@ -385,8 +403,16 @@ async def _handle_api_key_input(
         )
 
         keyboard = [
-            [InlineKeyboardButton("🔄 Restart Gateway", callback_data="gateway_restart")],
-            [InlineKeyboardButton("« Back", callback_data=f"gateway_rpc_{provider_key}")]
+            [
+                InlineKeyboardButton(
+                    "🔄 Restart Gateway", callback_data="gateway_restart"
+                )
+            ],
+            [
+                InlineKeyboardButton(
+                    "« Back", callback_data=f"gateway_rpc_{provider_key}"
+                )
+            ],
         ]
         reply_markup = InlineKeyboardMarkup(keyboard)
 
@@ -397,7 +423,7 @@ async def _handle_api_key_input(
                     message_id=message_id,
                     text=success_text,
                     parse_mode="MarkdownV2",
-                    reply_markup=reply_markup
+                    reply_markup=reply_markup,
                 )
             except Exception as edit_err:
                 logger.warning(f"Could not edit message, sending new: {edit_err}")
@@ -405,14 +431,14 @@ async def _handle_api_key_input(
                     chat_id=update.effective_chat.id,
                     text=success_text,
                     parse_mode="MarkdownV2",
-                    reply_markup=reply_markup
+                    reply_markup=reply_markup,
                 )
         else:
             await update.get_bot().send_message(
                 chat_id=update.effective_chat.id,
                 text=success_text,
                 parse_mode="MarkdownV2",
-                reply_markup=reply_markup
+                reply_markup=reply_markup,
             )
 
         logger.info(f"Successfully configured {provider_key}")
@@ -422,7 +448,7 @@ async def _handle_api_key_input(
         try:
             await update.get_bot().send_message(
                 chat_id=update.effective_chat.id,
-                text=f"❌ Error saving API key: {str(e)}"
+                text=f"❌ Error saving API key: {str(e)}",
             )
         except Exception as send_err:
             logger.error(f"Could not send error message: {send_err}")
@@ -440,14 +466,17 @@ async def _handle_url_input(
     try:
         # Extract network_id from input_type (format: "url_{network_id}")
         network_id = input_type.replace("url_", "")
-        node_url = update.message.text.strip() if update.message and update.message.text else ""
+        node_url = (
+            update.message.text.strip()
+            if update.message and update.message.text
+            else ""
+        )
 
         logger.info(f"Processing URL input for network: {network_id}")
 
         if not node_url:
             await update.get_bot().send_message(
-                chat_id=update.effective_chat.id,
-                text="❌ URL cannot be empty"
+                chat_id=update.effective_chat.id, text="❌ URL cannot be empty"
             )
             return
 
@@ -455,7 +484,7 @@ async def _handle_url_input(
         if not node_url.startswith(("http://", "https://")):
             await update.get_bot().send_message(
                 chat_id=update.effective_chat.id,
-                text="❌ URL must start with http:// or https://"
+                text="❌ URL must start with http:// or https://",
             )
             return
 
@@ -465,7 +494,7 @@ async def _handle_url_input(
                 await update.get_bot().edit_message_text(
                     chat_id=chat_id,
                     message_id=message_id,
-                    text=f"💾 Saving node URL for {network_id}..."
+                    text=f"💾 Saving node URL for {network_id}...",
                 )
             except Exception as edit_err:
                 logger.debug(f"Could not edit message: {edit_err}")
@@ -475,7 +504,7 @@ async def _handle_url_input(
 
         client = await get_config_manager().get_client_for_chat(
             update.effective_chat.id,
-            preferred_server=get_active_server(context.user_data)
+            preferred_server=get_active_server(context.user_data),
         )
 
         # Get current rpc_provider before updating
@@ -488,8 +517,7 @@ async def _handle_url_input(
         # Update only node_url (not rpc_provider yet)
         logger.info(f"Updating node_url for {network_id}")
         result = await client.gateway.update_network_config(
-            network_id,
-            {"node_url": node_url}
+            network_id, {"node_url": node_url}
         )
         logger.info(f"Network config update result: {result}")
 
@@ -504,14 +532,18 @@ async def _handle_url_input(
                 f"_Do you want to use the new nodeURL for this network?_"
             )
             keyboard = [
-                [InlineKeyboardButton(
-                    "✅ Yes, use new URL",
-                    callback_data=f"gateway_rpc_url_activate_{network_id}"
-                )],
-                [InlineKeyboardButton(
-                    f"Keep using {current_rpc}",
-                    callback_data="gateway_rpc_url_menu"
-                )],
+                [
+                    InlineKeyboardButton(
+                        "✅ Yes, use new URL",
+                        callback_data=f"gateway_rpc_url_activate_{network_id}",
+                    )
+                ],
+                [
+                    InlineKeyboardButton(
+                        f"Keep using {current_rpc}",
+                        callback_data="gateway_rpc_url_menu",
+                    )
+                ],
             ]
         else:
             success_text = (
@@ -519,8 +551,12 @@ async def _handle_url_input(
                 f"_Restart Gateway for changes to take effect\\._"
             )
             keyboard = [
-                [InlineKeyboardButton("🔄 Restart Gateway", callback_data="gateway_restart")],
-                [InlineKeyboardButton("« Back", callback_data="gateway_rpc_url_menu")]
+                [
+                    InlineKeyboardButton(
+                        "🔄 Restart Gateway", callback_data="gateway_restart"
+                    )
+                ],
+                [InlineKeyboardButton("« Back", callback_data="gateway_rpc_url_menu")],
             ]
 
         reply_markup = InlineKeyboardMarkup(keyboard)
@@ -532,7 +568,7 @@ async def _handle_url_input(
                     message_id=message_id,
                     text=success_text,
                     parse_mode="MarkdownV2",
-                    reply_markup=reply_markup
+                    reply_markup=reply_markup,
                 )
             except Exception as edit_err:
                 logger.warning(f"Could not edit message, sending new: {edit_err}")
@@ -540,14 +576,14 @@ async def _handle_url_input(
                     chat_id=update.effective_chat.id,
                     text=success_text,
                     parse_mode="MarkdownV2",
-                    reply_markup=reply_markup
+                    reply_markup=reply_markup,
                 )
         else:
             await update.get_bot().send_message(
                 chat_id=update.effective_chat.id,
                 text=success_text,
                 parse_mode="MarkdownV2",
-                reply_markup=reply_markup
+                reply_markup=reply_markup,
             )
 
         logger.info(f"Successfully updated URL for {network_id}")
@@ -556,8 +592,7 @@ async def _handle_url_input(
         logger.error(f"Error handling URL input: {e}", exc_info=True)
         try:
             await update.get_bot().send_message(
-                chat_id=update.effective_chat.id,
-                text=f"❌ Error saving URL: {str(e)}"
+                chat_id=update.effective_chat.id, text=f"❌ Error saving URL: {str(e)}"
             )
         except Exception as send_err:
             logger.error(f"Could not send error message: {send_err}")
@@ -585,8 +620,7 @@ async def activate_provider(
         # Update rpcProvider on the default network
         network_id = provider_info["default_network"]
         await client.gateway.update_network_config(
-            network_id,
-            {"rpc_provider": provider_key}
+            network_id, {"rpc_provider": provider_key}
         )
 
         await query.answer(f"✅ {provider_info['name']} activated! Restart Gateway.")
@@ -620,10 +654,7 @@ async def deactivate_provider(
 
         # Set rpcProvider back to "url" (custom)
         network_id = provider_info["default_network"]
-        await client.gateway.update_network_config(
-            network_id,
-            {"rpc_provider": "url"}
-        )
+        await client.gateway.update_network_config(network_id, {"rpc_provider": "url"})
 
         await query.answer(f"✅ {provider_info['name']} deactivated. Restart Gateway.")
 
@@ -650,10 +681,7 @@ async def activate_custom_url(
         )
 
         # Set rpcProvider to "url"
-        await client.gateway.update_network_config(
-            network_id,
-            {"rpc_provider": "url"}
-        )
+        await client.gateway.update_network_config(network_id, {"rpc_provider": "url"})
 
         network_escaped = escape_markdown_v2(network_id)
         success_text = (
@@ -662,8 +690,12 @@ async def activate_custom_url(
         )
 
         keyboard = [
-            [InlineKeyboardButton("🔄 Restart Gateway", callback_data="gateway_restart")],
-            [InlineKeyboardButton("« Back", callback_data="gateway_rpc_url_menu")]
+            [
+                InlineKeyboardButton(
+                    "🔄 Restart Gateway", callback_data="gateway_restart"
+                )
+            ],
+            [InlineKeyboardButton("« Back", callback_data="gateway_rpc_url_menu")],
         ]
         reply_markup = InlineKeyboardMarkup(keyboard)
 
@@ -680,6 +712,7 @@ async def activate_custom_url(
 # Custom URL Configuration
 # ============================================
 
+
 async def show_url_networks_menu(
     query, context: ContextTypes.DEFAULT_TYPE, show_all: bool = False
 ) -> None:
@@ -718,7 +751,8 @@ async def show_url_networks_menu(
                 showing_defaults = False
             else:
                 networks_to_show = [
-                    n for n in all_networks
+                    n
+                    for n in all_networks
                     if extract_network_id(n) in default_network_ids
                 ][:20]
                 showing_defaults = True
@@ -730,12 +764,13 @@ async def show_url_networks_menu(
             network_buttons = []
             for idx, network_item in enumerate(networks_to_show):
                 network_id = extract_network_id(network_item)
-                network_buttons.append([
-                    InlineKeyboardButton(
-                        network_id,
-                        callback_data=f"gateway_rpc_url_net_{idx}"
-                    )
-                ])
+                network_buttons.append(
+                    [
+                        InlineKeyboardButton(
+                            network_id, callback_data=f"gateway_rpc_url_net_{idx}"
+                        )
+                    ]
+                )
 
             if showing_defaults:
                 count_escaped = escape_markdown_v2(str(len(networks_to_show)))
@@ -747,10 +782,14 @@ async def show_url_networks_menu(
                     [
                         InlineKeyboardButton(
                             f"🌐 All Networks ({len(all_networks)})",
-                            callback_data="gateway_rpc_url_all"
+                            callback_data="gateway_rpc_url_all",
+                        )
+                    ],
+                    [
+                        InlineKeyboardButton(
+                            "« Back", callback_data="gateway_rpc_providers"
                         )
                     ],
-                    [InlineKeyboardButton("« Back", callback_data="gateway_rpc_providers")]
                 ]
             else:
                 count_escaped = escape_markdown_v2(str(len(all_networks)))
@@ -759,7 +798,11 @@ async def show_url_networks_menu(
                     "_Select a network to view and edit RPC settings:_"
                 )
                 keyboard = network_buttons + [
-                    [InlineKeyboardButton("« Back", callback_data="gateway_rpc_providers")]
+                    [
+                        InlineKeyboardButton(
+                            "« Back", callback_data="gateway_rpc_providers"
+                        )
+                    ]
                 ]
 
         reply_markup = InlineKeyboardMarkup(keyboard)
@@ -771,7 +814,9 @@ async def show_url_networks_menu(
     except Exception as e:
         logger.error(f"Error showing URL networks menu: {e}", exc_info=True)
         error_text = f"❌ Error loading networks: {escape_markdown_v2(str(e))}"
-        keyboard = [[InlineKeyboardButton("« Back", callback_data="gateway_rpc_providers")]]
+        keyboard = [
+            [InlineKeyboardButton("« Back", callback_data="gateway_rpc_providers")]
+        ]
         reply_markup = InlineKeyboardMarkup(keyboard)
         await query.message.edit_text(
             error_text, parse_mode="MarkdownV2", reply_markup=reply_markup
@@ -830,11 +875,10 @@ async def show_network_rpc_config(
         keyboard = [
             [
                 InlineKeyboardButton(
-                    "✏️ Edit URL",
-                    callback_data=f"gateway_rpc_url_edit_{network_id}"
+                    "✏️ Edit URL", callback_data=f"gateway_rpc_url_edit_{network_id}"
                 )
             ],
-            [InlineKeyboardButton("« Back", callback_data="gateway_rpc_url_menu")]
+            [InlineKeyboardButton("« Back", callback_data="gateway_rpc_url_menu")],
         ]
 
         reply_markup = InlineKeyboardMarkup(keyboard)
@@ -846,7 +890,9 @@ async def show_network_rpc_config(
     except Exception as e:
         logger.error(f"Error showing network RPC config: {e}", exc_info=True)
         error_text = f"❌ Error: {escape_markdown_v2(str(e))}"
-        keyboard = [[InlineKeyboardButton("« Back", callback_data="gateway_rpc_url_menu")]]
+        keyboard = [
+            [InlineKeyboardButton("« Back", callback_data="gateway_rpc_url_menu")]
+        ]
         reply_markup = InlineKeyboardMarkup(keyboard)
         await query.message.edit_text(
             error_text, parse_mode="MarkdownV2", reply_markup=reply_markup
diff --git a/handlers/config/gateway/tokens.py b/handlers/config/gateway/tokens.py
index d37fdf3e..e95d4264 100644
--- a/handlers/config/gateway/tokens.py
+++ b/handlers/config/gateway/tokens.py
@@ -7,7 +7,12 @@
 from telegram.ext import ContextTypes
 
 from ..user_preferences import get_active_server
-from ._shared import escape_markdown_v2, extract_network_id, get_default_networks, logger
+from ._shared import (
+    escape_markdown_v2,
+    extract_network_id,
+    get_default_networks,
+    logger,
+)
 
 # Gateway network ID -> GeckoTerminal network ID mapping
 NETWORK_TO_GECKO = {
@@ -70,7 +75,8 @@ async def show_tokens_menu(
             else:
                 # Filter to only default networks
                 networks_to_show = [
-                    n for n in all_networks
+                    n
+                    for n in all_networks
                     if extract_network_id(n) in default_network_ids
                 ][:20]
                 showing_defaults = True
@@ -103,14 +109,14 @@ async def show_tokens_menu(
                     [
                         InlineKeyboardButton(
                             f"🌐 All Networks ({len(all_networks)})",
-                            callback_data="gateway_token_all_networks"
+                            callback_data="gateway_token_all_networks",
                         )
                     ],
                     [
                         InlineKeyboardButton(
                             "« Back to Gateway", callback_data="config_gateway"
                         )
-                    ]
+                    ],
                 ]
             else:
                 count_escaped = escape_markdown_v2(str(len(all_networks)))
diff --git a/handlers/config/gateway/wallets.py b/handlers/config/gateway/wallets.py
index c6185578..b10e2b2f 100644
--- a/handlers/config/gateway/wallets.py
+++ b/handlers/config/gateway/wallets.py
@@ -94,7 +94,9 @@ async def show_wallets_menu(query, context: ContextTypes.DEFAULT_TYPE) -> None:
                 default_address = wallet_group.get("default_address", "")
                 for address in addresses:
                     is_default = address == default_address
-                    wallet_list.append({"chain": chain, "address": address, "is_default": is_default})
+                    wallet_list.append(
+                        {"chain": chain, "address": address, "is_default": is_default}
+                    )
 
             context.user_data["wallet_list"] = wallet_list
             total_wallets = len(wallet_list)
@@ -119,7 +121,9 @@ async def show_wallets_menu(query, context: ContextTypes.DEFAULT_TYPE) -> None:
                     "🟣" if chain == "solana" else "🔵"
                 )  # Solana purple, Ethereum blue
                 default_indicator = " ⭐️" if is_default else ""
-                button_text = f"{chain_icon} {chain.title()}: {display_addr}{default_indicator}"
+                button_text = (
+                    f"{chain_icon} {chain.title()}: {display_addr}{default_indicator}"
+                )
                 wallet_buttons.append(
                     [
                         InlineKeyboardButton(
@@ -232,7 +236,9 @@ async def handle_wallet_action(query, context: ContextTypes.DEFAULT_TYPE) -> Non
             wallet_list = context.user_data.get("wallet_list", [])
             if 0 <= idx < len(wallet_list):
                 wallet = wallet_list[idx]
-                await set_default_wallet(query, context, wallet["chain"], wallet["address"])
+                await set_default_wallet(
+                    query, context, wallet["chain"], wallet["address"]
+                )
             else:
                 await query.answer("❌ Wallet not found")
         except ValueError:
@@ -417,11 +423,7 @@ async def show_wallet_details(
             )
 
         keyboard.append(
-            [
-                InlineKeyboardButton(
-                    "« Back to Wallets", callback_data="gateway_wallets"
-                )
-            ]
+            [InlineKeyboardButton("« Back to Wallets", callback_data="gateway_wallets")]
         )
 
         reply_markup = InlineKeyboardMarkup(keyboard)
diff --git a/handlers/delegations.py b/handlers/delegations.py
index 438da11d..0db96e35 100644
--- a/handlers/delegations.py
+++ b/handlers/delegations.py
@@ -20,11 +20,7 @@
 from telegram import InlineKeyboardButton, InlineKeyboardMarkup, Update
 from telegram.ext import ContextTypes
 
-from condor.agents.delegate import (
-    get_all_delegations,
-    get_delegation,
-    stop_delegation,
-)
+from condor.agents.delegate import get_all_delegations, get_delegation, stop_delegation
 from handlers import clear_all_input_states
 from utils.auth import restricted
 from utils.telegram_formatters import escape_markdown_v2
diff --git a/handlers/dex/_shared.py b/handlers/dex/_shared.py
index 21098270..ff8762f0 100644
--- a/handlers/dex/_shared.py
+++ b/handlers/dex/_shared.py
@@ -11,16 +11,14 @@
 import logging
 from typing import Any, Callable, Dict, List, Optional
 
-from condor.cache import (
-    DEFAULT_CACHE_TTL,
-    clear_cache as _clear_cache,
-    evict_expired as _evict_expired,
-    get_cached as _get_cached,
-    invalidate_groups as _invalidate_groups,
-    invalidates as _invalidates,
-    set_cached as _set_cached,
-    cached_call as _cached_call,
-)
+from condor.cache import DEFAULT_CACHE_TTL
+from condor.cache import cached_call as _cached_call
+from condor.cache import clear_cache as _clear_cache
+from condor.cache import evict_expired as _evict_expired
+from condor.cache import get_cached as _get_cached
+from condor.cache import invalidate_groups as _invalidate_groups
+from condor.cache import invalidates as _invalidates
+from condor.cache import set_cached as _set_cached
 
 logger = logging.getLogger(__name__)
 
@@ -32,7 +30,9 @@
 _NS = "_cache"  # namespace for DEX cache
 
 
-def get_cached(user_data: dict, key: str, ttl: int = DEFAULT_CACHE_TTL) -> Optional[Any]:
+def get_cached(
+    user_data: dict, key: str, ttl: int = DEFAULT_CACHE_TTL
+) -> Optional[Any]:
     return _get_cached(user_data, key, ttl, namespace=_NS)
 
 
@@ -56,7 +56,9 @@ async def cached_call(
     *args,
     **kwargs,
 ) -> Any:
-    return await _cached_call(user_data, key, fetch_func, ttl, *args, namespace=_NS, **kwargs)
+    return await _cached_call(
+        user_data, key, fetch_func, ttl, *args, namespace=_NS, **kwargs
+    )
 
 
 # ============================================
diff --git a/handlers/executors/__init__.py b/handlers/executors/__init__.py
index c0ad7e3a..4a9118e9 100644
--- a/handlers/executors/__init__.py
+++ b/handlers/executors/__init__.py
@@ -87,14 +87,9 @@ async def executors_callback_handler(
     # Import handlers lazily to avoid circular imports
     from .grid import handle_connector_select as grid_handle_connector_select
     from .grid import handle_deploy as grid_handle_deploy
-    from .grid import (
-        handle_interval_select,
-    )
+    from .grid import handle_interval_select
     from .grid import handle_pair_input as grid_handle_pair_input
-    from .grid import (
-        show_step_2_combined,
-        start_grid_wizard,
-    )
+    from .grid import show_step_2_combined, start_grid_wizard
     from .menu import (
         handle_close,
         handle_confirm_stop_executor,
@@ -107,14 +102,9 @@ async def executors_callback_handler(
     )
     from .position import handle_connector_select as pos_handle_connector_select
     from .position import handle_deploy as pos_handle_deploy
-    from .position import (
-        handle_entry_price_select as pos_handle_entry_price,
-    )
+    from .position import handle_entry_price_select as pos_handle_entry_price
     from .position import handle_pair_input as pos_handle_pair_input
-    from .position import (
-        show_step_2_config,
-        start_position_wizard,
-    )
+    from .position import show_step_2_config, start_position_wizard
 
     # Menu actions
     if action == "menu":
diff --git a/handlers/executors/grid.py b/handlers/executors/grid.py
index 9bdc8789..343bf36a 100644
--- a/handlers/executors/grid.py
+++ b/handlers/executors/grid.py
@@ -48,7 +48,11 @@
     set_executor_config,
 )
 
-ORDER_TYPE_LABELS = {ORDER_TYPE_MARKET: "MARKET", ORDER_TYPE_LIMIT: "LIMIT", ORDER_TYPE_LIMIT_MAKER: "LIMIT_MAKER"}
+ORDER_TYPE_LABELS = {
+    ORDER_TYPE_MARKET: "MARKET",
+    ORDER_TYPE_LIMIT: "LIMIT",
+    ORDER_TYPE_LIMIT_MAKER: "LIMIT_MAKER",
+}
 
 logger = logging.getLogger(__name__)
 
@@ -94,8 +98,12 @@ def _format_config_block(config: Dict[str, Any]) -> str:
 
     coerce_tp = config.get("coerce_tp_to_step", False)
     keep_position = config.get("keep_position", False)
-    open_ot = ORDER_TYPE_LABELS.get(config.get("open_order_type", ORDER_TYPE_LIMIT), "LIMIT")
-    tp_ot = ORDER_TYPE_LABELS.get(config.get("take_profit_order_type", ORDER_TYPE_LIMIT), "LIMIT")
+    open_ot = ORDER_TYPE_LABELS.get(
+        config.get("open_order_type", ORDER_TYPE_LIMIT), "LIMIT"
+    )
+    tp_ot = ORDER_TYPE_LABELS.get(
+        config.get("take_profit_order_type", ORDER_TYPE_LIMIT), "LIMIT"
+    )
 
     lines = [
         f"side={side_label}",
@@ -449,7 +457,9 @@ async def handle_pair_input(
             pair = correct_pair
         else:
             # Fallback: Get correctly formatted pair from trading rules
-            trading_rules = await get_trading_rules(context.user_data, client, connector)
+            trading_rules = await get_trading_rules(
+                context.user_data, client, connector
+            )
             fallback_pair = get_correct_pair_format(trading_rules, pair)
             if fallback_pair:
                 pair = fallback_pair
@@ -849,7 +859,11 @@ async def handle_config_input(
 
         # Handle order type fields: accept MARKET/LIMIT/LIMIT_MAKER or 1/2/3
         if key in ("open_order_type", "take_profit_order_type"):
-            ot_map = {"market": ORDER_TYPE_MARKET, "limit": ORDER_TYPE_LIMIT, "limit_maker": ORDER_TYPE_LIMIT_MAKER}
+            ot_map = {
+                "market": ORDER_TYPE_MARKET,
+                "limit": ORDER_TYPE_LIMIT,
+                "limit_maker": ORDER_TYPE_LIMIT_MAKER,
+            }
             val_lower = value.lower()
             if val_lower in ot_map:
                 updates[key] = ot_map[val_lower]
@@ -977,7 +991,9 @@ async def handle_deploy(update: Update, context: ContextTypes.DEFAULT_TYPE) -> N
         "triple_barrier_config": {
             "take_profit": config.get("take_profit", 0.0002),
             "open_order_type": config.get("open_order_type", ORDER_TYPE_LIMIT),
-            "take_profit_order_type": config.get("take_profit_order_type", ORDER_TYPE_LIMIT),
+            "take_profit_order_type": config.get(
+                "take_profit_order_type", ORDER_TYPE_LIMIT
+            ),
         },
     }
 
diff --git a/handlers/executors/menu.py b/handlers/executors/menu.py
index 665a4dbb..7fc43f43 100644
--- a/handlers/executors/menu.py
+++ b/handlers/executors/menu.py
@@ -284,8 +284,7 @@ async def show_history(
         # so fetch without status filter and exclude running ones.
         result = await search_running_executors(client, status=None, limit=100)
         history = [
-            ex for ex in result
-            if str(ex.get("status", "")).upper() != "RUNNING"
+            ex for ex in result if str(ex.get("status", "")).upper() != "RUNNING"
         ]
 
         # Sort by timestamp descending (most recent first)
@@ -470,7 +469,9 @@ async def show_history_detail(
     context.user_data["current_executor_id"] = full_id
 
     # Reuse the detail rendering
-    await _render_executor_detail(update, context, executor, back_callback="executors:history")
+    await _render_executor_detail(
+        update, context, executor, back_callback="executors:history"
+    )
 
 
 # ============================================
@@ -526,7 +527,9 @@ async def show_executor_detail(
         context.user_data["current_executor"] = executor
         context.user_data["current_executor_id"] = full_id
 
-        await _render_executor_detail(update, context, executor, back_callback="executors:menu")
+        await _render_executor_detail(
+            update, context, executor, back_callback="executors:menu"
+        )
 
     except Exception as e:
         logger.error(f"Error showing executor detail: {e}", exc_info=True)
@@ -602,9 +605,9 @@ async def _render_executor_detail(
         take_profit = config.get("take_profit", 0) or tbc.get("take_profit", 0)
         time_limit = config.get("time_limit", 0) or tbc.get("time_limit", 0)
         trailing_cfg = tbc.get("trailing_stop") or {}
-        trailing_act = config.get(
-            "trailing_stop_activation", 0
-        ) or trailing_cfg.get("activation_price", 0)
+        trailing_act = config.get("trailing_stop_activation", 0) or trailing_cfg.get(
+            "activation_price", 0
+        )
         trailing_delta = config.get("trailing_stop_delta", 0) or trailing_cfg.get(
             "trailing_delta", 0
         )
@@ -678,8 +681,12 @@ async def _render_executor_detail(
             mid_price = (start_price + end_price) / 2
             grid_range = (end_price - start_price) / start_price
             min_step = max(min_spread, 0)
-            max_levels_by_amount = int(amount / min_order_quote) if min_order_quote else 1
-            max_levels_by_step = int(grid_range / min_step) if min_step > 0 else max_levels_by_amount
+            max_levels_by_amount = (
+                int(amount / min_order_quote) if min_order_quote else 1
+            )
+            max_levels_by_step = (
+                int(grid_range / min_step) if min_step > 0 else max_levels_by_amount
+            )
             n_levels = max(1, min(max_levels_by_amount, max_levels_by_step))
             amount_per_level = amount / n_levels
             step = grid_range / max(n_levels - 1, 1)
@@ -687,10 +694,16 @@ async def _render_executor_detail(
 
             lines.append("")
             lines.append(f"📏 *Grid Metrics*")
-            lines.append(f"  Levels: `{n_levels}` \\| Step: `{escape_markdown_v2(f'{step:.4%}')}`")
-            lines.append(f"  Per Level: `${escape_markdown_v2(f'{amount_per_level:,.2f}')}`")
+            lines.append(
+                f"  Levels: `{n_levels}` \\| Step: `{escape_markdown_v2(f'{step:.4%}')}`"
+            )
+            lines.append(
+                f"  Per Level: `${escape_markdown_v2(f'{amount_per_level:,.2f}')}`"
+            )
             if coerce_tp and eff_tp != take_profit:
-                lines.append(f"  Eff\\. TP: `{escape_markdown_v2(f'{eff_tp:.4%}')}` \\(coerced to step\\)")
+                lines.append(
+                    f"  Eff\\. TP: `{escape_markdown_v2(f'{eff_tp:.4%}')}` \\(coerced to step\\)"
+                )
 
     lines.append("")
     lines.append(f"📊 *Performance*")
@@ -724,6 +737,7 @@ async def _render_executor_detail(
     # Created timestamp
     if created_at:
         from datetime import datetime, timezone
+
         try:
             dt = datetime.fromtimestamp(created_at, tz=timezone.utc)
             created_str = dt.strftime("%m/%d %H:%M UTC")
diff --git a/handlers/executors/position.py b/handlers/executors/position.py
index 08343284..ef4ee23c 100644
--- a/handlers/executors/position.py
+++ b/handlers/executors/position.py
@@ -16,10 +16,7 @@
 from telegram.error import BadRequest
 from telegram.ext import ContextTypes
 
-from handlers.bots._shared import (
-    fetch_current_price,
-    get_available_cex_connectors,
-)
+from handlers.bots._shared import fetch_current_price, get_available_cex_connectors
 from handlers.cex._shared import (
     get_cex_balances,
     get_correct_pair_format,
@@ -46,8 +43,12 @@
 
 # Order type mapping
 ORDER_TYPE_MAP = {
-    "MARKET": 1, "LIMIT": 2, "LIMIT_MAKER": 3,
-    "1": 1, "2": 2, "3": 3,
+    "MARKET": 1,
+    "LIMIT": 2,
+    "LIMIT_MAKER": 3,
+    "1": 1,
+    "2": 2,
+    "3": 3,
 }
 ORDER_TYPE_LABELS = {1: "MARKET", 2: "LIMIT", 3: "LIMIT_MAKER"}
 
@@ -82,7 +83,9 @@ def _is_perpetual(connector: str) -> bool:
     return "_perpetual" in connector.lower()
 
 
-def _format_config_block(config: Dict[str, Any], current_price: Optional[float] = None) -> str:
+def _format_config_block(
+    config: Dict[str, Any], current_price: Optional[float] = None
+) -> str:
     """Format config as key=value block for display inside a code block."""
     side = normalize_side(config.get("side", SIDE_LONG))
     side_label = "LONG" if side == SIDE_LONG else "SHORT"
@@ -213,33 +216,43 @@ def _build_step_2_text(
     return "\n".join(lines)
 
 
-def _build_step_2_keyboard(current_price: Optional[float] = None) -> InlineKeyboardMarkup:
+def _build_step_2_keyboard(
+    current_price: Optional[float] = None,
+) -> InlineKeyboardMarkup:
     """Build the keyboard for step 2."""
     keyboard = []
 
     # Entry price quick-pick buttons
     if current_price and current_price > 0:
-        keyboard.append([
-            InlineKeyboardButton("📊 Market", callback_data="executors:pos_entry:market"),
-            InlineKeyboardButton(
-                f"📊 Current ({current_price:,.6g})",
-                callback_data="executors:pos_entry:current",
-            ),
-        ])
-        keyboard.append([
-            InlineKeyboardButton("-2%", callback_data="executors:pos_entry:-2"),
-            InlineKeyboardButton("-1%", callback_data="executors:pos_entry:-1"),
-            InlineKeyboardButton("+1%", callback_data="executors:pos_entry:+1"),
-            InlineKeyboardButton("+2%", callback_data="executors:pos_entry:+2"),
-        ])
+        keyboard.append(
+            [
+                InlineKeyboardButton(
+                    "📊 Market", callback_data="executors:pos_entry:market"
+                ),
+                InlineKeyboardButton(
+                    f"📊 Current ({current_price:,.6g})",
+                    callback_data="executors:pos_entry:current",
+                ),
+            ]
+        )
+        keyboard.append(
+            [
+                InlineKeyboardButton("-2%", callback_data="executors:pos_entry:-2"),
+                InlineKeyboardButton("-1%", callback_data="executors:pos_entry:-1"),
+                InlineKeyboardButton("+1%", callback_data="executors:pos_entry:+1"),
+                InlineKeyboardButton("+2%", callback_data="executors:pos_entry:+2"),
+            ]
+        )
 
     keyboard.append(
         [InlineKeyboardButton("🚀 Deploy", callback_data="executors:pos_deploy")]
     )
-    keyboard.append([
-        InlineKeyboardButton("⬅️ Back", callback_data="executors:create_position"),
-        InlineKeyboardButton("❌ Cancel", callback_data="executors:menu"),
-    ])
+    keyboard.append(
+        [
+            InlineKeyboardButton("⬅️ Back", callback_data="executors:create_position"),
+            InlineKeyboardButton("❌ Cancel", callback_data="executors:menu"),
+        ]
+    )
     return InlineKeyboardMarkup(keyboard)
 
 
@@ -737,7 +750,12 @@ async def handle_config_input(
             continue
 
         # Handle order type fields: accept MARKET/LIMIT/LIMIT_MAKER or 1/2/3
-        if key in ("open_order_type", "take_profit_order_type", "stop_loss_order_type", "time_limit_order_type"):
+        if key in (
+            "open_order_type",
+            "take_profit_order_type",
+            "stop_loss_order_type",
+            "time_limit_order_type",
+        ):
             mapped = ORDER_TYPE_MAP.get(value.upper())
             if mapped:
                 updates[key] = mapped
@@ -844,7 +862,8 @@ async def handle_deploy(update: Update, context: ContextTypes.DEFAULT_TYPE) -> N
                 set_executor_config(context, config)
             else:
                 await query.answer(
-                    "Could not fetch price to convert total_amount_quote", show_alert=True
+                    "Could not fetch price to convert total_amount_quote",
+                    show_alert=True,
                 )
                 return
         except Exception as e:
diff --git a/mcp_servers/condor/tools/context.py b/mcp_servers/condor/tools/context.py
index 65fc05fb..8d94cdf8 100644
--- a/mcp_servers/condor/tools/context.py
+++ b/mcp_servers/condor/tools/context.py
@@ -21,11 +21,16 @@ async def get_user_context() -> dict:
     # New Agents inherit active_agent_key by default, so the coordinator should
     # never invent one — an invented key names a backend that may not exist.
     try:
-        from condor.preferences import get_active_agent_key, get_custom_providers, load_user_data_for
+        from condor.preferences import (
+            get_active_agent_key,
+            get_custom_providers,
+            load_user_data_for,
+        )
 
         context["active_agent_key"] = get_active_agent_key(settings.user_id)
         context["custom_llm_endpoints"] = [
-            p["name"] for p in get_custom_providers(load_user_data_for(settings.user_id))
+            p["name"]
+            for p in get_custom_providers(load_user_data_for(settings.user_id))
         ]
     except Exception:
         context["active_agent_key"] = None
diff --git a/mcp_servers/condor/tools/servers.py b/mcp_servers/condor/tools/servers.py
index 7c15a935..8e79399b 100644
--- a/mcp_servers/condor/tools/servers.py
+++ b/mcp_servers/condor/tools/servers.py
@@ -15,13 +15,15 @@ def list_servers() -> dict:
         if not server:
             continue
         perm = cm.get_server_permission(settings.user_id, name)
-        servers.append({
-            "name": name,
-            "host": server["host"],
-            "port": server["port"],
-            "permission": perm.value if perm else "unknown",
-            "is_active": name == active_server,
-        })
+        servers.append(
+            {
+                "name": name,
+                "host": server["host"],
+                "port": server["port"],
+                "permission": perm.value if perm else "unknown",
+                "is_active": name == active_server,
+            }
+        )
     return {"servers": servers, "active_server": active_server}
 
 
diff --git a/mcp_servers/hummingbot_api/executor_preferences.py b/mcp_servers/hummingbot_api/executor_preferences.py
index 2fe3d8ae..2e054313 100644
--- a/mcp_servers/hummingbot_api/executor_preferences.py
+++ b/mcp_servers/hummingbot_api/executor_preferences.py
@@ -6,6 +6,7 @@
 
 Preferences are stored at: ~/.hummingbot_mcp/executor_preferences.md
 """
+
 import logging
 import re
 from pathlib import Path
@@ -143,7 +144,9 @@ def _ensure_preferences_exist(self) -> None:
         # Create default preferences file if it doesn't exist
         if not self.preferences_path.exists():
             self._write_template()
-            logger.info(f"Created default executor preferences at {self.preferences_path}")
+            logger.info(
+                f"Created default executor preferences at {self.preferences_path}"
+            )
 
     def _write_template(self) -> None:
         """Write the default template to the preferences file."""
@@ -169,7 +172,7 @@ def _parse_yaml_blocks(self, content: str) -> dict[str, dict[str, Any]]:
             Dictionary mapping executor type to its configuration
         """
         # Pattern to match YAML code blocks
-        yaml_pattern = r'```yaml\s*\n([\s\S]*?)```'
+        yaml_pattern = r"```yaml\s*\n([\s\S]*?)```"
 
         defaults = {}
         matches = re.findall(yaml_pattern, content)
@@ -244,12 +247,14 @@ def update_defaults(self, executor_type: str, config: dict[str, Any]) -> None:
         merged_config = {**existing_defaults, **config}
 
         # Create the new YAML block
-        new_yaml = yaml.dump({executor_type: merged_config}, default_flow_style=False, sort_keys=False)
+        new_yaml = yaml.dump(
+            {executor_type: merged_config}, default_flow_style=False, sort_keys=False
+        )
         new_block = f"```yaml\n{new_yaml}```"
 
         # Pattern to find the existing block for this executor type
         # Look for ```yaml followed by the executor type key
-        pattern = rf'```yaml\s*\n{re.escape(executor_type)}:[\s\S]*?```'
+        pattern = rf"```yaml\s*\n{re.escape(executor_type)}:[\s\S]*?```"
 
         if re.search(pattern, content):
             # Replace existing block
@@ -260,23 +265,22 @@ def update_defaults(self, executor_type: str, config: dict[str, Any]) -> None:
             section_header = f"### {executor_type.replace('_', ' ').title()} Defaults"
             if section_header in content:
                 # Find the section and add after the header
-                pattern = rf'({re.escape(section_header)}\s*\n\n)```yaml[\s\S]*?```'
+                pattern = rf"({re.escape(section_header)}\s*\n\n)```yaml[\s\S]*?```"
                 if re.search(pattern, content):
-                    content = re.sub(pattern, rf'\1{new_block}', content)
+                    content = re.sub(pattern, rf"\1{new_block}", content)
                 else:
                     # Section exists but no yaml block, add it
                     content = content.replace(
-                        section_header,
-                        f"{section_header}\n\n{new_block}"
+                        section_header, f"{section_header}\n\n{new_block}"
                     )
             else:
                 # No section found, append before the footer
-                footer_pattern = r'\n---\s*\n\*Last updated:'
+                footer_pattern = r"\n---\s*\n\*Last updated:"
                 if re.search(footer_pattern, content):
                     content = re.sub(
                         footer_pattern,
                         f"\n### {executor_type.replace('_', ' ').title()} Defaults\n\n{new_block}\n\n---\n\n*Last updated:",
-                        content
+                        content,
                     )
                 else:
                     # Just append at the end
@@ -284,17 +288,18 @@ def update_defaults(self, executor_type: str, config: dict[str, Any]) -> None:
 
         # Update the last updated timestamp
         from datetime import datetime
+
         timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
         content = re.sub(
-            r'\*Last updated:.*\*',
-            f'*Last updated: {timestamp}*',
-            content
+            r"\*Last updated:.*\*", f"*Last updated: {timestamp}*", content
         )
 
         self._write_content(content)
         logger.info(f"Updated defaults for {executor_type}")
 
-    def merge_with_defaults(self, executor_type: str, user_config: dict[str, Any]) -> dict[str, Any]:
+    def merge_with_defaults(
+        self, executor_type: str, user_config: dict[str, Any]
+    ) -> dict[str, Any]:
         """Merge user configuration with stored defaults.
 
         User-provided values take precedence over defaults.
diff --git a/mcp_servers/hummingbot_api/formatters/__init__.py b/mcp_servers/hummingbot_api/formatters/__init__.py
index aee5bf34..1a83936f 100644
--- a/mcp_servers/hummingbot_api/formatters/__init__.py
+++ b/mcp_servers/hummingbot_api/formatters/__init__.py
@@ -28,19 +28,11 @@
     truncate_string,
 )
 
-# Table builder for creating consistent tables
-from .table_builder import ColumnDef, TableBuilder, create_simple_table
-
 # Bot formatters
-from .bots import format_active_bots_as_table, format_bot_logs_as_table, format_controller_state
-
-# Gateway formatters
-from .gateway import (
-    format_amm_result,
-    format_gateway_clmm_pool_result,
-    format_gateway_config_result,
-    format_gateway_container_result,
-    format_gateway_swap_result,
+from .bots import (
+    format_active_bots_as_table,
+    format_bot_logs_as_table,
+    format_controller_state,
 )
 
 # Executor formatters
@@ -54,6 +46,15 @@
     format_positions_summary,
 )
 
+# Gateway formatters
+from .gateway import (
+    format_amm_result,
+    format_gateway_clmm_pool_result,
+    format_gateway_config_result,
+    format_gateway_container_result,
+    format_gateway_swap_result,
+)
+
 # Market data formatters
 from .market_data import (
     format_candles_as_table,
@@ -64,6 +65,9 @@
 # Portfolio formatters
 from .portfolio import format_portfolio_as_table
 
+# Table builder for creating consistent tables
+from .table_builder import ColumnDef, TableBuilder, create_simple_table
+
 # Trading formatters
 from .trading import format_orders_as_table, format_positions_as_table
 
diff --git a/mcp_servers/hummingbot_api/formatters/base.py b/mcp_servers/hummingbot_api/formatters/base.py
index 79f79747..7a898033 100644
--- a/mcp_servers/hummingbot_api/formatters/base.py
+++ b/mcp_servers/hummingbot_api/formatters/base.py
@@ -6,6 +6,7 @@
 It also includes field accessor utilities for safely extracting values
 from dictionaries with fallback support.
 """
+
 from datetime import datetime, timezone
 from typing import Any
 
@@ -75,7 +76,7 @@ def format_timestamp(ts: Any, format_str: str = "%m/%d %H:%M") -> str:
             dt = datetime.fromtimestamp(timestamp, tz=timezone.utc)
         else:
             # Try parsing ISO format string
-            dt = datetime.fromisoformat(str(ts).replace('Z', '+00:00'))
+            dt = datetime.fromisoformat(str(ts).replace("Z", "+00:00"))
             # Convert to UTC if timezone-aware
             if dt.tzinfo is not None:
                 dt = dt.astimezone(timezone.utc)
@@ -190,7 +191,7 @@ def truncate_string(text: str, max_len: int = 80, suffix: str = "...") -> str:
     """
     if len(text) <= max_len:
         return text
-    return text[:max_len - len(suffix)] + suffix
+    return text[: max_len - len(suffix)] + suffix
 
 
 def truncate_address(address: str, prefix_len: int = 8, suffix_len: int = 6) -> str:
@@ -286,10 +287,7 @@ def get_timestamp_field(item: dict[str, Any], *keys: str) -> str:
 
 
 def get_truncated(
-    item: dict[str, Any],
-    key: str,
-    max_len: int,
-    default: str = "N/A"
+    item: dict[str, Any], key: str, max_len: int, default: str = "N/A"
 ) -> str:
     """
     Get a string field and truncate it to a maximum length.
@@ -320,7 +318,7 @@ def get_formatted_number(
     *keys: str,
     decimals: int = 2,
     compact: bool = True,
-    default: str = "N/A"
+    default: str = "N/A",
 ) -> str:
     """
     Get a numeric field and format it.
@@ -351,7 +349,7 @@ def get_formatted_currency(
     *keys: str,
     symbol: str = "$",
     decimals: int = 2,
-    default: str = "N/A"
+    default: str = "N/A",
 ) -> str:
     """
     Get a numeric field and format it as currency.
@@ -377,10 +375,7 @@ def get_formatted_currency(
 
 
 def get_formatted_percentage(
-    item: dict[str, Any],
-    *keys: str,
-    decimals: int = 2,
-    default: str = "N/A"
+    item: dict[str, Any], *keys: str, decimals: int = 2, default: str = "N/A"
 ) -> str:
     """
     Get a decimal field and format it as percentage.
diff --git a/mcp_servers/hummingbot_api/formatters/bots.py b/mcp_servers/hummingbot_api/formatters/bots.py
index 07ccc602..e3b59f7f 100644
--- a/mcp_servers/hummingbot_api/formatters/bots.py
+++ b/mcp_servers/hummingbot_api/formatters/bots.py
@@ -3,6 +3,7 @@
 
 This module provides table formatters for bot logs and active bot status.
 """
+
 from typing import Any
 
 from .base import (
@@ -121,13 +122,30 @@ def format_active_bots_as_table(bots_data: dict[str, Any]) -> str:
             # Bot with controllers
             for controller_name, controller_data in performance.items():
                 ctrl_state = format_controller_state(controller_data)
-                ctrl_perf = controller_data.get("performance", {}) if isinstance(controller_data, dict) else {}
+                ctrl_perf = (
+                    controller_data.get("performance", {})
+                    if isinstance(controller_data, dict)
+                    else {}
+                )
 
-                realized_pnl = format_number(get_field(ctrl_perf, "realized_pnl_quote", default=None), compact=False)
-                unrealized_pnl = format_number(get_field(ctrl_perf, "unrealized_pnl_quote", default=None), compact=False)
-                global_pnl = format_number(get_field(ctrl_perf, "global_pnl_quote", default=None), compact=False)
-                global_pnl_pct = format_percentage(get_field(ctrl_perf, "global_pnl_pct", default=None))
-                volume = format_number(get_field(ctrl_perf, "volume_traded", default=None), compact=False)
+                realized_pnl = format_number(
+                    get_field(ctrl_perf, "realized_pnl_quote", default=None),
+                    compact=False,
+                )
+                unrealized_pnl = format_number(
+                    get_field(ctrl_perf, "unrealized_pnl_quote", default=None),
+                    compact=False,
+                )
+                global_pnl = format_number(
+                    get_field(ctrl_perf, "global_pnl_quote", default=None),
+                    compact=False,
+                )
+                global_pnl_pct = format_percentage(
+                    get_field(ctrl_perf, "global_pnl_pct", default=None)
+                )
+                volume = format_number(
+                    get_field(ctrl_perf, "volume_traded", default=None), compact=False
+                )
 
                 row = (
                     f"{bot_name} | "
diff --git a/mcp_servers/hummingbot_api/formatters/executors.py b/mcp_servers/hummingbot_api/formatters/executors.py
index ab3ab549..a4907fd7 100644
--- a/mcp_servers/hummingbot_api/formatters/executors.py
+++ b/mcp_servers/hummingbot_api/formatters/executors.py
@@ -4,6 +4,7 @@
 This module provides table formatters for executor types, executor lists,
 positions held, and executor configuration schemas.
 """
+
 from typing import Any
 
 from .base import (
@@ -44,9 +45,15 @@ def format_executor_types_table(executor_types: list[dict[str, Any]]) -> str:
     rows = []
     for exec_type in executor_types:
         name = str(get_field(exec_type, "name", default="unknown"))[:20]
-        description = truncate_string(str(get_field(exec_type, "description", default="")), max_len=40)
-        use_when = truncate_string(str(get_field(exec_type, "use_when", default="")), max_len=40)
-        avoid_when = truncate_string(str(get_field(exec_type, "avoid_when", default="")), max_len=40)
+        description = truncate_string(
+            str(get_field(exec_type, "description", default="")), max_len=40
+        )
+        use_when = truncate_string(
+            str(get_field(exec_type, "use_when", default="")), max_len=40
+        )
+        avoid_when = truncate_string(
+            str(get_field(exec_type, "avoid_when", default="")), max_len=40
+        )
 
         row = f"{name:20} | {description:40} | {use_when:40} | {avoid_when}"
         rows.append(row)
@@ -54,7 +61,6 @@ def format_executor_types_table(executor_types: list[dict[str, Any]]) -> str:
     return f"{header}\n{separator}\n" + "\n".join(rows)
 
 
-
 def format_executors_table(executors: list[dict[str, Any]]) -> str:
     """
     Format a list of executors as a table.
@@ -78,7 +84,9 @@ def format_executors_table(executors: list[dict[str, Any]]) -> str:
     rows = []
     for executor in executors:
         exec_id = str(get_field(executor, "id", "executor_id", default=""))
-        exec_type = str(get_field(executor, "type", "executor_type", default="unknown"))[:15]
+        exec_type = str(
+            get_field(executor, "type", "executor_type", default="unknown")
+        )[:15]
         connector = str(get_field(executor, "connector_name", default=""))[:17]
         trading_pair = str(get_field(executor, "trading_pair", default=""))[:10]
         status = str(get_field(executor, "status", default="unknown"))
@@ -92,10 +100,20 @@ def format_executors_table(executors: list[dict[str, Any]]) -> str:
         side = str(side)[:4] if side else ""
 
         # Volume is filled_amount_quote
-        volume = format_number(get_field(executor, "filled_amount_quote", default=None), decimals=2, compact=True)
-        pnl = format_number(get_field(executor, "net_pnl_quote", "pnl", default=None), decimals=2, compact=False)
-
-        created = format_timestamp(get_field(executor, "timestamp", "created_at", default=0))
+        volume = format_number(
+            get_field(executor, "filled_amount_quote", default=None),
+            decimals=2,
+            compact=True,
+        )
+        pnl = format_number(
+            get_field(executor, "net_pnl_quote", "pnl", default=None),
+            decimals=2,
+            compact=False,
+        )
+
+        created = format_timestamp(
+            get_field(executor, "timestamp", "created_at", default=0)
+        )
 
         row = f"{exec_id:44} | {exec_type:15} | {connector:17} | {trading_pair:10} | {status:10} | {close_type:20} | {side:4} | {volume:>11} | {pnl:>9} | {created}"
         rows.append(row)
@@ -157,7 +175,9 @@ def format_executor_detail(executor: dict[str, Any]) -> str:
 
     entry_price = get_field(executor, "entry_price", default=None)
     if entry_price is not None and entry_price != "N/A":
-        output += f"Entry Price: {format_number(entry_price, decimals=6, compact=False)}\n"
+        output += (
+            f"Entry Price: {format_number(entry_price, decimals=6, compact=False)}\n"
+        )
 
     current_price = get_field(executor, "current_price", default=None)
     if current_price is not None and current_price != "N/A":
@@ -201,7 +221,11 @@ def format_executor_detail(executor: dict[str, Any]) -> str:
         output += f"Created: {format_timestamp(created, '%Y-%m-%d %H:%M:%S')}\n"
 
     close_timestamp = get_field(executor, "close_timestamp", default=None)
-    if close_timestamp is not None and close_timestamp != "N/A" and close_timestamp != 0:
+    if (
+        close_timestamp is not None
+        and close_timestamp != "N/A"
+        and close_timestamp != 0
+    ):
         output += f"Closed: {format_timestamp(close_timestamp, '%Y-%m-%d %H:%M:%S')}\n"
 
     # Show full config if present (creation parameters)
@@ -224,13 +248,17 @@ def format_executor_detail(executor: dict[str, Any]) -> str:
             output += f"  end_price: {format_number(max(grid_levels), decimals=2, compact=False)}\n"
             output += f"  num_levels: {len(grid_levels)}\n"
             sorted_levels = sorted(grid_levels)
-            spreads = [(sorted_levels[i+1] - sorted_levels[i]) / sorted_levels[i]
-                       for i in range(len(sorted_levels) - 1)]
+            spreads = [
+                (sorted_levels[i + 1] - sorted_levels[i]) / sorted_levels[i]
+                for i in range(len(sorted_levels) - 1)
+            ]
             avg_spread = sum(spreads) / len(spreads) if spreads else 0
             output += f"  avg_spread_between_levels: {format_percentage(avg_spread)}\n"
             if isinstance(grid_tp, list) and len(grid_tp) > 1:
-                tp_diffs = [abs(grid_tp[i] - grid_levels[i]) / grid_levels[i]
-                            for i in range(min(len(grid_tp), len(grid_levels)))]
+                tp_diffs = [
+                    abs(grid_tp[i] - grid_levels[i]) / grid_levels[i]
+                    for i in range(min(len(grid_tp), len(grid_levels)))
+                ]
                 avg_tp = sum(tp_diffs) / len(tp_diffs) if tp_diffs else 0
                 output += f"  avg_take_profit: {format_percentage(avg_tp)}\n"
 
@@ -277,7 +305,9 @@ def format_positions_held_table(positions: list[dict[str, Any]]) -> str:
         amount_val = get_field(position, "net_amount_base", "amount", default=None)
         amount = format_number(amount_val, decimals=6, compact=False)
         # Handle both 'entry_price' and 'buy_breakeven_price' field names
-        entry_price_val = get_field(position, "buy_breakeven_price", "entry_price", default=None)
+        entry_price_val = get_field(
+            position, "buy_breakeven_price", "entry_price", default=None
+        )
         entry_price = format_number(entry_price_val, decimals=4, compact=False)
         # Compute notional value (amount * entry_price)
         notional_val = None
@@ -287,8 +317,16 @@ def format_positions_held_table(positions: list[dict[str, Any]]) -> str:
             except (ValueError, TypeError):
                 pass
         notional = format_number(notional_val, decimals=2, compact=False)
-        current_price = format_number(get_field(position, "current_price", default=None), decimals=4, compact=False)
-        unrealized_pnl = format_number(get_field(position, "unrealized_pnl_quote", "unrealized_pnl", default=None), decimals=2, compact=False)
+        current_price = format_number(
+            get_field(position, "current_price", default=None),
+            decimals=4,
+            compact=False,
+        )
+        unrealized_pnl = format_number(
+            get_field(position, "unrealized_pnl_quote", "unrealized_pnl", default=None),
+            decimals=2,
+            compact=False,
+        )
         leverage = str(get_field(position, "leverage", default="1"))[:8]
 
         row = f"{connector:19} | {trading_pair:12} | {side:4} | {amount:>12} | {notional:>12} | {entry_price:>12} | {current_price:>13} | {unrealized_pnl:>14} | {leverage:>8}"
@@ -340,7 +378,9 @@ def format_positions_summary(summary: dict[str, Any]) -> str:
     return output
 
 
-def format_executor_schema_table(schema: dict[str, Any], defaults: dict[str, Any] | None = None) -> str:
+def format_executor_schema_table(
+    schema: dict[str, Any], defaults: dict[str, Any] | None = None
+) -> str:
     """
     Format executor configuration schema as a table.
 
@@ -379,7 +419,9 @@ def format_executor_schema_table(schema: dict[str, Any], defaults: dict[str, Any
         if isinstance(param_info, dict):
             param_type = param_info.get("type", param_info.get("anyOf", "unknown"))
             if isinstance(param_type, list):
-                param_type = "/".join(str(t.get("type", t)) for t in param_type if isinstance(t, dict))
+                param_type = "/".join(
+                    str(t.get("type", t)) for t in param_type if isinstance(t, dict)
+                )
             param_type = str(param_type)[:17]
 
             required = "Yes" if param_name in required_fields else "No"
@@ -390,9 +432,13 @@ def format_executor_schema_table(schema: dict[str, Any], defaults: dict[str, Any
             default_str = truncate_string(str(default_val), max_len=16)
 
             user_default = defaults.get(param_name, "")
-            user_default_str = truncate_string(str(user_default), max_len=16) if user_default else "-"
+            user_default_str = (
+                truncate_string(str(user_default), max_len=16) if user_default else "-"
+            )
 
-            description = truncate_string(str(param_info.get("description", "")), max_len=40)
+            description = truncate_string(
+                str(param_info.get("description", "")), max_len=40
+            )
 
             row = f"{param_name:28} | {param_type:17} | {required:8} | {default_str:16} | {user_default_str:16} | {description}"
             rows.append(row)
diff --git a/mcp_servers/hummingbot_api/formatters/gateway.py b/mcp_servers/hummingbot_api/formatters/gateway.py
index 75c20420..230e3050 100644
--- a/mcp_servers/hummingbot_api/formatters/gateway.py
+++ b/mcp_servers/hummingbot_api/formatters/gateway.py
@@ -1,6 +1,7 @@
 """
 Gateway formatters for the Hummingbot MCP server.
 """
+
 from typing import Any
 
 
@@ -11,8 +12,8 @@ def format_gateway_container_result(result: dict[str, Any]) -> str:
     if result_action == "get_status":
         status = result.get("status", {})
         running = status.get("running", False)
-        container_id = status.get('container_id')
-        created_at = status.get('created_at')
+        container_id = status.get("container_id")
+        created_at = status.get("created_at")
 
         container_id_display = f"{container_id[:12]}..." if container_id else "None"
         created_at_display = created_at[:19] if created_at else "None"
@@ -198,7 +199,12 @@ def format_amm_result(action: str, result: dict[str, Any]) -> str:
     if action in ("quote_swap", "quote_liquidity") and isinstance(payload, dict):
         return f"{header}\n{payload}"
 
-    if action in ("execute_swap", "add_liquidity", "remove_liquidity", "create_pool") and isinstance(payload, dict):
+    if action in (
+        "execute_swap",
+        "add_liquidity",
+        "remove_liquidity",
+        "create_pool",
+    ) and isinstance(payload, dict):
         sig = payload.get("signature")
         extra = ""
         if action == "create_pool":
diff --git a/mcp_servers/hummingbot_api/formatters/market_data.py b/mcp_servers/hummingbot_api/formatters/market_data.py
index ce2bf3ed..ca2fc230 100644
--- a/mcp_servers/hummingbot_api/formatters/market_data.py
+++ b/mcp_servers/hummingbot_api/formatters/market_data.py
@@ -4,6 +4,7 @@
 This module provides table formatters for market data including
 prices, OHLCV candles, and order book snapshots.
 """
+
 from typing import Any
 
 from .base import (
diff --git a/mcp_servers/hummingbot_api/formatters/portfolio.py b/mcp_servers/hummingbot_api/formatters/portfolio.py
index d4afb3dd..34c6242f 100644
--- a/mcp_servers/hummingbot_api/formatters/portfolio.py
+++ b/mcp_servers/hummingbot_api/formatters/portfolio.py
@@ -3,6 +3,7 @@
 
 This module provides table formatters for portfolio balances and holdings.
 """
+
 from typing import Any
 
 from .base import format_number, format_table_separator, get_field
@@ -49,9 +50,17 @@ def format_portfolio_as_table(portfolio_data: dict[str, Any]) -> str:
             for balance in balances:
                 token = str(get_field(balance, "token", default="N/A"))[:8]
                 connector = connector_name[:17]
-                total = format_number(get_field(balance, "units", default=None), decimals=4, compact=True)
-                available = format_number(get_field(balance, "available_units", default=None), decimals=4, compact=True)
-                value_usd = format_number(get_field(balance, "value", default=None), decimals=2, compact=True)
+                total = format_number(
+                    get_field(balance, "units", default=None), decimals=4, compact=True
+                )
+                available = format_number(
+                    get_field(balance, "available_units", default=None),
+                    decimals=4,
+                    compact=True,
+                )
+                value_usd = format_number(
+                    get_field(balance, "value", default=None), decimals=2, compact=True
+                )
 
                 row = f"{token:8} | {connector:17} | {total:12} | {available:12} | {value_usd}"
                 rows.append(row)
diff --git a/mcp_servers/hummingbot_api/formatters/table_builder.py b/mcp_servers/hummingbot_api/formatters/table_builder.py
index af7eb7d3..49384304 100644
--- a/mcp_servers/hummingbot_api/formatters/table_builder.py
+++ b/mcp_servers/hummingbot_api/formatters/table_builder.py
@@ -4,6 +4,7 @@
 This module provides the TableBuilder class and ColumnDef dataclass that standardize
 table creation, reducing code duplication across all formatters.
 """
+
 from dataclasses import dataclass, field
 from typing import Any, Callable
 
@@ -100,7 +101,11 @@ def format_cell(self, item: dict[str, Any]) -> str:
 
         # Truncate if too long
         if len(value) > self.width:
-            value = value[:self.width - 3] + "..." if self.width > 3 else value[:self.width]
+            value = (
+                value[: self.width - 3] + "..."
+                if self.width > 3
+                else value[: self.width]
+            )
 
         # Apply alignment
         if self.align == "right":
@@ -143,7 +148,7 @@ def __init__(
         columns: list[ColumnDef],
         separator_char: str = "-",
         column_separator: str = " | ",
-        empty_message: str = "No data found."
+        empty_message: str = "No data found.",
     ):
         """
         Initialize the table builder.
@@ -171,7 +176,7 @@ def _build_header(self) -> str:
         for col in self.columns:
             header = col.name
             if len(header) > col.width:
-                header = header[:col.width]
+                header = header[: col.width]
             cells.append(header.ljust(col.width))
         return self.column_separator.join(cells)
 
@@ -180,7 +185,9 @@ def _build_row(self, item: dict[str, Any]) -> str:
         cells = [col.format_cell(item) for col in self.columns]
         return self.column_separator.join(cells)
 
-    def build(self, data: list[dict[str, Any]], empty_message: str | None = None) -> str:
+    def build(
+        self, data: list[dict[str, Any]], empty_message: str | None = None
+    ) -> str:
         """
         Build the complete table string.
 
@@ -201,10 +208,7 @@ def build(self, data: list[dict[str, Any]], empty_message: str | None = None) ->
         return f"{header}\n{separator}\n" + "\n".join(rows)
 
     def build_with_title(
-        self,
-        data: list[dict[str, Any]],
-        title: str,
-        empty_message: str | None = None
+        self, data: list[dict[str, Any]], title: str, empty_message: str | None = None
     ) -> str:
         """
         Build table with a title above it.
@@ -226,7 +230,7 @@ def build_with_title(
 def create_simple_table(
     data: list[dict[str, Any]],
     column_config: list[tuple[str, str, int]],
-    empty_message: str = "No data found."
+    empty_message: str = "No data found.",
 ) -> str:
     """
     Convenience function to create a simple table without defining ColumnDef objects.
@@ -248,6 +252,8 @@ def create_simple_table(
         Alice      | 30
         Bob        | 25
     """
-    columns = [ColumnDef(name=name, key=key, width=width) for name, key, width in column_config]
+    columns = [
+        ColumnDef(name=name, key=key, width=width) for name, key, width in column_config
+    ]
     builder = TableBuilder(columns, empty_message=empty_message)
     return builder.build(data)
diff --git a/mcp_servers/hummingbot_api/formatters/trading.py b/mcp_servers/hummingbot_api/formatters/trading.py
index 704cceca..ab0ddd68 100644
--- a/mcp_servers/hummingbot_api/formatters/trading.py
+++ b/mcp_servers/hummingbot_api/formatters/trading.py
@@ -4,6 +4,7 @@
 This module provides table formatters for trading data including
 orders and positions.
 """
+
 from typing import Any
 
 from .base import format_number, get_field, get_timestamp_field
@@ -26,7 +27,9 @@ def format_orders_as_table(orders: list[dict[str, Any]]) -> str:
         return "No orders found."
 
     def format_time(item: dict) -> str:
-        return get_timestamp_field(item, "created_at", "creation_timestamp", "timestamp")
+        return get_timestamp_field(
+            item, "created_at", "creation_timestamp", "timestamp"
+        )
 
     def format_pair(item: dict) -> str:
         return str(get_field(item, "trading_pair", default="N/A"))[:12]
@@ -38,13 +41,18 @@ def format_type(item: dict) -> str:
         return str(get_field(item, "order_type", "type", default="N/A"))[:6]
 
     def format_amount(item: dict) -> str:
-        return format_number(get_field(item, "amount", "order_size", default=None), compact=False)
+        return format_number(
+            get_field(item, "amount", "order_size", default=None), compact=False
+        )
 
     def format_price(item: dict) -> str:
         return format_number(get_field(item, "price", default=None), compact=False)
 
     def format_filled(item: dict) -> str:
-        return format_number(get_field(item, "filled_amount", "executed_amount_base", default=None), compact=False)
+        return format_number(
+            get_field(item, "filled_amount", "executed_amount_base", default=None),
+            compact=False,
+        )
 
     def format_status(item: dict) -> str:
         return str(get_field(item, "status", default="N/A"))[:8]
@@ -106,16 +114,24 @@ def format_side(item: dict) -> str:
         return str(get_field(item, "position_side", "side", default="N/A"))[:5]
 
     def format_amount(item: dict) -> str:
-        return format_number(get_field(item, "amount", "position_size", default=None), compact=False)
+        return format_number(
+            get_field(item, "amount", "position_size", default=None), compact=False
+        )
 
     def format_entry(item: dict) -> str:
-        return format_number(get_field(item, "entry_price", default=None), compact=False)
+        return format_number(
+            get_field(item, "entry_price", default=None), compact=False
+        )
 
     def format_current(item: dict) -> str:
-        return format_number(get_field(item, "current_price", "mark_price", default=None), compact=False)
+        return format_number(
+            get_field(item, "current_price", "mark_price", default=None), compact=False
+        )
 
     def format_pnl(item: dict) -> str:
-        return format_number(get_field(item, "unrealized_pnl", default=None), compact=False)
+        return format_number(
+            get_field(item, "unrealized_pnl", default=None), compact=False
+        )
 
     def format_leverage(item: dict) -> str:
         return str(get_field(item, "leverage", default="N/A"))
diff --git a/mcp_servers/hummingbot_api/hummingbot_client.py b/mcp_servers/hummingbot_api/hummingbot_client.py
index a371c6d5..3c04f4ba 100644
--- a/mcp_servers/hummingbot_api/hummingbot_client.py
+++ b/mcp_servers/hummingbot_api/hummingbot_client.py
@@ -56,7 +56,9 @@ async def initialize(self, force: bool = False) -> HummingbotAPIClient:
                 await self._client.accounts.list_accounts()
 
                 self._initialized = True
-                logger.info(f"Successfully connected to Hummingbot API at {settings.api_url}")
+                logger.info(
+                    f"Successfully connected to Hummingbot API at {settings.api_url}"
+                )
                 return self._client
 
             except Exception as e:
@@ -65,7 +67,11 @@ async def initialize(self, force: bool = False) -> HummingbotAPIClient:
                 logger.warning(f"Connection attempt {attempt + 1} failed: {e}")
 
                 # Don't retry on authentication errors
-                if "401" in error_str or "unauthorized" in error_str or "authentication" in error_str:
+                if (
+                    "401" in error_str
+                    or "unauthorized" in error_str
+                    or "authentication" in error_str
+                ):
                     self._failed_url = settings.api_url
                     self._last_error = MaxConnectionsAttemptError(
                         f"❌ Authentication failed when connecting to Hummingbot API at {settings.api_url}\n\n"
@@ -87,7 +93,12 @@ async def initialize(self, force: bool = False) -> HummingbotAPIClient:
         self._failed_url = settings.api_url
         error_str = str(last_error).lower() if last_error else ""
 
-        if "connection" in error_str or "refused" in error_str or "unreachable" in error_str or "timeout" in error_str:
+        if (
+            "connection" in error_str
+            or "refused" in error_str
+            or "unreachable" in error_str
+            or "timeout" in error_str
+        ):
             error_message = (
                 f"❌ Cannot reach Hummingbot API at {settings.api_url}\n\n"
                 f"The API server is not responding. This usually means:\n"
@@ -101,7 +112,10 @@ async def initialize(self, force: bool = False) -> HummingbotAPIClient:
             )
 
             # Add Docker networking warning for localhost URLs
-            if "localhost" in settings.api_url and os.getenv("DOCKER_CONTAINER") == "true":
+            if (
+                "localhost" in settings.api_url
+                and os.getenv("DOCKER_CONTAINER") == "true"
+            ):
                 system = platform.system()
                 if system in ["Darwin", "Windows"]:
                     error_message += (
diff --git a/mcp_servers/hummingbot_api/middleware.py b/mcp_servers/hummingbot_api/middleware.py
index ff8be8c8..8fe5726a 100644
--- a/mcp_servers/hummingbot_api/middleware.py
+++ b/mcp_servers/hummingbot_api/middleware.py
@@ -1,11 +1,15 @@
 """
 Middleware decorators for common tool patterns.
 """
+
 import functools
 import logging
 from typing import Any, Callable, Coroutine, TypeVar
 
-from mcp_servers.hummingbot_api.exceptions import MaxConnectionsAttemptError as HBConnectionError, ToolError
+from mcp_servers.hummingbot_api.exceptions import (
+    MaxConnectionsAttemptError as HBConnectionError,
+)
+from mcp_servers.hummingbot_api.exceptions import ToolError
 
 logger = logging.getLogger("hummingbot-mcp")
 
@@ -17,7 +21,9 @@
 def handle_errors(
     action_name: str,
     error_suffix: str = "",
-) -> Callable[[Callable[..., Coroutine[Any, Any, T]]], Callable[..., Coroutine[Any, Any, T]]]:
+) -> Callable[
+    [Callable[..., Coroutine[Any, Any, T]]], Callable[..., Coroutine[Any, Any, T]]
+]:
     """
     Decorator for standardized error handling in tool functions.
 
@@ -28,7 +34,10 @@ def handle_errors(
         action_name: Description of the action for error messages (e.g., "get prices")
         error_suffix: Optional string appended to error messages (e.g., GATEWAY_LOG_HINT)
     """
-    def decorator(func: Callable[..., Coroutine[Any, Any, T]]) -> Callable[..., Coroutine[Any, Any, T]]:
+
+    def decorator(
+        func: Callable[..., Coroutine[Any, Any, T]]
+    ) -> Callable[..., Coroutine[Any, Any, T]]:
         @functools.wraps(func)
         async def wrapper(*args: Any, **kwargs: Any) -> T:
             try:
@@ -40,5 +49,7 @@ async def wrapper(*args: Any, **kwargs: Any) -> T:
             except Exception as e:
                 logger.error(f"{action_name} failed: {str(e)}", exc_info=True)
                 raise ToolError(f"Failed to {action_name}: {str(e)}{error_suffix}")
+
         return wrapper
+
     return decorator
diff --git a/mcp_servers/hummingbot_api/schemas.py b/mcp_servers/hummingbot_api/schemas.py
index edcb26aa..917dddba 100644
--- a/mcp_servers/hummingbot_api/schemas.py
+++ b/mcp_servers/hummingbot_api/schemas.py
@@ -598,7 +598,10 @@ class AMMRequest(BaseModel):
             "create_pool",
         ]
         | None
-    ) = Field(default=None, description="AMM action. Leave empty to load the AMM guide + param matrix.")
+    ) = Field(
+        default=None,
+        description="AMM action. Leave empty to load the AMM guide + param matrix.",
+    )
 
     connector: str | None = Field(
         default=None,
@@ -608,7 +611,10 @@ class AMMRequest(BaseModel):
         default=None,
         description="Network ID in 'chain-network' format. Examples: 'solana-mainnet-beta', 'ethereum-mainnet', 'base-mainnet'",
     )
-    wallet_address: str | None = Field(default=None, description="Wallet address (optional, uses default if not provided)")
+    wallet_address: str | None = Field(
+        default=None,
+        description="Wallet address (optional, uses default if not provided)",
+    )
     pool_address: str | None = Field(default=None, description="Pool contract address")
     position_address: str | None = Field(
         default=None,
@@ -616,20 +622,55 @@ class AMMRequest(BaseModel):
     )
 
     # Swap params
-    base_token: str | None = Field(default=None, description="Base token symbol or address (swap direction / pool base)")
-    quote_token: str | None = Field(default=None, description="Quote token symbol or address (pool quote, for create_pool)")
-    amount: str | None = Field(default=None, description="Swap amount (as string; parsed to Decimal)")
-    side: Literal["BUY", "SELL"] | None = Field(default=None, description="Swap direction")
-    slippage_pct: str | None = Field(default=None, description="Maximum slippage percentage (as string)")
+    base_token: str | None = Field(
+        default=None,
+        description="Base token symbol or address (swap direction / pool base)",
+    )
+    quote_token: str | None = Field(
+        default=None,
+        description="Quote token symbol or address (pool quote, for create_pool)",
+    )
+    amount: str | None = Field(
+        default=None, description="Swap amount (as string; parsed to Decimal)"
+    )
+    side: Literal["BUY", "SELL"] | None = Field(
+        default=None, description="Swap direction"
+    )
+    slippage_pct: str | None = Field(
+        default=None, description="Maximum slippage percentage (as string)"
+    )
 
     # Liquidity params
-    base_token_amount: str | None = Field(default=None, description="Base token amount (add_liquidity / quote_liquidity / create_pool)")
-    quote_token_amount: str | None = Field(default=None, description="Quote token amount (add_liquidity / quote_liquidity / create_pool)")
-    percentage_to_remove: str | None = Field(default=None, description="Percentage of liquidity to remove, 0-100 (remove_liquidity)")
+    base_token_amount: str | None = Field(
+        default=None,
+        description="Base token amount (add_liquidity / quote_liquidity / create_pool)",
+    )
+    quote_token_amount: str | None = Field(
+        default=None,
+        description="Quote token amount (add_liquidity / quote_liquidity / create_pool)",
+    )
+    percentage_to_remove: str | None = Field(
+        default=None,
+        description="Percentage of liquidity to remove, 0-100 (remove_liquidity)",
+    )
 
     # create_pool params
-    initial_price: str | None = Field(default=None, description="Initial price as quote per base (create_pool; overrides quote_token_amount)")
-    config_address: str | None = Field(default=None, description="Meteora DAMM v2 config account address (required for meteora create_pool)")
-    fee_config_index: int | None = Field(default=None, description="Raydium CPMM fee config index (optional, create_pool)")
-    gas_price: str | None = Field(default=None, description="Uniswap (EVM) gas price in gwei (optional, create_pool)")
-    max_gas: int | None = Field(default=None, description="Uniswap (EVM) max gas limit (optional, create_pool)")
+    initial_price: str | None = Field(
+        default=None,
+        description="Initial price as quote per base (create_pool; overrides quote_token_amount)",
+    )
+    config_address: str | None = Field(
+        default=None,
+        description="Meteora DAMM v2 config account address (required for meteora create_pool)",
+    )
+    fee_config_index: int | None = Field(
+        default=None,
+        description="Raydium CPMM fee config index (optional, create_pool)",
+    )
+    gas_price: str | None = Field(
+        default=None,
+        description="Uniswap (EVM) gas price in gwei (optional, create_pool)",
+    )
+    max_gas: int | None = Field(
+        default=None, description="Uniswap (EVM) max gas limit (optional, create_pool)"
+    )
diff --git a/mcp_servers/hummingbot_api/server.py b/mcp_servers/hummingbot_api/server.py
index e9f1f077..3c71eea7 100644
--- a/mcp_servers/hummingbot_api/server.py
+++ b/mcp_servers/hummingbot_api/server.py
@@ -46,9 +46,7 @@
 from mcp_servers.hummingbot_api.tools.gateway import (
     manage_gateway_container as manage_gateway_container_impl,
 )
-from mcp_servers.hummingbot_api.tools.gateway_amm import (
-    manage_amm_impl,
-)
+from mcp_servers.hummingbot_api.tools.gateway_amm import manage_amm_impl
 from mcp_servers.hummingbot_api.tools.gateway_clmm import (
     explore_gateway_clmm_pools as explore_gateway_clmm_pools_impl,
 )
diff --git a/mcp_servers/hummingbot_api/tools/bot_management.py b/mcp_servers/hummingbot_api/tools/bot_management.py
index 4606c802..b2ff3a7b 100644
--- a/mcp_servers/hummingbot_api/tools/bot_management.py
+++ b/mcp_servers/hummingbot_api/tools/bot_management.py
@@ -4,13 +4,19 @@
 This module provides the core business logic for managing bots, including
 status retrieval, log management, and execution control.
 """
+
 import asyncio
 from typing import Any, Literal
 
-from mcp_servers.hummingbot_api.formatters import format_active_bots_as_table, format_bot_logs_as_table
+from mcp_servers.hummingbot_api.formatters import (
+    format_active_bots_as_table,
+    format_bot_logs_as_table,
+)
 
 
-async def _get_controller_configs_map(client: Any, bot_name: str) -> dict[str, dict[str, Any]]:
+async def _get_controller_configs_map(
+    client: Any, bot_name: str
+) -> dict[str, dict[str, Any]]:
     """
     Fetch a bot's controller configs keyed by both config id and config file name.
 
@@ -58,7 +64,9 @@ async def get_active_bots_status(client: Any) -> dict[str, Any]:
     bots_table = format_active_bots_as_table(active_bots)
 
     # Count total bots
-    total_bots = len(active_bots.get("data", {})) if isinstance(active_bots, dict) else 0
+    total_bots = (
+        len(active_bots.get("data", {})) if isinstance(active_bots, dict) else 0
+    )
 
     return {
         "active_bots": active_bots,
@@ -97,7 +105,9 @@ async def _attach_kill_switches(client: Any, bots: dict[str, Any]) -> None:
                 continue
             config = configs.get(str(controller_id))
             if config is not None:
-                controller_data["kill_switch"] = bool(config.get("manual_kill_switch", False))
+                controller_data["kill_switch"] = bool(
+                    config.get("manual_kill_switch", False)
+                )
 
 
 async def get_bot_logs(
@@ -150,7 +160,10 @@ async def get_bot_logs(
     if log_type in ["error", "all"] and "error_logs" in bot_data:
         error_logs = bot_data["error_logs"]
         for log_entry in error_logs:
-            if search_term is None or search_term.lower() in log_entry.get("msg", "").lower():
+            if (
+                search_term is None
+                or search_term.lower() in log_entry.get("msg", "").lower()
+            ):
                 log_entry["log_category"] = "error"
                 logs.append(log_entry)
 
@@ -158,7 +171,10 @@ async def get_bot_logs(
     if log_type in ["general", "all"] and "general_logs" in bot_data:
         general_logs = bot_data["general_logs"]
         for log_entry in general_logs:
-            if search_term is None or search_term.lower() in log_entry.get("msg", "").lower():
+            if (
+                search_term is None
+                or search_term.lower() in log_entry.get("msg", "").lower()
+            ):
                 log_entry["log_category"] = "general"
                 logs.append(log_entry)
 
@@ -281,9 +297,13 @@ async def _set_kill_switches(
         updated_configs = {}
     for name in succeeded:
         config = updated_configs.get(name) or updated_configs.get(targets[name])
-        confirmed[name] = bool(config.get("manual_kill_switch", False)) if config else None
+        confirmed[name] = (
+            bool(config.get("manual_kill_switch", False)) if config else None
+        )
 
-    unconfirmed = [name for name, value in confirmed.items() if value is not kill_switch]
+    unconfirmed = [
+        name for name, value in confirmed.items() if value is not kill_switch
+    ]
 
     verified = [name for name in succeeded if name not in unconfirmed]
     message = (
@@ -364,10 +384,14 @@ async def update_bot_controller_config(
     config_controller_name = config_data.get("controller_name")
 
     if not config_controller_type or not config_controller_name:
-        raise ValueError("config_data must include 'controller_type' and 'controller_name'")
+        raise ValueError(
+            "config_data must include 'controller_type' and 'controller_name'"
+        )
 
     # Validate config first
-    await client.controllers.validate_controller_config(config_controller_type, config_controller_name, config_data)
+    await client.controllers.validate_controller_config(
+        config_controller_type, config_controller_name, config_data
+    )
 
     if not confirm_override:
         current_configs = await client.controllers.get_bot_controller_configs(bot_name)
@@ -379,12 +403,16 @@ async def update_bot_controller_config(
                 "config_name": config_name,
                 "bot_name": bot_name,
                 "current_config": config,
-                "message": (f"Config '{config_name}' already exists in bot '{bot_name}' with data: {config}. "
-                           "Set confirm_override=True to update it."),
+                "message": (
+                    f"Config '{config_name}' already exists in bot '{bot_name}' with data: {config}. "
+                    "Set confirm_override=True to update it."
+                ),
             }
         else:
             clean_data = {k: v for k, v in config_data.items() if not k.startswith("_")}
-            update_op = await client.controllers.update_bot_controller_config(bot_name, config_name, clean_data)
+            update_op = await client.controllers.update_bot_controller_config(
+                bot_name, config_name, clean_data
+            )
             return {
                 "action": "update_config",
                 "exists": False,
@@ -398,7 +426,9 @@ async def update_bot_controller_config(
         if "id" not in config_data or config_data["id"] != config_name:
             config_data["id"] = config_name
         clean_data = {k: v for k, v in config_data.items() if not k.startswith("_")}
-        update_op = await client.controllers.update_bot_controller_config(bot_name, config_name, clean_data)
+        update_op = await client.controllers.update_bot_controller_config(
+            bot_name, config_name, clean_data
+        )
         return {
             "action": "update_config",
             "exists": True,
diff --git a/mcp_servers/hummingbot_api/tools/controllers.py b/mcp_servers/hummingbot_api/tools/controllers.py
index 3b11c6c0..903408b8 100644
--- a/mcp_servers/hummingbot_api/tools/controllers.py
+++ b/mcp_servers/hummingbot_api/tools/controllers.py
@@ -4,10 +4,17 @@
 This module provides the core business logic for managing controllers and their
 configurations, including exploration, modification, and bot deployment.
 """
+
 from typing import Any, Literal
 
 # Internal/auto-managed fields that should be skipped during schema validation
-_SKIP_FIELDS = {"id", "controller_name", "controller_type", "candles_config", "initial_positions"}
+_SKIP_FIELDS = {
+    "id",
+    "controller_name",
+    "controller_type",
+    "candles_config",
+    "initial_positions",
+}
 
 
 def _validate_config_against_template(
@@ -47,7 +54,8 @@ def _validate_config_against_template(
     if missing_fields:
         raise ValueError(
             "Config validation failed against controller template schema.\n\n"
-            "Missing required fields (no default value in schema):\n" + "\n".join(missing_fields)
+            "Missing required fields (no default value in schema):\n"
+            + "\n".join(missing_fields)
             + "\n\nUse manage_controllers(action='describe', controller_name='"
             + str(config_data.get("controller_name", "..."))
             + "') to see all available parameters and their defaults."
@@ -66,7 +74,9 @@ async def manage_controllers(
     client: Any,
     action: Literal["list", "describe", "upsert", "delete"],
     target: Literal["controller", "config"] | None = None,
-    controller_type: Literal["directional_trading", "market_making", "generic"] | None = None,
+    controller_type: (
+        Literal["directional_trading", "market_making", "generic"] | None
+    ) = None,
     controller_name: str | None = None,
     controller_code: str | None = None,
     config_name: str | None = None,
@@ -93,7 +103,9 @@ async def manage_controllers(
         )
     elif action in ("upsert", "delete"):
         if not target:
-            raise ValueError("'target' parameter ('controller' or 'config') is required for upsert/delete actions")
+            raise ValueError(
+                "'target' parameter ('controller' or 'config') is required for upsert/delete actions"
+            )
         return await modify_controllers(
             client=client,
             action=action,
@@ -106,13 +118,17 @@ async def manage_controllers(
             confirm_override=confirm_override,
         )
     else:
-        raise ValueError(f"Invalid action '{action}'. Use 'list', 'describe', 'upsert', or 'delete'.")
+        raise ValueError(
+            f"Invalid action '{action}'. Use 'list', 'describe', 'upsert', or 'delete'."
+        )
 
 
 async def explore_controllers(
     client: Any,
     action: Literal["list", "describe"],
-    controller_type: Literal["directional_trading", "market_making", "generic"] | None = None,
+    controller_type: (
+        Literal["directional_trading", "market_making", "generic"] | None
+    ) = None,
     controller_name: str | None = None,
     config_name: str | None = None,
     include_code: bool = False,
@@ -142,7 +158,9 @@ async def explore_controllers(
                 continue
             result += f"Controller Type: {c_type}\n"
             for controller in controller_list:
-                controller_configs = [c for c in configs if c.get('controller_name') == controller]
+                controller_configs = [
+                    c for c in configs if c.get("controller_name") == controller
+                ]
                 result += f"- {controller} ({len(controller_configs)} configs)\n"
                 if len(controller_configs) > 0:
                     for config in controller_configs:
@@ -195,15 +213,21 @@ async def explore_controllers(
             }
 
         # Get config template (lightweight — just parameter schema)
-        controller_configs = [c.get("id") for c in configs if c.get('controller_name') == controller_name]
-        template = await client.controllers.get_controller_config_template(found_controller_type, controller_name)
+        controller_configs = [
+            c.get("id") for c in configs if c.get("controller_name") == controller_name
+        ]
+        template = await client.controllers.get_controller_config_template(
+            found_controller_type, controller_name
+        )
 
         result += f"Controller: {controller_name} ({found_controller_type})\n\n"
 
         # Only fetch and include full source code when explicitly requested
         controller_code_content = None
         if include_code:
-            controller_code_content = await client.controllers.get_controller(found_controller_type, controller_name)
+            controller_code_content = await client.controllers.get_controller(
+                found_controller_type, controller_name
+            )
             result += f"Controller Code:\n{controller_code_content}\n\n"
 
         # Format config template parameters as table
@@ -212,15 +236,25 @@ async def explore_controllers(
         result += "-" * 80 + "\n"
 
         for param_name, param_info in template.items():
-            if param_name in ['id', 'controller_name', 'controller_type', 'candles_config', 'initial_positions']:
+            if param_name in [
+                "id",
+                "controller_name",
+                "controller_type",
+                "candles_config",
+                "initial_positions",
+            ]:
                 continue  # Skip internal fields
 
-            param_type = str(param_info.get('type', 'unknown'))
+            param_type = str(param_info.get("type", "unknown"))
             # Simplify type names
-            param_type = param_type.replace("<class '", "").replace("'>", "").replace("decimal.Decimal", "Decimal")
+            param_type = (
+                param_type.replace("<class '", "")
+                .replace("'>", "")
+                .replace("decimal.Decimal", "Decimal")
+            )
             param_type = param_type.replace("typing.", "").split(".")[-1][:15]
 
-            default = str(param_info.get('default', 'None'))
+            default = str(param_info.get("default", "None"))
             if len(default) > 30:
                 default = default[:27] + "..."
 
@@ -231,14 +265,20 @@ async def explore_controllers(
         # Format configs list
         result += f"Total Configs: {len(controller_configs)}\n"
         if len(controller_configs) <= 10:
-            result += "Configs:\n" + "\n".join(f"  - {c}" for c in controller_configs if c) + "\n"
+            result += (
+                "Configs:\n"
+                + "\n".join(f"  - {c}" for c in controller_configs if c)
+                + "\n"
+            )
         else:
             result += f"Configs (showing first 10 of {len(controller_configs)}):\n"
             result += "\n".join(f"  - {c}" for c in controller_configs[:10] if c) + "\n"
             result += f"  ... and {len(controller_configs) - 10} more\n"
 
         if not include_code:
-            result += "\nTip: Set include_code=True to see the full controller source code.\n"
+            result += (
+                "\nTip: Set include_code=True to see the full controller source code.\n"
+            )
 
         return_data = {
             "action": "describe",
@@ -265,7 +305,9 @@ async def modify_controllers(
     client: Any,
     action: Literal["upsert", "delete"],
     target: Literal["controller", "config"],
-    controller_type: Literal["directional_trading", "market_making", "generic"] | None = None,
+    controller_type: (
+        Literal["directional_trading", "market_making", "generic"] | None
+    ) = None,
     controller_name: str | None = None,
     controller_code: str | None = None,
     config_name: str | None = None,
@@ -297,14 +339,18 @@ async def modify_controllers(
     if target == "controller":
         if action == "upsert":
             if not controller_type or not controller_name or not controller_code:
-                raise ValueError("controller_type, controller_name, and controller_code are required for controller upsert")
+                raise ValueError(
+                    "controller_type, controller_name, and controller_code are required for controller upsert"
+                )
 
             # Check if controller exists
             controllers = await client.controllers.list_controllers()
             exists = controller_name in controllers.get(controller_type, [])
 
             if exists and not confirm_override:
-                existing_code = await client.controllers.get_controller(controller_type, controller_name)
+                existing_code = await client.controllers.get_controller(
+                    controller_type, controller_name
+                )
                 return {
                     "action": "upsert",
                     "target": "controller",
@@ -312,15 +358,19 @@ async def modify_controllers(
                     "controller_name": controller_name,
                     "controller_type": controller_type,
                     "current_code": existing_code,
-                    "message": (f"Controller '{controller_name}' already exists and this is the current code: {existing_code}. "
-                               f"Set confirm_override=True to update it."),
+                    "message": (
+                        f"Controller '{controller_name}' already exists and this is the current code: {existing_code}. "
+                        f"Set confirm_override=True to update it."
+                    ),
                 }
 
             # POST /controllers/{type}/{name} expects a Controller body -- an OBJECT with a
             # "content" field -- not a bare source string. Passing the string through made
             # FastAPI reject the body with 422 for every controller upload.
             result = await client.controllers.create_or_update_controller(
-                controller_type, controller_name, {"content": controller_code, "type": controller_type}
+                controller_type,
+                controller_name,
+                {"content": controller_code, "type": controller_type},
             )
 
             return {
@@ -335,9 +385,13 @@ async def modify_controllers(
 
         elif action == "delete":
             if not controller_type or not controller_name:
-                raise ValueError("controller_type and controller_name are required for controller delete")
+                raise ValueError(
+                    "controller_type and controller_name are required for controller delete"
+                )
 
-            result = await client.controllers.delete_controller(controller_type, controller_name)
+            result = await client.controllers.delete_controller(
+                controller_type, controller_name
+            )
 
             return {
                 "action": "delete",
@@ -351,14 +405,18 @@ async def modify_controllers(
     elif target == "config":
         if action == "upsert":
             if not config_name or not config_data:
-                raise ValueError("config_name and config_data are required for config upsert")
+                raise ValueError(
+                    "config_name and config_data are required for config upsert"
+                )
 
             # Extract controller_type and controller_name from config_data
             config_controller_type = config_data.get("controller_type")
             config_controller_name = config_data.get("controller_name")
 
             if not config_controller_type or not config_controller_name:
-                raise ValueError("config_data must include 'controller_type' and 'controller_name'")
+                raise ValueError(
+                    "config_data must include 'controller_type' and 'controller_name'"
+                )
 
             # Always set the config id to match the config name (file name), so the
             # backend gets a complete config for validation and storage.
@@ -372,26 +430,34 @@ async def modify_controllers(
             _validate_config_against_template(config_data, template)
 
             # Validate config with backend
-            await client.controllers.validate_controller_config(config_controller_type, config_controller_name, config_data)
+            await client.controllers.validate_controller_config(
+                config_controller_type, config_controller_name, config_data
+            )
 
             controller_configs = await client.controllers.list_controller_configs()
             exists = config_name in [c.get("id") for c in controller_configs]
 
             if exists and not confirm_override:
-                existing_config = await client.controllers.get_controller_config(config_name)
+                existing_config = await client.controllers.get_controller_config(
+                    config_name
+                )
                 return {
                     "action": "upsert",
                     "target": "config",
                     "exists": True,
                     "config_name": config_name,
                     "current_config": existing_config,
-                    "message": (f"Config '{config_name}' already exists with data: {existing_config}. "
-                               "Set confirm_override=True to update it."),
+                    "message": (
+                        f"Config '{config_name}' already exists with data: {existing_config}. "
+                        "Set confirm_override=True to update it."
+                    ),
                 }
 
             # Strip internal fields like _config_name that cause Pydantic validation errors
             clean_data = {k: v for k, v in config_data.items() if not k.startswith("_")}
-            result = await client.controllers.create_or_update_controller_config(config_name, clean_data)
+            result = await client.controllers.create_or_update_controller_config(
+                config_name, clean_data
+            )
             return {
                 "action": "upsert",
                 "target": "config",
diff --git a/mcp_servers/hummingbot_api/tools/executors.py b/mcp_servers/hummingbot_api/tools/executors.py
index fe99b3a4..fc43d135 100644
--- a/mcp_servers/hummingbot_api/tools/executors.py
+++ b/mcp_servers/hummingbot_api/tools/executors.py
@@ -4,6 +4,7 @@
 This module provides business logic for managing trading executors including
 creation, viewing, stopping, and position management with progressive disclosure.
 """
+
 import logging
 from typing import Any
 
@@ -23,7 +24,9 @@
 _INTERNAL_FIELDS = {"type", "executor_type", "id"}
 
 
-def validate_executor_config(config: dict[str, Any], schema: dict[str, Any]) -> list[str]:
+def validate_executor_config(
+    config: dict[str, Any], schema: dict[str, Any]
+) -> list[str]:
     """Validate config keys against the backend schema properties.
 
     Returns a list of error strings. An empty list means the config is valid.
@@ -33,7 +36,9 @@ def validate_executor_config(config: dict[str, Any], schema: dict[str, Any]) ->
     return errors
 
 
-def _validate_level(config: dict[str, Any], schema: dict[str, Any], path: str, errors: list[str]) -> None:
+def _validate_level(
+    config: dict[str, Any], schema: dict[str, Any], path: str, errors: list[str]
+) -> None:
     """Recursively validate config keys against schema properties."""
     properties = schema.get("properties", {})
     if not properties:
@@ -47,15 +52,23 @@ def _validate_level(config: dict[str, Any], schema: dict[str, Any], path: str, e
         if key not in allowed:
             field_list = ", ".join(sorted(allowed - _INTERNAL_FIELDS))
             location = f" inside '{path}'" if path else ""
-            errors.append(f"Unknown field '{key}'{location}. Allowed fields: {field_list}")
+            errors.append(
+                f"Unknown field '{key}'{location}. Allowed fields: {field_list}"
+            )
             continue
         # Recurse into nested objects
         prop_schema = properties[key]
-        if isinstance(prop_schema, dict) and isinstance(config[key], dict) and "properties" in prop_schema:
+        if (
+            isinstance(prop_schema, dict)
+            and isinstance(config[key], dict)
+            and "properties" in prop_schema
+        ):
             _validate_level(config[key], prop_schema, key, errors)
 
 
-async def manage_executors(client: Any, request: ManageExecutorsRequest) -> dict[str, Any]:
+async def manage_executors(
+    client: Any, request: ManageExecutorsRequest
+) -> dict[str, Any]:
     """
     Manage executors with progressive disclosure.
 
@@ -90,7 +103,9 @@ async def manage_executors(client: Any, request: ManageExecutorsRequest) -> dict
     elif flow_stage == "show_schema":
         # Stage 2: Show config schema with user defaults
         try:
-            schema = await client.executors.get_executor_config_schema(request.executor_type)
+            schema = await client.executors.get_executor_config_schema(
+                request.executor_type
+            )
         except Exception as e:
             return {
                 "action": "show_schema",
@@ -114,7 +129,9 @@ async def manage_executors(client: Any, request: ManageExecutorsRequest) -> dict
             formatted += f"\n\nYour saved defaults for {request.executor_type}:\n"
             for key, value in user_defaults.items():
                 formatted += f"  {key}: {value}\n"
-            formatted += f"\nPreferences file: {executor_preferences.get_preferences_path()}"
+            formatted += (
+                f"\nPreferences file: {executor_preferences.get_preferences_path()}"
+            )
 
         return {
             "action": "show_schema",
@@ -128,7 +145,11 @@ async def manage_executors(client: Any, request: ManageExecutorsRequest) -> dict
 
     elif flow_stage == "create":
         # Stage 3: Create executor
-        executor_type = request.executor_type or request.executor_config.get("type") or request.executor_config.get("executor_type")
+        executor_type = (
+            request.executor_type
+            or request.executor_config.get("type")
+            or request.executor_config.get("executor_type")
+        )
 
         if not executor_type:
             return {
@@ -138,7 +159,9 @@ async def manage_executors(client: Any, request: ManageExecutorsRequest) -> dict
             }
 
         # Merge with defaults
-        merged_config = executor_preferences.merge_with_defaults(executor_type, request.executor_config)
+        merged_config = executor_preferences.merge_with_defaults(
+            executor_type, request.executor_config
+        )
 
         # Ensure type is set in config
         if "type" not in merged_config and "executor_type" not in merged_config:
@@ -164,14 +187,19 @@ async def manage_executors(client: Any, request: ManageExecutorsRequest) -> dict
 
         account = request.account_name or "master_account"
         # Check both top-level param and executor_config (agents sometimes put it in the wrong place)
-        controller_id = request.controller_id or merged_config.pop("controller_id", None) or "main"
+        controller_id = (
+            request.controller_id or merged_config.pop("controller_id", None) or "main"
+        )
 
         import logging as _logging
+
         _logging.getLogger(__name__).info(
             "create_executor: controller_id=%r (request=%r, config_had=%r), type=%s, account=%s",
-            controller_id, request.controller_id,
+            controller_id,
+            request.controller_id,
             "controller_id" in (request.executor_config or {}),
-            executor_type, account,
+            executor_type,
+            account,
         )
 
         try:
@@ -183,7 +211,9 @@ async def manage_executors(client: Any, request: ManageExecutorsRequest) -> dict
 
             # Save as default if requested
             if request.save_as_default:
-                executor_preferences.update_defaults(executor_type, request.executor_config)
+                executor_preferences.update_defaults(
+                    executor_type, request.executor_config
+                )
 
             executor_id = result.get("executor_id") or result.get("id")
 
@@ -238,7 +268,9 @@ async def manage_executors(client: Any, request: ManageExecutorsRequest) -> dict
                 controller_ids=request.controller_ids,
             )
 
-            executors = result.get("data", result) if isinstance(result, dict) else result
+            executors = (
+                result.get("data", result) if isinstance(result, dict) else result
+            )
             if not isinstance(executors, list):
                 executors = [executors] if executors else []
 
@@ -253,7 +285,9 @@ async def manage_executors(client: Any, request: ManageExecutorsRequest) -> dict
                 "action": "search",
                 "executors": executors,
                 "count": len(executors),
-                "cursor": result.get("next_cursor") if isinstance(result, dict) else None,
+                "cursor": (
+                    result.get("next_cursor") if isinstance(result, dict) else None
+                ),
                 "formatted_output": formatted,
             }
 
@@ -345,7 +379,9 @@ async def manage_executors(client: Any, request: ManageExecutorsRequest) -> dict
         # Stage 8: Get saved preferences (returns raw markdown content)
         raw_content = executor_preferences.get_raw_content()
 
-        formatted = f"Preferences file: {executor_preferences.get_preferences_path()}\n\n"
+        formatted = (
+            f"Preferences file: {executor_preferences.get_preferences_path()}\n\n"
+        )
         formatted += raw_content
 
         return {
@@ -377,10 +413,14 @@ async def manage_executors(client: Any, request: ManageExecutorsRequest) -> dict
         formatted = "Preferences documentation updated to latest version.\n\n"
         if preserved_count > 0:
             preserved_names = [k for k, v in preserved.items() if v]
-            formatted += f"Preserved {preserved_count} config(s): {', '.join(preserved_names)}\n"
+            formatted += (
+                f"Preserved {preserved_count} config(s): {', '.join(preserved_names)}\n"
+            )
         else:
             formatted += "No existing configs to preserve.\n"
-        formatted += f"\nPreferences file: {executor_preferences.get_preferences_path()}"
+        formatted += (
+            f"\nPreferences file: {executor_preferences.get_preferences_path()}"
+        )
 
         return {
             "action": "reset_preferences",
@@ -413,7 +453,9 @@ async def manage_executors(client: Any, request: ManageExecutorsRequest) -> dict
                     positions = [result] if not isinstance(result, list) else result
                     formatted += format_positions_held_table(positions)
                 else:
-                    formatted += "No position found for this connector/pair combination."
+                    formatted += (
+                        "No position found for this connector/pair combination."
+                    )
 
                 return {
                     "action": "positions_summary",
@@ -428,13 +470,17 @@ async def manage_executors(client: Any, request: ManageExecutorsRequest) -> dict
                 controller_id=request.controller_id,
             )
 
-            positions = result.get("positions", result) if isinstance(result, dict) else result
+            positions = (
+                result.get("positions", result) if isinstance(result, dict) else result
+            )
             if not isinstance(positions, list):
                 positions = [positions] if positions else []
 
             formatted = f"Positions Held Summary\n\n"
 
-            if isinstance(result, dict) and any(k in result for k in ["total_positions", "total_value", "by_connector"]):
+            if isinstance(result, dict) and any(
+                k in result for k in ["total_positions", "total_value", "by_connector"]
+            ):
                 formatted += format_positions_summary(result)
                 if positions:
                     formatted += "\n\nPositions Detail:\n"
@@ -445,7 +491,9 @@ async def manage_executors(client: Any, request: ManageExecutorsRequest) -> dict
             return {
                 "action": "positions_summary",
                 "positions": positions,
-                "summary": result if isinstance(result, dict) else {"positions": positions},
+                "summary": (
+                    result if isinstance(result, dict) else {"positions": positions}
+                ),
                 "formatted_output": formatted,
             }
 
diff --git a/mcp_servers/hummingbot_api/tools/gateway.py b/mcp_servers/hummingbot_api/tools/gateway.py
index c4ecdf17..716444fc 100644
--- a/mcp_servers/hummingbot_api/tools/gateway.py
+++ b/mcp_servers/hummingbot_api/tools/gateway.py
@@ -1,16 +1,22 @@
 """
 Gateway management tools for Hummingbot MCP Server
 """
+
 import logging
 from typing import Any
 
 from mcp_servers.hummingbot_api.exceptions import ToolError
-from mcp_servers.hummingbot_api.schemas import GatewayConfigRequest, GatewayContainerRequest
+from mcp_servers.hummingbot_api.schemas import (
+    GatewayConfigRequest,
+    GatewayContainerRequest,
+)
 
 logger = logging.getLogger("hummingbot-mcp")
 
 
-async def manage_gateway_container(client: Any, request: GatewayContainerRequest) -> dict[str, Any]:
+async def manage_gateway_container(
+    client: Any, request: GatewayContainerRequest
+) -> dict[str, Any]:
     """Manage Gateway container lifecycle operations.
 
     Supports:
@@ -22,10 +28,7 @@ async def manage_gateway_container(client: Any, request: GatewayContainerRequest
     """
     if request.action == "get_status":
         result = await client.gateway.get_status()
-        return {
-            "action": "get_status",
-            "status": result
-        }
+        return {"action": "get_status", "status": result}
 
     elif request.action == "start":
         if not request.config:
@@ -38,7 +41,7 @@ async def manage_gateway_container(client: Any, request: GatewayContainerRequest
         return {
             "action": "start",
             "message": "Gateway started successfully",
-            "result": result
+            "result": result,
         }
 
     elif request.action == "stop":
@@ -46,7 +49,7 @@ async def manage_gateway_container(client: Any, request: GatewayContainerRequest
         return {
             "action": "stop",
             "message": "Gateway stopped successfully",
-            "result": result
+            "result": result,
         }
 
     elif request.action == "restart":
@@ -55,22 +58,20 @@ async def manage_gateway_container(client: Any, request: GatewayContainerRequest
             "action": "restart",
             "message": "Gateway restarted successfully",
             "result": result,
-            "config_updated": request.config is not None
+            "config_updated": request.config is not None,
         }
 
     elif request.action == "get_logs":
         result = await client.gateway.get_logs(tail=request.tail or 100)
-        return {
-            "action": "get_logs",
-            "tail": request.tail or 100,
-            "logs": result
-        }
+        return {"action": "get_logs", "tail": request.tail or 100, "logs": result}
 
     else:
         raise ToolError(f"Unknown action: {request.action}")
 
 
-async def manage_gateway_config(client: Any, request: GatewayConfigRequest) -> dict[str, Any]:
+async def manage_gateway_config(
+    client: Any, request: GatewayConfigRequest
+) -> dict[str, Any]:
     """Manage Gateway configuration for chains, networks, tokens, connectors, pools, and wallets.
 
     Resource Types:
@@ -86,14 +87,12 @@ async def manage_gateway_config(client: Any, request: GatewayConfigRequest) -> d
     # ============================================
     if request.resource_type == "chains":
         if request.action != "list":
-            raise ToolError(f"Only 'list' action is supported for chains, got: {request.action}")
+            raise ToolError(
+                f"Only 'list' action is supported for chains, got: {request.action}"
+            )
 
         result = await client.gateway.list_chains()
-        return {
-            "resource_type": "chains",
-            "action": "list",
-            "result": result
-        }
+        return {"resource_type": "chains", "action": "list", "result": result}
 
     # ============================================
     # NETWORKS
@@ -101,11 +100,7 @@ async def manage_gateway_config(client: Any, request: GatewayConfigRequest) -> d
     elif request.resource_type == "networks":
         if request.action == "list":
             result = await client.gateway.list_networks()
-            return {
-                "resource_type": "networks",
-                "action": "list",
-                "result": result
-            }
+            return {"resource_type": "networks", "action": "list", "result": result}
 
         elif request.action == "get":
             if not request.network_id:
@@ -116,24 +111,25 @@ async def manage_gateway_config(client: Any, request: GatewayConfigRequest) -> d
                 "resource_type": "networks",
                 "action": "get",
                 "network_id": request.network_id,
-                "result": result
+                "result": result,
             }
 
         elif request.action == "update":
             if not request.network_id:
                 raise ToolError("network_id is required for 'update' network action")
             if not request.config_updates:
-                raise ToolError("config_updates is required for 'update' network action")
+                raise ToolError(
+                    "config_updates is required for 'update' network action"
+                )
 
             result = await client.gateway.update_network_config(
-                request.network_id,
-                request.config_updates
+                request.network_id, request.config_updates
             )
             return {
                 "resource_type": "networks",
                 "action": "update",
                 "network_id": request.network_id,
-                "result": result
+                "result": result,
             }
 
         else:
@@ -151,15 +147,14 @@ async def manage_gateway_config(client: Any, request: GatewayConfigRequest) -> d
                 raise ToolError("network_id is required for 'list' tokens action")
 
             result = await client.gateway.get_network_tokens(
-                request.network_id,
-                search=request.search
+                request.network_id, search=request.search
             )
             return {
                 "resource_type": "tokens",
                 "action": "list",
                 "network_id": request.network_id,
                 "search": request.search,
-                "result": result
+                "result": result,
             }
 
         elif request.action == "add":
@@ -177,7 +172,7 @@ async def manage_gateway_config(client: Any, request: GatewayConfigRequest) -> d
                 address=request.token_address,
                 symbol=request.token_symbol,
                 decimals=request.token_decimals,
-                name=request.token_name
+                name=request.token_name,
             )
             return {
                 "resource_type": "tokens",
@@ -187,9 +182,9 @@ async def manage_gateway_config(client: Any, request: GatewayConfigRequest) -> d
                     "address": request.token_address,
                     "symbol": request.token_symbol,
                     "decimals": request.token_decimals,
-                    "name": request.token_name
+                    "name": request.token_name,
                 },
-                "result": result
+                "result": result,
             }
 
         elif request.action == "delete":
@@ -199,15 +194,14 @@ async def manage_gateway_config(client: Any, request: GatewayConfigRequest) -> d
                 raise ToolError("token_address is required for 'delete' token action")
 
             result = await client.gateway.delete_token(
-                network_id=request.network_id,
-                token_address=request.token_address
+                network_id=request.network_id, token_address=request.token_address
             )
             return {
                 "resource_type": "tokens",
                 "action": "delete",
                 "network_id": request.network_id,
                 "token_address": request.token_address,
-                "result": result
+                "result": result,
             }
 
         elif request.action == "save":
@@ -221,15 +215,14 @@ async def manage_gateway_config(client: Any, request: GatewayConfigRequest) -> d
                 raise ToolError("token_address is required for 'save' token action")
 
             result = await client.gateway.save_network_token(
-                network_id=request.network_id,
-                token_address=request.token_address
+                network_id=request.network_id, token_address=request.token_address
             )
             return {
                 "resource_type": "tokens",
                 "action": "save",
                 "network_id": request.network_id,
                 "token_address": request.token_address,
-                "result": result
+                "result": result,
             }
 
         else:
@@ -244,11 +237,7 @@ async def manage_gateway_config(client: Any, request: GatewayConfigRequest) -> d
     elif request.resource_type == "connectors":
         if request.action == "list":
             result = await client.gateway.list_connectors()
-            return {
-                "resource_type": "connectors",
-                "action": "list",
-                "result": result
-            }
+            return {"resource_type": "connectors", "action": "list", "result": result}
 
         elif request.action == "get":
             if not request.connector_name:
@@ -259,24 +248,27 @@ async def manage_gateway_config(client: Any, request: GatewayConfigRequest) -> d
                 "resource_type": "connectors",
                 "action": "get",
                 "connector_name": request.connector_name,
-                "result": result
+                "result": result,
             }
 
         elif request.action == "update":
             if not request.connector_name:
-                raise ToolError("connector_name is required for 'update' connector action")
+                raise ToolError(
+                    "connector_name is required for 'update' connector action"
+                )
             if not request.config_updates:
-                raise ToolError("config_updates is required for 'update' connector action")
+                raise ToolError(
+                    "config_updates is required for 'update' connector action"
+                )
 
             result = await client.gateway.update_connector_config(
-                request.connector_name,
-                request.config_updates
+                request.connector_name, request.config_updates
             )
             return {
                 "resource_type": "connectors",
                 "action": "update",
                 "connector_name": request.connector_name,
-                "result": result
+                "result": result,
             }
 
         else:
@@ -300,14 +292,14 @@ async def manage_gateway_config(client: Any, request: GatewayConfigRequest) -> d
                 network_id=request.network_id,
                 connector=request.connector_name,  # Optional filter
                 pool_type=request.pool_type,  # Optional filter
-                search=request.search  # Optional search
+                search=request.search,  # Optional search
             )
             return {
                 "resource_type": "pools",
                 "action": "list",
                 "network_id": request.network_id,
                 "connector": request.connector_name,
-                "result": result
+                "result": result,
             }
 
         elif request.action == "add":
@@ -329,7 +321,7 @@ async def manage_gateway_config(client: Any, request: GatewayConfigRequest) -> d
                 pool_type=request.pool_type,
                 address=request.pool_address,
                 base=request.pool_base,
-                quote=request.pool_quote
+                quote=request.pool_quote,
             )
             return {
                 "resource_type": "pools",
@@ -340,9 +332,9 @@ async def manage_gateway_config(client: Any, request: GatewayConfigRequest) -> d
                     "type": request.pool_type,
                     "base": request.pool_base,
                     "quote": request.pool_quote,
-                    "address": request.pool_address
+                    "address": request.pool_address,
                 },
-                "result": result
+                "result": result,
             }
 
         elif request.action == "delete":
@@ -357,14 +349,14 @@ async def manage_gateway_config(client: Any, request: GatewayConfigRequest) -> d
             result = await client.gateway.delete_network_pool(
                 network_id=request.network_id,
                 address=request.pool_address,
-                pool_type=request.pool_type
+                pool_type=request.pool_type,
             )
             return {
                 "resource_type": "pools",
                 "action": "delete",
                 "network_id": request.network_id,
                 "pool_address": request.pool_address,
-                "result": result
+                "result": result,
             }
 
         elif request.action == "save":
@@ -378,15 +370,14 @@ async def manage_gateway_config(client: Any, request: GatewayConfigRequest) -> d
                 raise ToolError("pool_address is required for 'save' pool action")
 
             result = await client.gateway.save_network_pool(
-                network_id=request.network_id,
-                pool_address=request.pool_address
+                network_id=request.network_id, pool_address=request.pool_address
             )
             return {
                 "resource_type": "pools",
                 "action": "save",
                 "network_id": request.network_id,
                 "pool_address": request.pool_address,
-                "result": result
+                "result": result,
             }
 
         else:
@@ -406,14 +397,13 @@ async def manage_gateway_config(client: Any, request: GatewayConfigRequest) -> d
                 raise ToolError("private_key is required for 'add' wallet action")
 
             result = await client.accounts.add_gateway_wallet(
-                chain=request.chain,
-                private_key=request.private_key
+                chain=request.chain, private_key=request.private_key
             )
             return {
                 "resource_type": "wallets",
                 "action": "add",
                 "chain": request.chain,
-                "result": result
+                "result": result,
             }
 
         elif request.action == "delete":
@@ -423,15 +413,14 @@ async def manage_gateway_config(client: Any, request: GatewayConfigRequest) -> d
                 raise ToolError("wallet_address is required for 'delete' wallet action")
 
             result = await client.accounts.remove_gateway_wallet(
-                chain=request.chain,
-                address=request.wallet_address
+                chain=request.chain, address=request.wallet_address
             )
             return {
                 "resource_type": "wallets",
                 "action": "delete",
                 "chain": request.chain,
                 "wallet_address": request.wallet_address,
-                "result": result
+                "result": result,
             }
 
         else:
diff --git a/mcp_servers/hummingbot_api/tools/gateway_amm.py b/mcp_servers/hummingbot_api/tools/gateway_amm.py
index c37ac464..6a9dc7a9 100644
--- a/mcp_servers/hummingbot_api/tools/gateway_amm.py
+++ b/mcp_servers/hummingbot_api/tools/gateway_amm.py
@@ -10,6 +10,7 @@
 positions[] breakdown, and positions_owned lists all of a wallet's positions. Fungible-LP AMMs
 (raydium, uniswap) ignore position_address and have no enumerable positions.
 """
+
 from decimal import Decimal
 from pathlib import Path
 from typing import Any
@@ -66,7 +67,9 @@ async def manage_amm_impl(client: Any, request: AMMRequest) -> dict[str, Any]:
             f"Unsupported AMM connector '{request.connector}'. Supported: {', '.join(sorted(SUPPORTED_CONNECTORS))}"
         )
     if not request.network:
-        raise ToolError("network is required (e.g. 'solana-mainnet-beta', 'ethereum-mainnet')")
+        raise ToolError(
+            "network is required (e.g. 'solana-mainnet-beta', 'ethereum-mainnet')"
+        )
 
     net = request.network
     action = request.action
@@ -75,12 +78,16 @@ async def manage_amm_impl(client: Any, request: AMMRequest) -> dict[str, Any]:
 
     if action == "pool_info":
         _require(request, "pool_address")
-        result = await ga.get_pool_info(connector=connector, network=net, pool_address=request.pool_address)
+        result = await ga.get_pool_info(
+            connector=connector, network=net, pool_address=request.pool_address
+        )
 
     elif action == "position_info":
         _require(request, "pool_address")
         result = await ga.get_position_info(
-            connector=connector, network=net, pool_address=request.pool_address,
+            connector=connector,
+            network=net,
+            pool_address=request.pool_address,
             wallet_address=request.wallet_address,
         )
 
@@ -90,28 +97,41 @@ async def manage_amm_impl(client: Any, request: AMMRequest) -> dict[str, Any]:
                 f"positions_owned is not supported for '{connector}': fungible-LP AMMs have no enumerable "
                 "positions. Use position_info with a specific pool_address instead."
             )
-        result = await ga.get_positions_owned(connector=connector, network=net, wallet_address=request.wallet_address)
+        result = await ga.get_positions_owned(
+            connector=connector, network=net, wallet_address=request.wallet_address
+        )
 
     elif action == "quote_swap":
         _require(request, "pool_address", "base_token", "side", "amount")
         result = await ga.get_swap_quote(
-            connector=connector, network=net, pool_address=request.pool_address,
-            base_token=request.base_token, side=request.side, amount=_dec(request.amount, "amount"),
+            connector=connector,
+            network=net,
+            pool_address=request.pool_address,
+            base_token=request.base_token,
+            side=request.side,
+            amount=_dec(request.amount, "amount"),
             slippage_pct=_opt_dec(request.slippage_pct),
         )
 
     elif action == "execute_swap":
         _require(request, "pool_address", "base_token", "side", "amount")
         result = await ga.execute_swap(
-            connector=connector, network=net, pool_address=request.pool_address,
-            base_token=request.base_token, side=request.side, amount=_dec(request.amount, "amount"),
-            slippage_pct=_opt_dec(request.slippage_pct), wallet_address=request.wallet_address,
+            connector=connector,
+            network=net,
+            pool_address=request.pool_address,
+            base_token=request.base_token,
+            side=request.side,
+            amount=_dec(request.amount, "amount"),
+            slippage_pct=_opt_dec(request.slippage_pct),
+            wallet_address=request.wallet_address,
         )
 
     elif action == "quote_liquidity":
         _require(request, "pool_address", "base_token_amount", "quote_token_amount")
         result = await ga.get_liquidity_quote(
-            connector=connector, network=net, pool_address=request.pool_address,
+            connector=connector,
+            network=net,
+            pool_address=request.pool_address,
             base_token_amount=_dec(request.base_token_amount, "base_token_amount"),
             quote_token_amount=_dec(request.quote_token_amount, "quote_token_amount"),
             slippage_pct=_opt_dec(request.slippage_pct),
@@ -121,10 +141,13 @@ async def manage_amm_impl(client: Any, request: AMMRequest) -> dict[str, Any]:
         _require(request, "pool_address", "base_token_amount", "quote_token_amount")
         # Meteora: position_address optional (omit = new position). Fungible-LP: ignored.
         result = await ga.add_liquidity(
-            connector=connector, network=net, pool_address=request.pool_address,
+            connector=connector,
+            network=net,
+            pool_address=request.pool_address,
             base_token_amount=_dec(request.base_token_amount, "base_token_amount"),
             quote_token_amount=_dec(request.quote_token_amount, "quote_token_amount"),
-            slippage_pct=_opt_dec(request.slippage_pct), wallet_address=request.wallet_address,
+            slippage_pct=_opt_dec(request.slippage_pct),
+            wallet_address=request.wallet_address,
             position_address=request.position_address,
         )
 
@@ -137,9 +160,14 @@ async def manage_amm_impl(client: Any, request: AMMRequest) -> dict[str, Any]:
                 "and a wallet may hold several per pool. List them with position_info or positions_owned."
             )
         result = await ga.remove_liquidity(
-            connector=connector, network=net, pool_address=request.pool_address,
-            percentage_to_remove=_dec(request.percentage_to_remove, "percentage_to_remove"),
-            position_address=request.position_address, slippage_pct=_opt_dec(request.slippage_pct),
+            connector=connector,
+            network=net,
+            pool_address=request.pool_address,
+            percentage_to_remove=_dec(
+                request.percentage_to_remove, "percentage_to_remove"
+            ),
+            position_address=request.position_address,
+            slippage_pct=_opt_dec(request.slippage_pct),
             wallet_address=request.wallet_address,
         )
 
@@ -152,12 +180,17 @@ async def manage_amm_impl(client: Any, request: AMMRequest) -> dict[str, Any]:
                 "avoid token-launch configs whose base fee starts near 99%."
             )
         result = await ga.create_pool(
-            connector=connector, network=net, base_token=request.base_token, quote_token=request.quote_token,
+            connector=connector,
+            network=net,
+            base_token=request.base_token,
+            quote_token=request.quote_token,
             base_token_amount=_dec(request.base_token_amount, "base_token_amount"),
             quote_token_amount=_opt_dec(request.quote_token_amount),
             initial_price=_opt_dec(request.initial_price),
-            config_address=request.config_address, fee_config_index=request.fee_config_index,
-            gas_price=_opt_dec(request.gas_price), max_gas=request.max_gas,
+            config_address=request.config_address,
+            fee_config_index=request.fee_config_index,
+            gas_price=_opt_dec(request.gas_price),
+            max_gas=request.max_gas,
             wallet_address=request.wallet_address,
         )
 
diff --git a/mcp_servers/hummingbot_api/tools/gateway_clmm.py b/mcp_servers/hummingbot_api/tools/gateway_clmm.py
index ed332927..189f4fce 100644
--- a/mcp_servers/hummingbot_api/tools/gateway_clmm.py
+++ b/mcp_servers/hummingbot_api/tools/gateway_clmm.py
@@ -7,6 +7,7 @@
 
 For opening/closing LP positions, use `manage_executors` with `lp_executor` type.
 """
+
 import logging
 from typing import Any
 
@@ -74,16 +75,16 @@ def format_pools_as_detailed_table(pools: list[dict[str, Any]]) -> str:
     rows = []
     for pool in pools:
         # Extract nested volume fields
-        volume = pool.get('volume', {})
-        volume_hour_1 = volume.get('hour_1', 'N/A')
-        volume_hour_12 = volume.get('hour_12', 'N/A')
-        volume_hour_24 = volume.get('hour_24', 'N/A')
+        volume = pool.get("volume", {})
+        volume_hour_1 = volume.get("hour_1", "N/A")
+        volume_hour_12 = volume.get("hour_12", "N/A")
+        volume_hour_24 = volume.get("hour_24", "N/A")
 
         # Extract nested fee_tvl_ratio fields
-        fee_tvl_ratio = pool.get('fee_tvl_ratio', {})
-        fee_tvl_ratio_hour_1 = fee_tvl_ratio.get('hour_1', 'N/A')
-        fee_tvl_ratio_hour_12 = fee_tvl_ratio.get('hour_12', 'N/A')
-        fee_tvl_ratio_hour_24 = fee_tvl_ratio.get('hour_24', 'N/A')
+        fee_tvl_ratio = pool.get("fee_tvl_ratio", {})
+        fee_tvl_ratio_hour_1 = fee_tvl_ratio.get("hour_1", "N/A")
+        fee_tvl_ratio_hour_12 = fee_tvl_ratio.get("hour_12", "N/A")
+        fee_tvl_ratio_hour_24 = fee_tvl_ratio.get("hour_24", "N/A")
 
         row = (
             f"{get_field(pool, 'address', default='N/A')} | "
@@ -110,7 +111,9 @@ def format_pools_as_detailed_table(pools: list[dict[str, Any]]) -> str:
     return f"{header}\n{separator}\n" + "\n".join(rows)
 
 
-async def explore_gateway_clmm_pools(client: Any, request: GatewayCLMMRequest) -> dict[str, Any]:
+async def explore_gateway_clmm_pools(
+    client: Any, request: GatewayCLMMRequest
+) -> dict[str, Any]:
     """
     Explore Gateway CLMM pools: list pools and get pool information.
 
@@ -136,7 +139,7 @@ async def explore_gateway_clmm_pools(client: Any, request: GatewayCLMMRequest) -
             search_term=request.search_term,
             sort_key=request.sort_key,
             order_by=request.order_by,
-            include_unknown=request.include_unknown
+            include_unknown=request.include_unknown,
         )
 
         pools = result.get("pools", [])
@@ -155,14 +158,14 @@ async def explore_gateway_clmm_pools(client: Any, request: GatewayCLMMRequest) -
                 "search_term": request.search_term,
                 "sort_key": request.sort_key,
                 "order_by": request.order_by,
-                "include_unknown": request.include_unknown
+                "include_unknown": request.include_unknown,
             },
             "pagination": {
                 "page": request.page,
                 "limit": request.limit,
-                "total": result.get("total", 0)
+                "total": result.get("total", 0),
             },
-            "pools_table": formatted_table
+            "pools_table": formatted_table,
         }
 
     # ============================================
@@ -178,7 +181,7 @@ async def explore_gateway_clmm_pools(client: Any, request: GatewayCLMMRequest) -
         result = await client.gateway_clmm.get_pool_info(
             connector=request.connector,
             network=request.network,
-            pool_address=request.pool_address
+            pool_address=request.pool_address,
         )
 
         return {
@@ -186,10 +189,8 @@ async def explore_gateway_clmm_pools(client: Any, request: GatewayCLMMRequest) -
             "connector": request.connector,
             "network": request.network,
             "pool_address": request.pool_address,
-            "result": result
+            "result": result,
         }
 
     else:
         raise ToolError(f"Unknown action: {request.action}")
-
-
diff --git a/mcp_servers/hummingbot_api/tools/gateway_swap.py b/mcp_servers/hummingbot_api/tools/gateway_swap.py
index 309a1636..3843ef8a 100644
--- a/mcp_servers/hummingbot_api/tools/gateway_swap.py
+++ b/mcp_servers/hummingbot_api/tools/gateway_swap.py
@@ -5,6 +5,7 @@
 - Swap quote/execute (Router: Jupiter, 0x)
 - Swap search and status tracking
 """
+
 import logging
 from decimal import Decimal
 from typing import Any
@@ -15,7 +16,9 @@
 logger = logging.getLogger("hummingbot-mcp")
 
 
-async def manage_gateway_swaps(client: Any, request: GatewaySwapRequest) -> dict[str, Any]:
+async def manage_gateway_swaps(
+    client: Any, request: GatewaySwapRequest
+) -> dict[str, Any]:
     """
     Manage Gateway swap operations: quote, execute, search, and status tracking.
 
@@ -47,7 +50,9 @@ async def manage_gateway_swaps(client: Any, request: GatewaySwapRequest) -> dict
 
         # Parse trading pair
         if "-" not in request.trading_pair:
-            raise ToolError(f"Invalid trading_pair format. Expected 'BASE-QUOTE', got '{request.trading_pair}'")
+            raise ToolError(
+                f"Invalid trading_pair format. Expected 'BASE-QUOTE', got '{request.trading_pair}'"
+            )
 
         result = await client.gateway_swap.get_swap_quote(
             connector=request.connector,
@@ -55,7 +60,7 @@ async def manage_gateway_swaps(client: Any, request: GatewaySwapRequest) -> dict
             trading_pair=request.trading_pair,
             side=request.side,
             amount=Decimal(request.amount),
-            slippage_pct=Decimal(request.slippage_pct or "1.0")
+            slippage_pct=Decimal(request.slippage_pct or "1.0"),
         )
 
         return {
@@ -63,7 +68,7 @@ async def manage_gateway_swaps(client: Any, request: GatewaySwapRequest) -> dict
             "trading_pair": request.trading_pair,
             "side": request.side,
             "amount": request.amount,
-            "result": result
+            "result": result,
         }
 
     # ============================================
@@ -84,7 +89,9 @@ async def manage_gateway_swaps(client: Any, request: GatewaySwapRequest) -> dict
 
         # Parse trading pair
         if "-" not in request.trading_pair:
-            raise ToolError(f"Invalid trading_pair format. Expected 'BASE-QUOTE', got '{request.trading_pair}'")
+            raise ToolError(
+                f"Invalid trading_pair format. Expected 'BASE-QUOTE', got '{request.trading_pair}'"
+            )
 
         result = await client.gateway_swap.execute_swap(
             connector=request.connector,
@@ -93,7 +100,7 @@ async def manage_gateway_swaps(client: Any, request: GatewaySwapRequest) -> dict
             side=request.side,
             amount=Decimal(request.amount),
             slippage_pct=Decimal(request.slippage_pct or "1.0"),
-            wallet_address=request.wallet_address
+            wallet_address=request.wallet_address,
         )
 
         return {
@@ -102,7 +109,7 @@ async def manage_gateway_swaps(client: Any, request: GatewaySwapRequest) -> dict
             "side": request.side,
             "amount": request.amount,
             "wallet_address": request.wallet_address or "(default)",
-            "result": result
+            "result": result,
         }
 
     # ============================================
@@ -117,7 +124,7 @@ async def manage_gateway_swaps(client: Any, request: GatewaySwapRequest) -> dict
         return {
             "action": "get_status",
             "transaction_hash": request.transaction_hash,
-            "result": result
+            "result": result,
         }
 
     # ============================================
@@ -125,10 +132,7 @@ async def manage_gateway_swaps(client: Any, request: GatewaySwapRequest) -> dict
     # ============================================
     elif request.action == "search":
         # Build search filters
-        search_params = {
-            "limit": request.limit or 50,
-            "offset": request.offset or 0
-        }
+        search_params = {"limit": request.limit or 50, "offset": request.offset or 0}
 
         # Add optional filters
         if request.search_network:
@@ -150,12 +154,14 @@ async def manage_gateway_swaps(client: Any, request: GatewaySwapRequest) -> dict
 
         return {
             "action": "search",
-            "filters": {k: v for k, v in search_params.items() if k not in ["limit", "offset"]},
+            "filters": {
+                k: v for k, v in search_params.items() if k not in ["limit", "offset"]
+            },
             "pagination": {
                 "limit": search_params["limit"],
-                "offset": search_params["offset"]
+                "offset": search_params["offset"],
             },
-            "result": result
+            "result": result,
         }
 
     else:
diff --git a/mcp_servers/hummingbot_api/tools/geckoterminal.py b/mcp_servers/hummingbot_api/tools/geckoterminal.py
index 3b9db361..05bb675c 100644
--- a/mcp_servers/hummingbot_api/tools/geckoterminal.py
+++ b/mcp_servers/hummingbot_api/tools/geckoterminal.py
@@ -8,11 +8,17 @@
 - OHLCV candle data
 - Recent trades
 """
+
 import logging
 from typing import Any
 
 from mcp_servers.hummingbot_api.exceptions import ToolError
-from mcp_servers.hummingbot_api.formatters.base import format_currency, format_number, format_timestamp, truncate_address
+from mcp_servers.hummingbot_api.formatters.base import (
+    format_currency,
+    format_number,
+    format_timestamp,
+    truncate_address,
+)
 
 logger = logging.getLogger("hummingbot-mcp")
 
@@ -26,15 +32,23 @@
 def _parse_timeframe(timeframe: str) -> tuple[str, str]:
     """Parse '1h' into ('hour', '1')."""
     if timeframe not in OHLCV_TIMEFRAMES:
-        raise ToolError(f"Unsupported timeframe '{timeframe}'. Use one of: {OHLCV_TIMEFRAMES}")
+        raise ToolError(
+            f"Unsupported timeframe '{timeframe}'. Use one of: {OHLCV_TIMEFRAMES}"
+        )
     period, unit = timeframe[:-1], timeframe[-1]
     return TIMEFRAME_UNIT_MAP[unit], period
 
 
 def _extract_networks(response: dict) -> list[dict[str, Any]]:
     return [
-        {"id": item["id"], "type": item["type"], "name": item["attributes"]["name"],
-         "coingecko_asset_platform_id": item["attributes"].get("coingecko_asset_platform_id")}
+        {
+            "id": item["id"],
+            "type": item["type"],
+            "name": item["attributes"]["name"],
+            "coingecko_asset_platform_id": item["attributes"].get(
+                "coingecko_asset_platform_id"
+            ),
+        }
         for item in response.get("data", [])
     ]
 
@@ -108,7 +122,14 @@ def _extract_trades(response: dict) -> list[dict[str, Any]]:
 def _extract_ohlcv(response: dict) -> list[dict[str, Any]]:
     ohlcv_list = response.get("data", {}).get("attributes", {}).get("ohlcv_list", [])
     return [
-        {"timestamp": row[0], "open": row[1], "high": row[2], "low": row[3], "close": row[4], "volume_usd": row[5]}
+        {
+            "timestamp": row[0],
+            "open": row[1],
+            "high": row[2],
+            "low": row[3],
+            "close": row[4],
+            "volume_usd": row[5],
+        }
         for row in ohlcv_list
     ]
 
@@ -127,7 +148,11 @@ def _extract_token_info(response: dict) -> dict[str, Any]:
         "fdv_usd": attrs.get("fdv_usd"),
         "market_cap_usd": attrs.get("market_cap_usd"),
         "total_reserve_in_usd": attrs.get("total_reserve_in_usd"),
-        "volume_usd_h24": attrs.get("volume_usd", {}).get("h24") if isinstance(attrs.get("volume_usd"), dict) else None,
+        "volume_usd_h24": (
+            attrs.get("volume_usd", {}).get("h24")
+            if isinstance(attrs.get("volume_usd"), dict)
+            else None
+        ),
     }
 
 
@@ -164,8 +189,14 @@ def format_pools_table(pools: list[dict]) -> str:
         price = format_currency(p.get("base_token_price_usd"), decimals=4)
         reserve = format_number(p.get("reserve_in_usd"))
         vol = format_number(p.get("volume_h24"))
-        chg = f"{float(p['price_change_h24']):.2f}%" if p.get("price_change_h24") is not None else "N/A"
-        rows.append(f"{name:31} | {addr:44} | {price:16} | {reserve:16} | {vol:16} | {chg}")
+        chg = (
+            f"{float(p['price_change_h24']):.2f}%"
+            if p.get("price_change_h24") is not None
+            else "N/A"
+        )
+        rows.append(
+            f"{name:31} | {addr:44} | {price:16} | {reserve:16} | {vol:16} | {chg}"
+        )
     return f"{header}\n{sep}\n" + "\n".join(rows)
 
 
@@ -197,7 +228,9 @@ def format_trades_table(trades: list[dict]) -> str:
         from_amt = format_number(t.get("from_token_amount"), 4, False)
         to_amt = format_number(t.get("to_token_amount"), 4, False)
         tx = truncate_address(t.get("tx_hash") or "N/A", 8, 6)
-        rows.append(f"{dt:19} | {side:4} | {vol:16} | {from_amt:16} | {to_amt:16} | {tx}")
+        rows.append(
+            f"{dt:19} | {side:4} | {vol:16} | {from_amt:16} | {to_amt:16} | {tx}"
+        )
     return f"{header}\n{sep}\n" + "\n".join(rows)
 
 
@@ -247,7 +280,9 @@ async def _get(path: str, params: dict | None = None) -> dict:
         if action == "networks":
             data = await _get("networks")
             networks = _extract_networks(data)
-            return {"formatted_output": f"Available Networks ({len(networks)}):\n\n{format_networks_table(networks)}"}
+            return {
+                "formatted_output": f"Available Networks ({len(networks)}):\n\n{format_networks_table(networks)}"
+            }
 
         # ── DEXes by network ─────────────────────────────────────────
         elif action == "dexes":
@@ -255,7 +290,9 @@ async def _get(path: str, params: dict | None = None) -> dict:
                 raise ToolError("'network' is required for action='dexes'")
             data = await _get(f"networks/{network}/dexes")
             dexes = _extract_dexes(data)
-            return {"formatted_output": f"DEXes on {network} ({len(dexes)}):\n\n{format_dexes_table(dexes)}"}
+            return {
+                "formatted_output": f"DEXes on {network} ({len(dexes)}):\n\n{format_dexes_table(dexes)}"
+            }
 
         # ── Trending pools ───────────────────────────────────────────
         elif action == "trending_pools":
@@ -266,7 +303,9 @@ async def _get(path: str, params: dict | None = None) -> dict:
                 data = await _get("networks/trending_pools")
                 title = "Trending Pools (All Networks)"
             pools = _extract_pools(data)
-            return {"formatted_output": f"{title} ({len(pools)}):\n\n{format_pools_table(pools)}"}
+            return {
+                "formatted_output": f"{title} ({len(pools)}):\n\n{format_pools_table(pools)}"
+            }
 
         # ── Top pools ────────────────────────────────────────────────
         elif action == "top_pools":
@@ -279,7 +318,9 @@ async def _get(path: str, params: dict | None = None) -> dict:
                 data = await _get(f"networks/{network}/pools")
                 title = f"Top Pools on {network}"
             pools = _extract_pools(data)
-            return {"formatted_output": f"{title} ({len(pools)}):\n\n{format_pools_table(pools)}"}
+            return {
+                "formatted_output": f"{title} ({len(pools)}):\n\n{format_pools_table(pools)}"
+            }
 
         # ── New pools ────────────────────────────────────────────────
         elif action == "new_pools":
@@ -290,12 +331,16 @@ async def _get(path: str, params: dict | None = None) -> dict:
                 data = await _get("networks/new_pools")
                 title = "New Pools (All Networks)"
             pools = _extract_pools(data)
-            return {"formatted_output": f"{title} ({len(pools)}):\n\n{format_pools_table(pools)}"}
+            return {
+                "formatted_output": f"{title} ({len(pools)}):\n\n{format_pools_table(pools)}"
+            }
 
         # ── Pool detail ──────────────────────────────────────────────
         elif action == "pool_detail":
             if not network or not pool_address:
-                raise ToolError("'network' and 'pool_address' are required for action='pool_detail'")
+                raise ToolError(
+                    "'network' and 'pool_address' are required for action='pool_detail'"
+                )
             data = await _get(f"networks/{network}/pools/{pool_address}")
             pools = _extract_pools(data)
             if pools:
@@ -321,24 +366,34 @@ async def _get(path: str, params: dict | None = None) -> dict:
         # ── Multiple pools ───────────────────────────────────────────
         elif action == "multi_pools":
             if not network or not pool_addresses:
-                raise ToolError("'network' and 'pool_addresses' are required for action='multi_pools'")
+                raise ToolError(
+                    "'network' and 'pool_addresses' are required for action='multi_pools'"
+                )
             addresses_str = ",".join(pool_addresses)
             data = await _get(f"networks/{network}/pools/multi/{addresses_str}")
             pools = _extract_pools(data)
-            return {"formatted_output": f"Pools on {network} ({len(pools)}):\n\n{format_pools_table(pools)}"}
+            return {
+                "formatted_output": f"Pools on {network} ({len(pools)}):\n\n{format_pools_table(pools)}"
+            }
 
         # ── Pools by token ───────────────────────────────────────────
         elif action == "token_pools":
             if not network or not token_address:
-                raise ToolError("'network' and 'token_address' are required for action='token_pools'")
+                raise ToolError(
+                    "'network' and 'token_address' are required for action='token_pools'"
+                )
             data = await _get(f"networks/{network}/tokens/{token_address}/pools")
             pools = _extract_pools(data)
-            return {"formatted_output": f"Top Pools for token on {network} ({len(pools)}):\n\n{format_pools_table(pools)}"}
+            return {
+                "formatted_output": f"Top Pools for token on {network} ({len(pools)}):\n\n{format_pools_table(pools)}"
+            }
 
         # ── Token info ───────────────────────────────────────────────
         elif action == "token_info":
             if not network or not token_address:
-                raise ToolError("'network' and 'token_address' are required for action='token_info'")
+                raise ToolError(
+                    "'network' and 'token_address' are required for action='token_info'"
+                )
             data = await _get(f"networks/{network}/tokens/{token_address}")
             token_data = _extract_token_info(data)
             return {"formatted_output": format_token_info(token_data)}
@@ -346,12 +401,22 @@ async def _get(path: str, params: dict | None = None) -> dict:
         # ── OHLCV candles ────────────────────────────────────────────
         elif action == "ohlcv":
             if not network or not pool_address:
-                raise ToolError("'network' and 'pool_address' are required for action='ohlcv'")
+                raise ToolError(
+                    "'network' and 'pool_address' are required for action='ohlcv'"
+                )
             tf_unit, tf_period = _parse_timeframe(timeframe)
-            params: dict[str, Any] = {"aggregate": tf_period, "limit": limit, "currency": currency, "token": token}
+            params: dict[str, Any] = {
+                "aggregate": tf_period,
+                "limit": limit,
+                "currency": currency,
+                "token": token,
+            }
             if before_timestamp:
                 params["before_timestamp"] = before_timestamp
-            data = await _get(f"networks/{network}/pools/{pool_address}/ohlcv/{tf_unit}", params=params)
+            data = await _get(
+                f"networks/{network}/pools/{pool_address}/ohlcv/{tf_unit}",
+                params=params,
+            )
             candles = _extract_ohlcv(data)
             # Sort by timestamp ascending and deduplicate
             seen: set[int] = set()
@@ -361,24 +426,32 @@ async def _get(path: str, params: dict | None = None) -> dict:
                     seen.add(c["timestamp"])
                     unique.append(c)
             unique.sort(key=lambda x: x["timestamp"])
-            return {"formatted_output": (
-                f"OHLCV for pool {truncate_address(pool_address)} on {network} ({timeframe}, {len(unique)} candles):\n\n"
-                f"{format_ohlcv_table(unique)}"
-            )}
+            return {
+                "formatted_output": (
+                    f"OHLCV for pool {truncate_address(pool_address)} on {network} ({timeframe}, {len(unique)} candles):\n\n"
+                    f"{format_ohlcv_table(unique)}"
+                )
+            }
 
         # ── Trades ───────────────────────────────────────────────────
         elif action == "trades":
             if not network or not pool_address:
-                raise ToolError("'network' and 'pool_address' are required for action='trades'")
+                raise ToolError(
+                    "'network' and 'pool_address' are required for action='trades'"
+                )
             params = {}
             if trade_volume_filter is not None:
                 params["trade_volume_in_usd_greater_than"] = trade_volume_filter
-            data = await _get(f"networks/{network}/pools/{pool_address}/trades", params=params or None)
+            data = await _get(
+                f"networks/{network}/pools/{pool_address}/trades", params=params or None
+            )
             trades = _extract_trades(data)
-            return {"formatted_output": (
-                f"Recent Trades for pool {truncate_address(pool_address)} on {network} ({len(trades)}):\n\n"
-                f"{format_trades_table(trades)}"
-            )}
+            return {
+                "formatted_output": (
+                    f"Recent Trades for pool {truncate_address(pool_address)} on {network} ({len(trades)}):\n\n"
+                    f"{format_trades_table(trades)}"
+                )
+            }
 
         else:
             raise ToolError(
diff --git a/mcp_servers/hummingbot_api/tools/history.py b/mcp_servers/hummingbot_api/tools/history.py
index 9d1745e3..6fde5af5 100644
--- a/mcp_servers/hummingbot_api/tools/history.py
+++ b/mcp_servers/hummingbot_api/tools/history.py
@@ -6,12 +6,14 @@
 - Perpetual positions (open and closed)
 - CLMM positions (open and closed)
 """
+
 import logging
 from typing import Any, Literal
 
 from mcp_servers.hummingbot_api.hummingbot_client import HummingbotClient
-from . import trading as trading_tools
+
 from . import gateway_clmm as gateway_clmm_tools
+from . import trading as trading_tools
 
 logger = logging.getLogger("hummingbot-mcp")
 
@@ -83,14 +85,16 @@ async def search_history(
 
             formatted_output = f"Order History\n{'=' * 100}\n\n{result['orders_table']}"
 
-            if result['pagination'].get('has_more'):
-                formatted_output += f"\n\n... and more (use offset={offset + limit} to see more)"
+            if result["pagination"].get("has_more"):
+                formatted_output += (
+                    f"\n\n... and more (use offset={offset + limit} to see more)"
+                )
 
             return {
                 "data_type": "orders",
-                "total_count": result['total_returned'],
-                "results": result['orders'],
-                "formatted_output": formatted_output
+                "total_count": result["total_returned"],
+                "results": result["orders"],
+                "formatted_output": formatted_output,
             }
 
         # ============================================
@@ -109,9 +113,9 @@ async def search_history(
 
             return {
                 "data_type": "perp_positions",
-                "total_count": result['total_positions'],
-                "results": result['positions'],
-                "formatted_output": formatted_output
+                "total_count": result["total_positions"],
+                "results": result["positions"],
+                "formatted_output": formatted_output,
             }
 
         # ============================================
@@ -131,9 +135,13 @@ async def search_history(
             if wallet_address:
                 search_params["wallet_address"] = wallet_address
             if connector_names:
-                search_params["connector"] = connector_names[0] if len(connector_names) == 1 else None
+                search_params["connector"] = (
+                    connector_names[0] if len(connector_names) == 1 else None
+                )
             if trading_pairs:
-                search_params["trading_pair"] = trading_pairs[0] if len(trading_pairs) == 1 else None
+                search_params["trading_pair"] = (
+                    trading_pairs[0] if len(trading_pairs) == 1 else None
+                )
             if status:
                 search_params["status"] = status
             if position_addresses:
@@ -147,7 +155,7 @@ async def search_history(
                     "data_type": "clmm_positions",
                     "total_count": 0,
                     "results": [],
-                    "formatted_output": "No CLMM positions found"
+                    "formatted_output": "No CLMM positions found",
                 }
 
             positions = result.get("data", [])
@@ -170,7 +178,11 @@ async def search_history(
                     upper = f"{float(pos.get('upper_price', 0)):.4f}"[:10]
                     status_val = pos.get("status", "N/A")[:8]
                     created = pos.get("created_at", "N/A")[:20]
-                    closed = pos.get("closed_at", "N/A")[:20] if pos.get("closed_at") else "-"
+                    closed = (
+                        pos.get("closed_at", "N/A")[:20]
+                        if pos.get("closed_at")
+                        else "-"
+                    )
 
                     table_lines.append(
                         f"{connector:<10} | {network:<20} | {pair:<15} | {lower:<10} | {upper:<10} | "
@@ -178,7 +190,9 @@ async def search_history(
                     )
 
                 if total_count > limit:
-                    table_lines.append(f"\n... and {total_count - limit} more positions (use offset={offset + limit} to see more)")
+                    table_lines.append(
+                        f"\n... and {total_count - limit} more positions (use offset={offset + limit} to see more)"
+                    )
 
                 formatted_output = "\n".join(table_lines)
             else:
@@ -188,7 +202,7 @@ async def search_history(
                 "data_type": "clmm_positions",
                 "total_count": total_count,
                 "results": positions,
-                "formatted_output": formatted_output
+                "formatted_output": formatted_output,
             }
 
         else:
@@ -196,7 +210,7 @@ async def search_history(
                 "data_type": data_type,
                 "total_count": 0,
                 "results": [],
-                "formatted_output": f"Unknown data type: {data_type}"
+                "formatted_output": f"Unknown data type: {data_type}",
             }
 
     except Exception as e:
diff --git a/mcp_servers/hummingbot_api/tools/market_data.py b/mcp_servers/hummingbot_api/tools/market_data.py
index f2f807cb..992c2085 100644
--- a/mcp_servers/hummingbot_api/tools/market_data.py
+++ b/mcp_servers/hummingbot_api/tools/market_data.py
@@ -4,6 +4,7 @@
 This module provides the core business logic for market data operations including
 prices, candles, funding rates, and order books.
 """
+
 from datetime import datetime
 from typing import Any, Literal
 
@@ -230,7 +231,9 @@ async def get_order_book(
     else:
         # Handle query-based requests
         if query_value is None:
-            raise ValueError(f"query_value must be provided for query_type '{query_type}'")
+            raise ValueError(
+                f"query_value must be provided for query_type '{query_type}'"
+            )
 
         # Execute appropriate query
         if query_type == "volume_for_price":
diff --git a/mcp_servers/hummingbot_api/tools/portfolio.py b/mcp_servers/hummingbot_api/tools/portfolio.py
index d0224648..88ff5778 100644
--- a/mcp_servers/hummingbot_api/tools/portfolio.py
+++ b/mcp_servers/hummingbot_api/tools/portfolio.py
@@ -6,13 +6,14 @@
 - Perpetual positions from CEX
 - LP positions (CLMM) from blockchain DEXs
 """
+
 import asyncio
 import logging
 from typing import Any, Literal
 
 from mcp_servers.hummingbot_api.exceptions import ToolError
-from mcp_servers.hummingbot_api.hummingbot_client import HummingbotClient
 from mcp_servers.hummingbot_api.formatters import format_portfolio_as_table
+from mcp_servers.hummingbot_api.hummingbot_client import HummingbotClient
 from mcp_servers.hummingbot_api.tools import trading as trading_tools
 
 logger = logging.getLogger("hummingbot-mcp")
@@ -69,6 +70,7 @@ async def get_portfolio_overview(
 
         # Task 1: Get token balances
         if include_balances:
+
             async def get_balances():
                 try:
                     return await client.portfolio.get_state(
@@ -85,6 +87,7 @@ async def get_balances():
 
         # Task 2: Get perpetual positions
         if include_perp_positions:
+
             async def get_perp_positions():
                 try:
                     return await trading_tools.get_positions(
@@ -102,6 +105,7 @@ async def get_perp_positions():
 
         # Task 3: Get LP positions (CLMM) - Real-time from blockchain
         if include_lp_positions:
+
             async def get_lp_positions():
                 try:
                     # Step 1: Get all unique pools from database (to know which pools to query)
@@ -145,10 +149,12 @@ async def fetch_pool(connector, network, pool_address):
                                     connector=connector,
                                     network=network,
                                     pool_address=pool_address,
-                                    wallet_address=None  # Uses default wallet
+                                    wallet_address=None,  # Uses default wallet
                                 )
                             except Exception as e:
-                                logger.warning(f"Failed to get positions for pool {pool_address}: {str(e)}")
+                                logger.warning(
+                                    f"Failed to get positions for pool {pool_address}: {str(e)}"
+                                )
                                 return None
 
                     pool_results = await asyncio.gather(
@@ -179,6 +185,7 @@ async def fetch_pool(connector, network, pool_address):
 
         # Task 4: Get active orders
         if include_active_orders:
+
             async def get_active_orders():
                 try:
                     return await trading_tools.search_orders(
@@ -230,21 +237,29 @@ async def get_active_orders():
             total_value += balance_value
 
             # Format balances as table
-            balances_table = format_portfolio_as_table(balances_data) if balances_data else "No balances found"
-
-            sections.append({
-                "title": "Token Balances",
-                "content": balances_table,
-                "total_value": balance_value,
-                "emoji": "💰"
-            })
+            balances_table = (
+                format_portfolio_as_table(balances_data)
+                if balances_data
+                else "No balances found"
+            )
+
+            sections.append(
+                {
+                    "title": "Token Balances",
+                    "content": balances_table,
+                    "total_value": balance_value,
+                    "emoji": "💰",
+                }
+            )
         elif include_balances and not data.get("balances"):
-            sections.append({
-                "title": "Token Balances",
-                "content": "Failed to fetch balances",
-                "total_value": 0.0,
-                "emoji": "⚠️"
-            })
+            sections.append(
+                {
+                    "title": "Token Balances",
+                    "content": "Failed to fetch balances",
+                    "total_value": 0.0,
+                    "emoji": "⚠️",
+                }
+            )
 
         # ============================================
         # SECTION 2: Perpetual Positions
@@ -260,26 +275,32 @@ async def get_active_orders():
                 # Note: You'll need to parse the table or enhance trading_tools.get_positions
                 # to return structured data with PnL values
 
-                sections.append({
-                    "title": "Perpetual Positions",
-                    "content": perp_table,
-                    "total_positions": total_positions,
-                    "emoji": "📊"
-                })
+                sections.append(
+                    {
+                        "title": "Perpetual Positions",
+                        "content": perp_table,
+                        "total_positions": total_positions,
+                        "emoji": "📊",
+                    }
+                )
             else:
-                sections.append({
+                sections.append(
+                    {
+                        "title": "Perpetual Positions",
+                        "content": "No perpetual positions found",
+                        "total_positions": 0,
+                        "emoji": "📊",
+                    }
+                )
+        elif include_perp_positions and not data.get("perp_positions"):
+            sections.append(
+                {
                     "title": "Perpetual Positions",
-                    "content": "No perpetual positions found",
+                    "content": "Failed to fetch perpetual positions",
                     "total_positions": 0,
-                    "emoji": "📊"
-                })
-        elif include_perp_positions and not data.get("perp_positions"):
-            sections.append({
-                "title": "Perpetual Positions",
-                "content": "Failed to fetch perpetual positions",
-                "total_positions": 0,
-                "emoji": "⚠️"
-            })
+                    "emoji": "⚠️",
+                }
+            )
 
         # ============================================
         # SECTION 3: LP Positions (CLMM) - Real-time data
@@ -297,7 +318,9 @@ async def get_active_orders():
                 # Format LP positions - show all open positions with real-time data
                 if open_positions:
                     lp_table_lines = ["Status: OPEN positions", ""]
-                    lp_table_lines.append("connector | trading_pair | lower_price | upper_price | position_address")
+                    lp_table_lines.append(
+                        "connector | trading_pair | lower_price | upper_price | position_address"
+                    )
                     lp_table_lines.append("-" * 100)
 
                     for pos in open_positions[:10]:  # Show up to 10 open positions
@@ -308,13 +331,17 @@ async def get_active_orders():
                         position_address = pos.get("position_address", "N/A")
 
                         # Format prices
-                        if lower_price != "N/A" and isinstance(lower_price, (int, float, str)):
+                        if lower_price != "N/A" and isinstance(
+                            lower_price, (int, float, str)
+                        ):
                             try:
                                 lower_price = f"{float(lower_price):.4f}"
                             except:
                                 pass
 
-                        if upper_price != "N/A" and isinstance(upper_price, (int, float, str)):
+                        if upper_price != "N/A" and isinstance(
+                            upper_price, (int, float, str)
+                        ):
                             try:
                                 upper_price = f"{float(upper_price):.4f}"
                             except:
@@ -322,40 +349,50 @@ async def get_active_orders():
 
                         # Truncate position address
                         if position_address != "N/A" and len(position_address) > 20:
-                            position_address = f"{position_address[:8]}...{position_address[-6:]}"
+                            position_address = (
+                                f"{position_address[:8]}...{position_address[-6:]}"
+                            )
 
                         lp_table_lines.append(
                             f"{connector[:10]:10} | {trading_pair[:15]:15} | {str(lower_price)[:11]:11} | {str(upper_price)[:11]:11} | {position_address}"
                         )
 
                     if len(open_positions) > 10:
-                        lp_table_lines.append(f"... and {len(open_positions) - 10} more open positions")
+                        lp_table_lines.append(
+                            f"... and {len(open_positions) - 10} more open positions"
+                        )
 
                     lp_table = "\n".join(lp_table_lines)
                 else:
                     lp_table = "No active LP positions found"
 
-                sections.append({
-                    "title": "LP Positions (CLMM)",
-                    "content": lp_table,
-                    "total_positions": total_lp_positions,
-                    "open_positions": len(open_positions),
-                    "emoji": "🏊"
-                })
+                sections.append(
+                    {
+                        "title": "LP Positions (CLMM)",
+                        "content": lp_table,
+                        "total_positions": total_lp_positions,
+                        "open_positions": len(open_positions),
+                        "emoji": "🏊",
+                    }
+                )
             else:
-                sections.append({
+                sections.append(
+                    {
+                        "title": "LP Positions (CLMM)",
+                        "content": "No LP positions found",
+                        "total_positions": 0,
+                        "emoji": "🏊",
+                    }
+                )
+        elif include_lp_positions and not data.get("lp_positions"):
+            sections.append(
+                {
                     "title": "LP Positions (CLMM)",
-                    "content": "No LP positions found",
+                    "content": "Failed to fetch LP positions",
                     "total_positions": 0,
-                    "emoji": "🏊"
-                })
-        elif include_lp_positions and not data.get("lp_positions"):
-            sections.append({
-                "title": "LP Positions (CLMM)",
-                "content": "Failed to fetch LP positions",
-                "total_positions": 0,
-                "emoji": "⚠️"
-            })
+                    "emoji": "⚠️",
+                }
+            )
 
         # ============================================
         # SECTION 4: Active Orders
@@ -367,26 +404,32 @@ async def get_active_orders():
                 orders_table = orders_data.get("orders_table", "No active orders found")
                 total_orders = orders_data.get("total_returned", 0)
 
-                sections.append({
-                    "title": "Active Orders",
-                    "content": orders_table,
-                    "total_orders": total_orders,
-                    "emoji": "📋"
-                })
+                sections.append(
+                    {
+                        "title": "Active Orders",
+                        "content": orders_table,
+                        "total_orders": total_orders,
+                        "emoji": "📋",
+                    }
+                )
             else:
-                sections.append({
+                sections.append(
+                    {
+                        "title": "Active Orders",
+                        "content": "No active orders found",
+                        "total_orders": 0,
+                        "emoji": "📋",
+                    }
+                )
+        elif include_active_orders and not data.get("active_orders"):
+            sections.append(
+                {
                     "title": "Active Orders",
-                    "content": "No active orders found",
+                    "content": "Failed to fetch active orders",
                     "total_orders": 0,
-                    "emoji": "📋"
-                })
-        elif include_active_orders and not data.get("active_orders"):
-            sections.append({
-                "title": "Active Orders",
-                "content": "Failed to fetch active orders",
-                "total_orders": 0,
-                "emoji": "⚠️"
-            })
+                    "emoji": "⚠️",
+                }
+            )
 
         # ============================================
         # Build final formatted output
@@ -404,23 +447,35 @@ async def get_active_orders():
         output_lines.append("-" * 80)
 
         if include_balances:
-            balance_section = next((s for s in sections if s["title"] == "Token Balances"), None)
+            balance_section = next(
+                (s for s in sections if s["title"] == "Token Balances"), None
+            )
             if balance_section and "total_value" in balance_section:
-                output_lines.append(f"Total Balance Value: ${balance_section['total_value']:.2f}")
+                output_lines.append(
+                    f"Total Balance Value: ${balance_section['total_value']:.2f}"
+                )
 
         if include_perp_positions:
-            perp_section = next((s for s in sections if s["title"] == "Perpetual Positions"), None)
+            perp_section = next(
+                (s for s in sections if s["title"] == "Perpetual Positions"), None
+            )
             if perp_section and "total_positions" in perp_section:
-                output_lines.append(f"Active Perpetual Positions: {perp_section['total_positions']}")
+                output_lines.append(
+                    f"Active Perpetual Positions: {perp_section['total_positions']}"
+                )
 
         if include_lp_positions:
-            lp_section = next((s for s in sections if s["title"] == "LP Positions (CLMM)"), None)
+            lp_section = next(
+                (s for s in sections if s["title"] == "LP Positions (CLMM)"), None
+            )
             if lp_section and "open_positions" in lp_section:
                 open_count = lp_section.get("open_positions", 0)
                 output_lines.append(f"Active LP Positions: {open_count}")
 
         if include_active_orders:
-            orders_section = next((s for s in sections if s["title"] == "Active Orders"), None)
+            orders_section = next(
+                (s for s in sections if s["title"] == "Active Orders"), None
+            )
             if orders_section and "total_orders" in orders_section:
                 output_lines.append(f"Active Orders: {orders_section['total_orders']}")
 
@@ -437,7 +492,7 @@ async def get_active_orders():
                 "include_perp_positions": include_perp_positions,
                 "include_lp_positions": include_lp_positions,
                 "include_active_orders": include_active_orders,
-            }
+            },
         }
 
     except Exception as e:
diff --git a/mcp_servers/hummingbot_api/tools/trading.py b/mcp_servers/hummingbot_api/tools/trading.py
index cf006668..11b9a279 100644
--- a/mcp_servers/hummingbot_api/tools/trading.py
+++ b/mcp_servers/hummingbot_api/tools/trading.py
@@ -6,9 +6,13 @@
 
 For order placement and cancellation, use `manage_executors` with `order_executor` type.
 """
+
 from typing import Any, Literal
 
-from mcp_servers.hummingbot_api.formatters import format_orders_as_table, format_positions_as_table
+from mcp_servers.hummingbot_api.formatters import (
+    format_orders_as_table,
+    format_positions_as_table,
+)
 
 
 async def set_position_mode_and_leverage(
@@ -48,7 +52,9 @@ async def set_position_mode_and_leverage(
             raise ValueError("Invalid position mode. Must be 'HEDGE' or 'ONE-WAY'")
 
         position_mode_result = await client.trading.set_position_mode(
-            account_name=account_name, connector_name=connector_name, position_mode=position_mode
+            account_name=account_name,
+            connector_name=connector_name,
+            position_mode=position_mode,
         )
         results["position_mode"] = position_mode_result
 
diff --git a/routines/market_scanner.py b/routines/market_scanner.py
index 0454502e..286c471c 100644
--- a/routines/market_scanner.py
+++ b/routines/market_scanner.py
@@ -390,6 +390,7 @@ async def run(config: Config, context: ContextTypes.DEFAULT_TYPE) -> str:
     text = format_results(classified, config.lookback_hours)
 
     import plotly.graph_objects as go
+
     from condor.reports import ReportBuilder
 
     def _to_table(items):
diff --git a/tests/test_custom_provider.py b/tests/test_custom_provider.py
index b3d4c403..280f86f7 100644
--- a/tests/test_custom_provider.py
+++ b/tests/test_custom_provider.py
@@ -50,7 +50,6 @@
     _custom_manage_keyboard,
 )
 
-
 # -- agent_key routing --
 
 
@@ -210,10 +209,16 @@ def test_active_agent_key_round_trips_through_preferences():
 def test_legacy_custom_llm_is_migrated():
     # The first iteration stored one endpoint in raw user_data, outside the
     # preference system. It should move across on first read, once.
-    user_data = {"custom_llm": {"base_url": "https://api.venice.ai/api/v1", "api_key": "sk-old"}}
+    user_data = {
+        "custom_llm": {"base_url": "https://api.venice.ai/api/v1", "api_key": "sk-old"}
+    }
     providers = get_custom_providers(user_data)
     assert providers == [
-        {"name": "Venice", "base_url": "https://api.venice.ai/api/v1", "api_key": "sk-old"}
+        {
+            "name": "Venice",
+            "base_url": "https://api.venice.ai/api/v1",
+            "api_key": "sk-old",
+        }
     ]
     assert "custom_llm" not in user_data
     assert get_custom_providers(user_data) == providers
@@ -228,8 +233,14 @@ def test_normalize_base_url_variants():
         == "https://api.venice.ai/api/v1"
     )
     assert normalize_base_url("api.venice.ai/api/v1/") == "https://api.venice.ai/api/v1"
-    assert normalize_base_url(" https://x.example/v1/chat/completions ") == "https://x.example/v1"
-    assert normalize_base_url("http://localhost:8000/v1/models") == "http://localhost:8000/v1"
+    assert (
+        normalize_base_url(" https://x.example/v1/chat/completions ")
+        == "https://x.example/v1"
+    )
+    assert (
+        normalize_base_url("http://localhost:8000/v1/models")
+        == "http://localhost:8000/v1"
+    )
 
 
 def test_normalize_base_url_rejects_garbage():
@@ -252,7 +263,9 @@ def test_normalize_base_url_blocks_metadata_endpoints():
 def test_normalize_base_url_allows_local_servers_by_default():
     # Local model servers are the most common use of this feature
     assert normalize_base_url("http://localhost:8000/v1") == "http://localhost:8000/v1"
-    assert normalize_base_url("http://192.168.1.5:1234/v1") == "http://192.168.1.5:1234/v1"
+    assert (
+        normalize_base_url("http://192.168.1.5:1234/v1") == "http://192.168.1.5:1234/v1"
+    )
 
 
 def test_normalize_base_url_strict_mode_blocks_private(monkeypatch):
@@ -569,7 +582,12 @@ async def scenario(_base):
 def test_fetch_models_reports_when_only_non_chat_models_exist():
     async def models_handler(request: web.Request) -> web.Response:
         return web.json_response(
-            {"data": [{"id": "bge-m3", "type": "embedding"}, {"id": "flux", "type": "image"}]}
+            {
+                "data": [
+                    {"id": "bge-m3", "type": "embedding"},
+                    {"id": "flux", "type": "image"},
+                ]
+            }
         )
 
     async def scenario():
diff --git a/tests/test_executor_mutation_errors.py b/tests/test_executor_mutation_errors.py
index a4a894bd..2860c7cd 100644
--- a/tests/test_executor_mutation_errors.py
+++ b/tests/test_executor_mutation_errors.py
@@ -29,10 +29,7 @@
     stop_executor,
 )
 from condor.web.models import CreateExecutorRequest, WebUser
-from condor.web.routes.executors import (
-    create_executor_endpoint,
-    stop_executor_endpoint,
-)
+from condor.web.routes.executors import create_executor_endpoint, stop_executor_endpoint
 
 # The internal address a shared-server trader must never be shown.
 BACKEND_URL = "http://10.0.0.7:8000/executors/create"
diff --git a/tests/test_executor_row_shared.py b/tests/test_executor_row_shared.py
index 3126418f..32751bb9 100644
--- a/tests/test_executor_row_shared.py
+++ b/tests/test_executor_row_shared.py
@@ -49,7 +49,10 @@ def test_current_price_precedence_is_the_union_of_both_chains():
         "close_price": 3.0,
         "held_position_orders": [{"price": 4.0}],
     }
-    assert build_executor_row({"current_price": 1.0, "custom_info": ci})["current_price"] == 1.0
+    assert (
+        build_executor_row({"current_price": 1.0, "custom_info": ci})["current_price"]
+        == 1.0
+    )
     assert build_executor_row({"custom_info": ci})["current_price"] == 2.0
     assert (
         build_executor_row(
diff --git a/tests/test_executors_period_summary.py b/tests/test_executors_period_summary.py
index 3c57abf6..1223f54b 100644
--- a/tests/test_executors_period_summary.py
+++ b/tests/test_executors_period_summary.py
@@ -17,10 +17,7 @@
 import pytest
 from fastapi import HTTPException
 
-from condor.fetchers.executors import (
-    EXECUTORS_PAGE_SIZE,
-    summarize_executors_by_quote,
-)
+from condor.fetchers.executors import EXECUTORS_PAGE_SIZE, summarize_executors_by_quote
 from condor.web.models import WebUser
 from condor.web.routes.executors import _summary_cache, executors_summary
 
@@ -119,7 +116,9 @@ def test_summary_spans_the_whole_history_not_one_page(summary_env):
 
     result = _summary("1D")
 
-    assert result.count == EXECUTORS_PAGE_SIZE + 120, "the window was truncated to a page"
+    assert (
+        result.count == EXECUTORS_PAGE_SIZE + 120
+    ), "the window was truncated to a page"
     assert result.pnl == pytest.approx(EXECUTORS_PAGE_SIZE + 120)
     assert len(client.calls) > 1, "a full-history total needs the whole walk"
     assert client.calls[0]["limit"] == EXECUTORS_PAGE_SIZE
@@ -127,7 +126,11 @@ def test_summary_spans_the_whole_history_not_one_page(summary_env):
 
 def test_executors_outside_the_window_are_excluded(summary_env):
     """A 1D total holds yesterday's executors and not last week's."""
-    rows = [_executor(0, age_days=0.5), _executor(1, age_days=3), _executor(2, age_days=20)]
+    rows = [
+        _executor(0, age_days=0.5),
+        _executor(1, age_days=3),
+        _executor(2, age_days=20),
+    ]
     summary_env(rows, {"USDT-USDT": 1.0})
 
     assert _summary("1D").count == 1
@@ -160,7 +163,9 @@ def test_an_unpriceable_quote_is_reported_not_hidden(summary_env):
 
     result = _summary("1D")
 
-    assert result.pnl == pytest.approx(4.0), "an unconvertible row is kept at face value"
+    assert result.pnl == pytest.approx(
+        4.0
+    ), "an unconvertible row is kept at face value"
     assert result.converted is False
 
 
diff --git a/tests/test_instance_history_pagination.py b/tests/test_instance_history_pagination.py
index 897d0861..fedeaeb7 100644
--- a/tests/test_instance_history_pagination.py
+++ b/tests/test_instance_history_pagination.py
@@ -157,7 +157,9 @@ def test_no_warning_when_the_walk_completes(caplog):
 
     assert len(hist) == 10
     assert len(handler.calls) == 1  # short page ends the walk
-    assert [r.getMessage() for r in caplog.records if r.levelno >= logging.WARNING] == []
+    assert [
+        r.getMessage() for r in caplog.records if r.levelno >= logging.WARNING
+    ] == []
 
 
 def test_stops_when_the_api_echoes_the_cursor_back():
diff --git a/tests/test_reports_attribution.py b/tests/test_reports_attribution.py
index b36ba7b9..912c894c 100644
--- a/tests/test_reports_attribution.py
+++ b/tests/test_reports_attribution.py
@@ -188,9 +188,7 @@ async def run(config, ctx):
         await b.save()
         return "done"
 
-    return SimpleNamespace(
-        name=name, source="global", config_class=Config, run_fn=run
-    )
+    return SimpleNamespace(name=name, source="global", config_class=Config, run_fn=run)
 
 
 def test_store_run_stamps_the_source_when_the_routine_forgot_it(reports_dir):
diff --git a/utils/auth.py b/utils/auth.py
index 5759c71b..cdb7ddb3 100644
--- a/utils/auth.py
+++ b/utils/auth.py
@@ -4,11 +4,7 @@
 from telegram import InlineKeyboardButton, InlineKeyboardMarkup, Update
 from telegram.ext import ContextTypes
 
-from config_manager import (
-    ServerPermission,
-    UserRole,
-    get_config_manager,
-)
+from config_manager import ServerPermission, UserRole, get_config_manager
 
 logger = logging.getLogger(__name__)
 
diff --git a/utils/deeplink.py b/utils/deeplink.py
index f949e9ba..2fdaae6c 100644
--- a/utils/deeplink.py
+++ b/utils/deeplink.py
@@ -25,11 +25,11 @@ def decode_deeplink(encoded: str) -> Tuple[Optional[dict], Optional[str]]:
     """
     try:
         # Add padding if needed and decode base64
-        padded = encoded + '=' * (4 - len(encoded) % 4)
-        decoded = base64.urlsafe_b64decode(padded).decode('utf-8')
+        padded = encoded + "=" * (4 - len(encoded) % 4)
+        decoded = base64.urlsafe_b64decode(padded).decode("utf-8")
 
         # Split pipe-delimited fields
-        parts = decoded.split('|')
+        parts = decoded.split("|")
         if len(parts) != 5:
             return None, f"Invalid payload format (expected 5 fields, got {len(parts)})"
 
@@ -42,11 +42,11 @@ def decode_deeplink(encoded: str) -> Tuple[Optional[dict], Optional[str]]:
             return None, "Invalid port number"
 
         return {
-            'name': name,
-            'host': host,
-            'port': port,
-            'username': username,
-            'password': password,
+            "name": name,
+            "host": host,
+            "port": port,
+            "username": username,
+            "password": password,
         }, None
 
     except Exception as e:
diff --git a/utils/transcribe.py b/utils/transcribe.py
index 2af72f1f..31e668d9 100644
--- a/utils/transcribe.py
+++ b/utils/transcribe.py
@@ -24,7 +24,9 @@ def _get_model(model_size: str = DEFAULT_MODEL):
         from faster_whisper import WhisperModel
 
         log.info("Loading Whisper model '%s' ...", model_size)
-        _models[model_size] = WhisperModel(model_size, device="cpu", compute_type="int8")
+        _models[model_size] = WhisperModel(
+            model_size, device="cpu", compute_type="int8"
+        )
         log.info("Whisper model loaded: %s", model_size)
     return _models[model_size]
 
@@ -74,6 +76,9 @@ def _transcribe_sync(
     text = " ".join(seg.text.strip() for seg in segments)
     log.info(
         "Transcribed %.1fs audio → %d chars (lang=%s, model=%s)",
-        info.duration, len(text), info.language, model_size,
+        info.duration,
+        len(text),
+        info.language,
+        model_size,
     )
     return text
diff --git a/utils/updater.py b/utils/updater.py
index fc3c661d..e5e9df78 100644
--- a/utils/updater.py
+++ b/utils/updater.py
@@ -20,11 +20,15 @@
 logger = logging.getLogger(__name__)
 
 # How often to check for updates (seconds)
-UPDATE_CHECK_INTERVAL = int(os.environ.get("UPDATE_CHECK_INTERVAL", "3600"))  # 1h default
+UPDATE_CHECK_INTERVAL = int(
+    os.environ.get("UPDATE_CHECK_INTERVAL", "3600")
+)  # 1h default
 
 CONDOR_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
 HUMMINGBOT_API_DIR = os.path.normpath(
-    os.environ.get("HUMMINGBOT_API_DIR", os.path.join(CONDOR_DIR, "..", "hummingbot-api"))
+    os.environ.get(
+        "HUMMINGBOT_API_DIR", os.path.join(CONDOR_DIR, "..", "hummingbot-api")
+    )
 )
 FRONTEND_DIR = os.path.join(CONDOR_DIR, "frontend")
 
@@ -124,7 +128,9 @@ async def check_for_updates(repo_dir: str = CONDOR_DIR) -> dict:
 
         # Get local and remote commits
         _, local = await _run_git("rev-parse", "--short", "HEAD", repo_dir=repo_dir)
-        _, remote = await _run_git("rev-parse", "--short", f"origin/{branch}", repo_dir=repo_dir)
+        _, remote = await _run_git(
+            "rev-parse", "--short", f"origin/{branch}", repo_dir=repo_dir
+        )
         result["local_commit"] = local
         result["remote_commit"] = remote
 
@@ -142,7 +148,10 @@ async def check_for_updates(repo_dir: str = CONDOR_DIR) -> dict:
         if commits_behind > 0:
             # Get log of new commits
             _, log = await _run_git(
-                "log", "--oneline", f"HEAD..origin/{branch}", "--max-count=10",
+                "log",
+                "--oneline",
+                f"HEAD..origin/{branch}",
+                "--max-count=10",
                 repo_dir=repo_dir,
             )
             result["commit_log"] = log
@@ -165,7 +174,10 @@ async def pull_updates(repo_dir: str = CONDOR_DIR) -> tuple[bool, str]:
     # Check for uncommitted changes
     rc, status = await _run_git("status", "--porcelain", repo_dir=repo_dir)
     if status:
-        return False, "Cannot update: there are uncommitted changes. Please commit or stash first."
+        return (
+            False,
+            "Cannot update: there are uncommitted changes. Please commit or stash first.",
+        )
 
     # Pull
     rc, output = await _run_git("pull", "origin", branch, repo_dir=repo_dir)
@@ -196,7 +208,11 @@ async def paths_changed(
     if old_commit == new_commit:
         return False
     rc, out = await _run_git(
-        "diff", "--name-only", f"{old_commit}..{new_commit}", "--", *paths,
+        "diff",
+        "--name-only",
+        f"{old_commit}..{new_commit}",
+        "--",
+        *paths,
         repo_dir=repo_dir,
     )
     if rc != 0:
@@ -303,15 +319,19 @@ def hb_api_available() -> bool:
     return os.path.isdir(HUMMINGBOT_API_DIR)
 
 
-async def get_docker_container_info(container_name: str = "hummingbot-api") -> dict | None:
+async def get_docker_container_info(
+    container_name: str = "hummingbot-api",
+) -> dict | None:
     """
     Inspect a Docker container and return basic info.
 
     Returns {"status", "started_at", "image"} or None if unavailable.
     """
     rc, output = await _run_cmd(
-        "docker", "inspect",
-        "--format", '{{.State.Status}}|{{.State.StartedAt}}|{{.Config.Image}}',
+        "docker",
+        "inspect",
+        "--format",
+        "{{.State.Status}}|{{.State.StartedAt}}|{{.Config.Image}}",
         container_name,
         timeout=30,
     )
@@ -367,7 +387,9 @@ async def update_hb_api() -> tuple[bool, str]:
 
     # Docker compose build
     rc, output = await _run_cmd(
-        "docker", "compose", "build",
+        "docker",
+        "compose",
+        "build",
         cwd=HUMMINGBOT_API_DIR,
         timeout=DOCKER_TIMEOUT,
     )
@@ -376,7 +398,10 @@ async def update_hb_api() -> tuple[bool, str]:
 
     # Docker compose up -d
     rc, output = await _run_cmd(
-        "docker", "compose", "up", "-d",
+        "docker",
+        "compose",
+        "up",
+        "-d",
         cwd=HUMMINGBOT_API_DIR,
         timeout=DOCKER_TIMEOUT,
     )

From 4fbd32203e95f81794f021d91763c06c70efa314 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Tue, 11 Aug 2026 23:01:48 +0300
Subject: [PATCH 009/116] Skip the format sweep in git blame
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The sweep rewrote 85 files without changing a line of logic, so it sits on top of
every blame it touched. The repo had no `.git-blame-ignore-revs`; this adds one
holding that single revision.

Git does not read the file automatically — it is per-clone opt-in, so the header
carries the `git config blame.ignoreRevsFile` line rather than assuming anyone
already ran it. GitHub's blame view honors the file without configuration.

READ-133
---
 .git-blame-ignore-revs | 6 ++++++
 1 file changed, 6 insertions(+)
 create mode 100644 .git-blame-ignore-revs

diff --git a/.git-blame-ignore-revs b/.git-blame-ignore-revs
new file mode 100644
index 00000000..ac49978c
--- /dev/null
+++ b/.git-blame-ignore-revs
@@ -0,0 +1,6 @@
+# Revisions listed here are skipped by `git blame`.
+# Enable locally with:
+#   git config blame.ignoreRevsFile .git-blame-ignore-revs
+#
+# (style) mechanical format sweep: isort then black over the Python tree (READ-133)
+3fa941fa3e49fb647b94916b92d11e481e7b7fdd

From 4c43a253454ae6b73ea61c6aebb751feca151746 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Tue, 11 Aug 2026 23:06:28 +0300
Subject: [PATCH 010/116] (fix) survive an executor whose config is null
 instead of 502ing the listing (CORR-131)

get_executor_type resolved the config with executor.get("config", executor),
whose default only fires when the key is absent. The backend emits rows with the
key present and explicitly null, so config became None and the first
source.get(...) raised AttributeError. The helper runs while building every
display row -- REST listing, WS broadcast and the agents rollup all go through
it -- so one malformed executor took down the whole page rather than degrading
to an unknown type for that single row.

Guard the resolution with the same isinstance check build_executor_row already
uses, falling back to the executor itself so a row carrying its fields at the
top level (and the start_price/stop_loss shape inference) resolves exactly as
before.
---
 condor/fetchers/executors.py            | 13 ++++-
 tests/test_executor_type_null_config.py | 71 +++++++++++++++++++++++++
 2 files changed, 83 insertions(+), 1 deletion(-)
 create mode 100644 tests/test_executor_type_null_config.py

diff --git a/condor/fetchers/executors.py b/condor/fetchers/executors.py
index e47422a1..2e37bc19 100644
--- a/condor/fetchers/executors.py
+++ b/condor/fetchers/executors.py
@@ -42,8 +42,19 @@ def get_executor_type(executor: Dict[str, Any]) -> str:
     """Determine executor type from its data.
 
     Returns the executor type label (e.g. 'grid', 'position', 'order', 'dca', 'lp').
+
+    Never raises: this runs while building every display row, so an executor
+    whose ``config`` is explicitly ``null`` (a shape the backend does emit) must
+    degrade to ``unknown`` for that one row instead of taking down the whole
+    listing.
     """
-    config = executor.get("config", executor)
+    # ``config`` is often present *and* null, so a ``dict.get`` default is not
+    # enough -- it only covers the absent key. Same isinstance guard as
+    # :func:`build_executor_row`, falling back to the executor itself so a row
+    # that carries its fields at the top level still resolves as before.
+    config = executor.get("config")
+    if not isinstance(config, dict):
+        config = executor
     for source in (config, executor):
         ex_type = source.get("type", "") or source.get("executor_type", "")
         if isinstance(ex_type, str) and ex_type:
diff --git a/tests/test_executor_type_null_config.py b/tests/test_executor_type_null_config.py
new file mode 100644
index 00000000..d16297f6
--- /dev/null
+++ b/tests/test_executor_type_null_config.py
@@ -0,0 +1,71 @@
+"""Tests for CORR-131: a null ``config`` must not take down the executor listing.
+
+``get_executor_type`` resolved the config with ``executor.get("config", executor)``,
+whose default only fires when the key is *absent*. The backend does emit rows with
+the key present and explicitly ``null``, which made ``config`` ``None`` and raised
+``AttributeError`` on the first ``source.get(...)``. Since the helper runs while
+building every display row (REST listing, WS broadcast, agents rollup), one
+malformed executor 502'd the whole listing instead of degrading that single row.
+"""
+
+from condor.fetchers.executors import build_executor_row, get_executor_type
+from condor.web.models import ExecutorInfo
+from condor.web.routes.executors import _offset_page
+
+# ── The crash this item closes ──
+
+
+def test_null_config_returns_a_label_instead_of_raising():
+    assert get_executor_type({"config": None}) == "unknown"
+
+
+def test_non_dict_config_returns_a_label_instead_of_raising():
+    assert get_executor_type({"config": "not-a-dict"}) == "unknown"
+    assert get_executor_type({"config": []}) == "unknown"
+
+
+def test_null_config_still_resolves_a_top_level_type():
+    """The fallback to the executor itself survives the null-safety guard."""
+    assert get_executor_type({"config": None, "type": "PositionExecutor"}) == "position"
+    assert (
+        get_executor_type({"config": None, "executor_type": "GridExecutor"}) == "grid"
+    )
+
+
+# ── The blast radius: one bad row must not sink the page ──
+
+
+def test_null_config_row_survives_the_display_row_transform():
+    row = build_executor_row({"id": "e1", "config": None})
+
+    assert row["id"] == "e1"
+    assert row["config"] == {}
+    assert ExecutorInfo.from_raw({"id": "e1", "config": None}).type == "unknown"
+
+
+def test_one_null_config_row_does_not_break_the_rest_of_the_listing():
+    """The 502: the listing loop raised on the bad row before reaching the good ones."""
+    rows = [
+        {"id": "good-1", "config": {"type": "PositionExecutor"}},
+        {"id": "bad", "config": None},
+        {"id": "good-2", "config": {"type": "GridExecutor"}},
+    ]
+
+    items = _offset_page(rows, 0, 10)["executors"]
+
+    assert [i.id for i in items] == ["good-1", "bad", "good-2"]
+    assert [i.type for i in items] == ["position", "unknown", "grid"]
+
+
+# ── Well-formed executors resolve exactly as before ──
+
+
+def test_type_resolution_is_unchanged_for_well_formed_executors():
+    assert get_executor_type({"config": {"type": "PositionExecutor"}}) == "position"
+    assert get_executor_type({"config": {"executor_type": "DCAExecutor"}}) == "dca"
+    assert get_executor_type({"type": "OrderExecutor"}) == "order"
+    # Shape inference, which reads the executor itself when there is no config key.
+    assert get_executor_type({"start_price": 1, "end_price": 2}) == "grid"
+    assert get_executor_type({"config": {"stop_loss": 0.01}}) == "position"
+    assert get_executor_type({"trailing_stop": {}}) == "position"
+    assert get_executor_type({}) == "unknown"

From d57d2053cde6ca42d037d18e0811a0dcf2794a7e Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Tue, 11 Aug 2026 23:11:21 +0300
Subject: [PATCH 011/116] (fix) fail closed when the executor pair validation
 itself breaks (CORR-132)

CORR-124 made validate_trading_pair fail closed, but the grid and position
wizards wrapped the whole validation block in a bare except Exception whose
fall-through still assigned and persisted the pair. Anything raised around
the validator -- the executors client lookup, the get_correct_pair_format
fallback read -- therefore landed an unvalidated pair in the executor config
with only a log warning, reopening the hole one refactor away.

Both panels now resolve a verdict inside the try and gate the write outside
it: a raised exception sets is_valid=False with a cause-naming message, so it
reaches the same suggestions screen an explicitly invalid pair does and never
touches the config. The stale "Allow through if validation fails" comment is
gone. The block stays identical in both files.

Users can now be blocked where they previously slipped through -- that is the
point of the item; no existing test depended on the fail-open path.
---
 handlers/executors/grid.py                    |  38 ++--
 handlers/executors/position.py                |  37 ++--
 ...st_executor_pair_validation_fail_closed.py | 190 ++++++++++++++++++
 3 files changed, 236 insertions(+), 29 deletions(-)
 create mode 100644 tests/test_executor_pair_validation_fail_closed.py

diff --git a/handlers/executors/grid.py b/handlers/executors/grid.py
index 343bf36a..3c5b22e0 100644
--- a/handlers/executors/grid.py
+++ b/handlers/executors/grid.py
@@ -446,27 +446,35 @@ async def handle_pair_input(
             context.user_data, client, connector, pair
         )
 
-        if not is_valid:
-            await _show_pair_suggestions(
-                update, context, pair, error_msg, suggestions, connector
-            )
-            return
-
-        # Use the correct pair format returned by validation
-        if correct_pair:
-            pair = correct_pair
-        else:
+        if is_valid and not correct_pair:
             # Fallback: Get correctly formatted pair from trading rules
             trading_rules = await get_trading_rules(
                 context.user_data, client, connector
             )
-            fallback_pair = get_correct_pair_format(trading_rules, pair)
-            if fallback_pair:
-                pair = fallback_pair
+            correct_pair = get_correct_pair_format(trading_rules, pair)
 
     except Exception as e:
-        logger.warning(f"Could not validate trading pair: {e}")
-        # Allow through if validation fails (e.g. no trading rules)
+        # Fail closed: anything that breaks around the validator leaves the pair
+        # unvalidated, so it must not reach the config. The user gets the same
+        # surface as an explicitly invalid pair.
+        logger.warning(f"Could not validate trading pair '{pair}' on {connector}: {e}")
+        is_valid = False
+        error_msg = (
+            f"Could not reach {connector} to validate the pair. "
+            "Try again in a moment."
+        )
+        suggestions = []
+        correct_pair = None
+
+    if not is_valid:
+        await _show_pair_suggestions(
+            update, context, pair, error_msg, suggestions, connector
+        )
+        return
+
+    # Use the correct pair format resolved during validation
+    if correct_pair:
+        pair = correct_pair
 
     config["trading_pair"] = pair
     set_executor_config(context, config)
diff --git a/handlers/executors/position.py b/handlers/executors/position.py
index ef4ee23c..82726ce6 100644
--- a/handlers/executors/position.py
+++ b/handlers/executors/position.py
@@ -440,26 +440,35 @@ async def handle_pair_input(
             context.user_data, client, connector, pair
         )
 
-        if not is_valid:
-            await _show_pair_suggestions(
-                update, context, pair, error_msg, suggestions, connector
-            )
-            return
-
-        # Use the correct pair format returned by validation
-        if correct_pair:
-            pair = correct_pair
-        else:
+        if is_valid and not correct_pair:
             # Fallback: Get correctly formatted pair from trading rules
             trading_rules = await get_trading_rules(
                 context.user_data, client, connector
             )
-            fallback_pair = get_correct_pair_format(trading_rules, pair)
-            if fallback_pair:
-                pair = fallback_pair
+            correct_pair = get_correct_pair_format(trading_rules, pair)
 
     except Exception as e:
-        logger.warning(f"Could not validate trading pair: {e}")
+        # Fail closed: anything that breaks around the validator leaves the pair
+        # unvalidated, so it must not reach the config. The user gets the same
+        # surface as an explicitly invalid pair.
+        logger.warning(f"Could not validate trading pair '{pair}' on {connector}: {e}")
+        is_valid = False
+        error_msg = (
+            f"Could not reach {connector} to validate the pair. "
+            "Try again in a moment."
+        )
+        suggestions = []
+        correct_pair = None
+
+    if not is_valid:
+        await _show_pair_suggestions(
+            update, context, pair, error_msg, suggestions, connector
+        )
+        return
+
+    # Use the correct pair format resolved during validation
+    if correct_pair:
+        pair = correct_pair
 
     config["trading_pair"] = pair
     set_executor_config(context, config)
diff --git a/tests/test_executor_pair_validation_fail_closed.py b/tests/test_executor_pair_validation_fail_closed.py
new file mode 100644
index 00000000..3dfe13cb
--- /dev/null
+++ b/tests/test_executor_pair_validation_fail_closed.py
@@ -0,0 +1,190 @@
+"""Tests for CORR-132: the executor panels must fail closed around the validator.
+
+[[CORR-124]] made ``validate_trading_pair`` itself fail closed, but the grid and
+position wizards still wrapped the whole validation block in a bare
+``except Exception`` whose fall-through path assigned and persisted the pair
+anyway. Anything raised *around* the validator — the API client lookup, the
+``get_correct_pair_format`` fallback read — therefore still landed an
+unvalidated pair in the executor config with only a log warning.
+
+Both panels now treat a raised exception exactly like an invalid pair: nothing
+is persisted, and the user lands on the same suggestions screen. The two causes
+stay distinguishable in the message the user reads.
+"""
+
+import asyncio
+from types import SimpleNamespace
+
+import pytest
+
+from handlers.executors import grid, position
+
+RULES = {"BTC-USDT": {"min_order_size": 1}}
+
+# Each panel duplicates the block verbatim, so every test runs against both.
+PANELS = [
+    pytest.param((grid, "show_step_2_combined"), id="grid"),
+    pytest.param((position, "show_step_2_config"), id="position"),
+]
+
+both_panels = pytest.mark.parametrize("panel", PANELS, indirect=True)
+
+
+def _boom():
+    raise RuntimeError("502 Bad Gateway")
+
+
+class _Panel:
+    """Drives one wizard's ``handle_pair_input`` with its collaborators stubbed."""
+
+    def __init__(self, module, step_2_name, monkeypatch):
+        self.module = module
+        self.monkeypatch = monkeypatch
+        self.shown = None
+        self.reached_step_2 = False
+        self.context = SimpleNamespace(
+            user_data={
+                "executor_config_params": {"connector_name": "binance_perpetual"}
+            }
+        )
+        self.update = SimpleNamespace(
+            effective_chat=SimpleNamespace(id=1), message=None, callback_query=None
+        )
+
+        async def show_pair_suggestions(
+            update, context, input_pair, error_msg, suggestions, connector
+        ):
+            self.shown = {
+                "pair": input_pair,
+                "error_msg": error_msg,
+                "suggestions": suggestions,
+                "connector": connector,
+            }
+
+        async def step_2(update, context):
+            self.reached_step_2 = True
+
+        self._patch("_show_pair_suggestions", show_pair_suggestions)
+        self._patch(step_2_name, step_2)
+        self.set_client(lambda: (object(), None))
+        self.set_validator(lambda: (True, None, [], "BTC-USDT"))
+        self.set_trading_rules(lambda: RULES)
+
+    def _patch(self, name, fn):
+        self.monkeypatch.setattr(self.module, name, fn)
+
+    def set_client(self, produce):
+        async def get_executors_client(chat_id, user_data):
+            return produce()
+
+        self._patch("get_executors_client", get_executors_client)
+
+    def set_validator(self, produce):
+        async def validate_trading_pair(user_data, client, connector, pair):
+            return produce()
+
+        self._patch("validate_trading_pair", validate_trading_pair)
+
+    def set_trading_rules(self, produce):
+        async def get_trading_rules(user_data, client, connector):
+            return produce()
+
+        self._patch("get_trading_rules", get_trading_rules)
+
+    def run(self, pair):
+        asyncio.run(self.module.handle_pair_input(self.update, self.context, pair))
+
+    @property
+    def config(self):
+        return self.context.user_data["executor_config_params"]
+
+
+@pytest.fixture
+def panel(request, monkeypatch):
+    module, step_2_name = request.param
+    return _Panel(module, step_2_name, monkeypatch)
+
+
+@both_panels
+def test_a_raising_validator_does_not_persist_the_pair(panel):
+    """The whole point: an exception must not wave an unvalidated pair through."""
+    panel.set_validator(_boom)
+
+    panel.run("DOGE-USDT")
+
+    assert "trading_pair" not in panel.config
+    assert panel.reached_step_2 is False
+    assert panel.shown is not None
+
+
+@both_panels
+def test_a_failure_before_the_validator_does_not_persist_the_pair(panel):
+    """The client lookup is inside the block, so its failure must fail closed too."""
+    panel.set_client(_boom)
+
+    panel.run("DOGE-USDT")
+
+    assert "trading_pair" not in panel.config
+    assert panel.reached_step_2 is False
+    assert panel.shown is not None
+
+
+@both_panels
+def test_a_raising_pair_format_fallback_does_not_persist_the_pair(panel):
+    """The fallback read runs after a valid verdict, and still gates the write."""
+    panel.set_validator(lambda: (True, None, [], None))
+    panel.set_trading_rules(_boom)
+
+    panel.run("BTC-USDT")
+
+    assert "trading_pair" not in panel.config
+    assert panel.reached_step_2 is False
+    assert panel.shown is not None
+
+
+@both_panels
+def test_a_crash_and_an_invalid_pair_share_the_surface_but_not_the_cause(panel):
+    """Same screen for both, but the user can still tell them apart."""
+    panel.set_validator(lambda: (False, "DOGE-USDT not found", ["DOGE-USDC"], None))
+    panel.run("DOGE-USDT")
+    invalid = panel.shown
+
+    panel.shown = None
+    panel.set_validator(_boom)
+    panel.run("DOGE-USDT")
+    crashed = panel.shown
+
+    # Same surface: neither persists, both land on the suggestions screen.
+    assert "trading_pair" not in panel.config
+    assert invalid is not None
+    assert crashed is not None
+
+    # Different cause: "that pair is wrong" vs "we could not check".
+    assert invalid["error_msg"] == "DOGE-USDT not found"
+    assert invalid["suggestions"] == ["DOGE-USDC"]
+    assert "could not reach" in crashed["error_msg"].lower()
+    assert "binance_perpetual" in crashed["error_msg"]
+    assert crashed["suggestions"] == []
+
+
+@both_panels
+def test_a_validated_pair_is_still_persisted_in_the_exchange_format(panel):
+    """Fail-closed must not block the happy path."""
+    panel.set_validator(lambda: (True, None, [], "BTC-USDT"))
+
+    panel.run("btc/usdt")
+
+    assert panel.config["trading_pair"] == "BTC-USDT"
+    assert panel.reached_step_2 is True
+    assert panel.shown is None
+
+
+@both_panels
+def test_the_pair_format_fallback_still_applies_when_validation_returns_none(panel):
+    """A valid verdict without a formatted pair still goes through the fallback."""
+    panel.set_validator(lambda: (True, None, [], None))
+
+    panel.run("BTC-USDT")
+
+    assert panel.config["trading_pair"] == "BTC-USDT"
+    assert panel.reached_step_2 is True

From 138dab7756697aac87a3681209bfcf26142736a9 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Tue, 11 Aug 2026 23:21:47 +0300
Subject: [PATCH 012/116] (sec) four more route modules fail without naming the
 backend (SEC-130)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`str(e)` on an aiohttp client exception embeds the backend's own URL, so
raising it as an HTTPException detail publishes the internal host and port
to anyone who can provoke a backend blip. SEC-116 removed that from the
executor mutations and SEC-126 from the executor reads; bots, settings,
market and controller_performance were still doing it at all 34 of their
backend call boundaries.

The mapping that executors.py had kept module-private moves to
condor/web/routes/_errors.py as `upstream_error`, so there is one
implementation rather than five. It still describes the failure with
`describe_executor_error` — no second sanitizer — and keeps the same
contract: an upstream 4xx is the caller's own bad request and stays 400,
anything else is 502. The settings endpoints previously answered 500 for
both; they now match the rest.

Every converted site logs the exception first. The address belongs in the
server log, where an operator needs it; only the client loses it.

Left alone: the `detail=str(e)` sites that catch a named domain exception
(a rejected identifier, an unparseable provider URL) rather than a bare
`Exception`. Those messages are our own text about the caller's own input
and carry no address — sessions.py and agents.py are untouched for the
same reason.
---
 condor/web/routes/_errors.py                |  40 +++
 condor/web/routes/bots.py                   |  80 +++++-
 condor/web/routes/controller_performance.py |   9 +-
 condor/web/routes/executors.py              |  43 +--
 condor/web/routes/market.py                 |  39 ++-
 condor/web/routes/settings.py               |  46 ++-
 tests/test_route_upstream_errors.py         | 297 ++++++++++++++++++++
 7 files changed, 485 insertions(+), 69 deletions(-)
 create mode 100644 condor/web/routes/_errors.py
 create mode 100644 tests/test_route_upstream_errors.py

diff --git a/condor/web/routes/_errors.py b/condor/web/routes/_errors.py
new file mode 100644
index 00000000..0bdd4c2c
--- /dev/null
+++ b/condor/web/routes/_errors.py
@@ -0,0 +1,40 @@
+"""One mapping from a failed upstream call to a response that leaks nothing.
+
+``str(exc)`` on an ``aiohttp`` client exception embeds the backend's own URL, so
+handing it to a browser as an ``HTTPException`` detail publishes the internal
+host and port to anyone who can provoke a backend blip — a timeout, a refused
+connection, an upstream 5xx. SEC-116 established the remedy for the executor
+mutations and SEC-126 extended it to the executor reads; this module is that
+same remedy lifted out of ``routes/executors.py`` so every route module shares
+one implementation instead of growing a second sanitizer.
+
+The description itself still comes from :func:`condor.fetchers.describe_executor_error`,
+which reads the safe pieces off the exception's attributes (``status`` is the
+code the API answered with, ``message`` is the API's own ``detail``) and
+collapses a transport failure — which has neither — to a generic line.
+"""
+
+from __future__ import annotations
+
+from fastapi import HTTPException
+
+from condor.fetchers.executors import describe_executor_error
+
+__all__ = ["upstream_error"]
+
+
+def upstream_error(action: str, exc: Exception) -> HTTPException:
+    """Map a failed backend call to an ``HTTPException`` that leaks nothing.
+
+    An upstream 4xx is the caller's own bad request and stays a 400; anything
+    else — an upstream 5xx, a timeout, a refused connection — is this gateway
+    failing to reach its backend, so 502. The detail carries the API's message
+    but never the raw exception.
+
+    Callers log the exception before raising: the address belongs in the server
+    log, where an operator needs it, not in the response, where a trader on a
+    shared server would read it.
+    """
+    status, message = describe_executor_error(exc)
+    code = 400 if status is not None and 400 <= status < 500 else 502
+    return HTTPException(status_code=code, detail=f"{action}: {message}")
diff --git a/condor/web/routes/bots.py b/condor/web/routes/bots.py
index e113526d..17b27b1c 100644
--- a/condor/web/routes/bots.py
+++ b/condor/web/routes/bots.py
@@ -22,6 +22,7 @@
     DeployBotRequest,
     WebUser,
 )
+from condor.web.routes._errors import upstream_error
 from config_manager import get_config_manager
 from handlers.bots._shared import clean_config_for_save
 
@@ -405,7 +406,8 @@ async def get_bot(name: str, bot_id: str, user: WebUser = Depends(get_current_us
     try:
         result = await client.bot_orchestration.get_bot_status(bot_id)
     except Exception as e:
-        raise HTTPException(status_code=502, detail=str(e))
+        logger.exception("Failed to fetch status for bot '%s' on '%s'", bot_id, name)
+        raise upstream_error("Failed to fetch bot status", e)
 
     if not isinstance(result, dict):
         raise HTTPException(status_code=404, detail="Bot not found")
@@ -511,7 +513,10 @@ async def get_controller_config(
     try:
         result = await client.controllers.get_controller_config(config_id)
     except Exception as e:
-        raise HTTPException(status_code=502, detail=str(e))
+        logger.exception(
+            "Failed to fetch controller config '%s' from '%s'", config_id, name
+        )
+        raise upstream_error("Failed to fetch controller config", e)
 
     if not isinstance(result, dict):
         raise HTTPException(status_code=404, detail="Config not found")
@@ -584,7 +589,10 @@ async def update_controller_config(
     except HTTPException:
         raise
     except Exception as e:
-        raise HTTPException(status_code=502, detail=str(e))
+        logger.exception(
+            "Failed to update controller config '%s' on '%s'", config_id, name
+        )
+        raise upstream_error("Failed to save controller config", e)
 
     return {"updated": True, "config_id": config_id, "result": result}
 
@@ -610,7 +618,13 @@ async def get_controller_source(
             controller_type, controller_name
         )
     except Exception as e:
-        raise HTTPException(status_code=502, detail=str(e))
+        logger.exception(
+            "Failed to fetch controller source '%s/%s' from '%s'",
+            controller_type,
+            controller_name,
+            name,
+        )
+        raise upstream_error("Failed to fetch controller source", e)
 
     if isinstance(result, str):
         source = result
@@ -656,7 +670,13 @@ async def update_controller_source(
             controller_type, controller_name, {"content": source}
         )
     except Exception as e:
-        raise HTTPException(status_code=502, detail=str(e))
+        logger.exception(
+            "Failed to update controller source '%s/%s' on '%s'",
+            controller_type,
+            controller_name,
+            name,
+        )
+        raise upstream_error("Failed to save controller source", e)
 
     return {"updated": True, "result": result}
 
@@ -681,7 +701,13 @@ async def get_controller_config_template(
             controller_type, controller_name
         )
     except Exception as e:
-        raise HTTPException(status_code=502, detail=str(e))
+        logger.exception(
+            "Failed to fetch config template for '%s/%s' from '%s'",
+            controller_type,
+            controller_name,
+            name,
+        )
+        raise upstream_error("Failed to fetch controller config template", e)
 
     if not result:
         raise HTTPException(status_code=404, detail="Template not found")
@@ -730,7 +756,10 @@ async def create_controller_config(
             config_id, clean_body
         )
     except Exception as e:
-        raise HTTPException(status_code=502, detail=str(e))
+        logger.exception(
+            "Failed to create controller config '%s' on '%s'", config_id, name
+        )
+        raise upstream_error("Failed to save controller config", e)
 
     return {"created": True, "config_id": config_id, "result": result}
 
@@ -750,7 +779,10 @@ async def delete_controller_config(
     try:
         result = await client.controllers.delete_controller_config(config_id)
     except Exception as e:
-        raise HTTPException(status_code=502, detail=str(e))
+        logger.exception(
+            "Failed to delete controller config '%s' from '%s'", config_id, name
+        )
+        raise upstream_error("Failed to delete controller config", e)
 
     return {"deleted": True, "config_id": config_id, "result": result}
 
@@ -773,7 +805,13 @@ async def delete_controller(
             controller_type, controller_name
         )
     except Exception as e:
-        raise HTTPException(status_code=502, detail=str(e))
+        logger.exception(
+            "Failed to delete controller '%s/%s' from '%s'",
+            controller_type,
+            controller_name,
+            name,
+        )
+        raise upstream_error("Failed to delete controller", e)
 
     return {
         "deleted": True,
@@ -806,7 +844,8 @@ async def deploy_bot_endpoint(
             max_controller_drawdown_quote=body.max_controller_drawdown_quote,
         )
     except Exception as e:
-        raise HTTPException(status_code=502, detail=str(e))
+        logger.exception("Failed to deploy bot '%s' on '%s'", body.bot_name, name)
+        raise upstream_error("Failed to deploy bot", e)
 
     return result
 
@@ -834,7 +873,8 @@ async def stop_bot_endpoint(
         )
     except Exception as e:
         clear_bot_stopping(name, bot_name)
-        raise HTTPException(status_code=502, detail=str(e))
+        logger.exception("Failed to stop bot '%s' on '%s'", bot_name, name)
+        raise upstream_error("Failed to stop bot", e)
 
     return result
 
@@ -865,7 +905,10 @@ async def stop_controllers_endpoint(
             controller_names=body.controller_names,
         )
     except Exception as e:
-        raise HTTPException(status_code=502, detail=str(e))
+        logger.exception(
+            "Failed to stop controllers on bot '%s' of '%s'", bot_name, name
+        )
+        raise upstream_error("Failed to stop controllers", e)
 
     return result
 
@@ -893,7 +936,10 @@ async def start_controllers_endpoint(
             controller_names=body.controller_names,
         )
     except Exception as e:
-        raise HTTPException(status_code=502, detail=str(e))
+        logger.exception(
+            "Failed to start controllers on bot '%s' of '%s'", bot_name, name
+        )
+        raise upstream_error("Failed to start controllers", e)
 
     return result
 
@@ -934,7 +980,13 @@ async def update_bot_controller_config_endpoint(
     except HTTPException:
         raise
     except Exception as e:
-        raise HTTPException(status_code=502, detail=str(e))
+        logger.exception(
+            "Failed to update controller config '%s' on bot '%s' of '%s'",
+            config_id,
+            bot_name,
+            name,
+        )
+        raise upstream_error("Failed to save controller config", e)
 
     return {
         "updated": True,
diff --git a/condor/web/routes/controller_performance.py b/condor/web/routes/controller_performance.py
index 2150a940..eaee3ea9 100644
--- a/condor/web/routes/controller_performance.py
+++ b/condor/web/routes/controller_performance.py
@@ -16,6 +16,7 @@
     ControllerPerformanceSnapshot,
     WebUser,
 )
+from condor.web.routes._errors import upstream_error
 from config_manager import get_config_manager
 
 logger = logging.getLogger(__name__)
@@ -136,8 +137,8 @@ async def _fetch_perf() -> dict[str, dict]:
     try:
         result, perf_by_bot = await asyncio.gather(_fetch_runs(), _fetch_perf())
     except Exception as e:
-        logger.warning("Failed to fetch bot runs from '%s': %s", name, e)
-        raise HTTPException(status_code=502, detail=str(e))
+        logger.exception("Failed to fetch bot runs from '%s'", name)
+        raise upstream_error("Failed to fetch bot runs", e)
 
     runs_list = _extract_runs_list(result)
 
@@ -165,8 +166,8 @@ async def delete_bot_run(
     try:
         result = await client.bot_orchestration.delete_bot_run(bot_run_id)
     except Exception as e:
-        logger.warning("Failed to delete bot run %d from '%s': %s", bot_run_id, name, e)
-        raise HTTPException(status_code=502, detail=str(e))
+        logger.exception("Failed to delete bot run %d from '%s'", bot_run_id, name)
+        raise upstream_error("Failed to delete bot run", e)
 
     return {"deleted": True, "bot_run_id": bot_run_id, "result": result}
 
diff --git a/condor/web/routes/executors.py b/condor/web/routes/executors.py
index b81d9d34..4ab74935 100644
--- a/condor/web/routes/executors.py
+++ b/condor/web/routes/executors.py
@@ -8,11 +8,7 @@
 logger = logging.getLogger(__name__)
 
 
-from condor.fetchers.executors import (
-    EXECUTORS_POLL_MAX,
-    MAX_EXECUTORS_FETCH,
-    describe_executor_error,
-)
+from condor.fetchers.executors import EXECUTORS_POLL_MAX, MAX_EXECUTORS_FETCH
 from condor.fetchers.executors import extract_executors_list as _extract_executors_list
 from condor.fetchers.executors import fetch_all_executors, summarize_executors_by_quote
 from condor.web.auth import get_current_user
@@ -22,6 +18,7 @@
     ExecutorPeriodSummary,
     WebUser,
 )
+from condor.web.routes._errors import upstream_error
 from config_manager import get_config_manager
 
 router = APIRouter(tags=["executors"])
@@ -45,24 +42,6 @@
 _summary_cache: dict[tuple[str, str], tuple[float, ExecutorPeriodSummary]] = {}
 
 
-def _executor_error(action: str, exc: Exception) -> HTTPException:
-    """Map an executor call failure to an HTTPException that leaks nothing.
-
-    An upstream 4xx is the caller's own bad request and stays a 400; anything
-    else — an upstream 5xx, a timeout, a refused connection — is the gateway
-    failing, so 502. The detail carries the API's message but never the raw
-    exception, whose string embeds the backend URL and port.
-
-    Reads go through this too, not only mutations: the listing endpoints are the
-    dashboard's hottest path, so any backend blip is the most reachable way for
-    that address to reach a browser. Callers log the exception before raising —
-    the address belongs in the server log, not in the response.
-    """
-    status, message = describe_executor_error(exc)
-    code = 400 if status is not None and 400 <= status < 500 else 502
-    return HTTPException(status_code=code, detail=f"{action}: {message}")
-
-
 @router.get("/servers/{name}/executors", response_model=list[ExecutorInfo])
 async def list_executors(
     name: str,
@@ -106,7 +85,7 @@ async def list_executors(
             result = executors_list
         except Exception as e:
             logger.exception("Failed to fetch executors for server %s", name)
-            raise _executor_error("Failed to fetch executors", e)
+            raise upstream_error("Failed to fetch executors", e)
     else:
         try:
             result = await get_server_data_service().get_or_fetch(
@@ -114,7 +93,7 @@ async def list_executors(
             )
         except Exception as e:
             logger.exception("Failed to fetch executors for server %s", name)
-            raise _executor_error("Failed to fetch executors", e)
+            raise upstream_error("Failed to fetch executors", e)
         if result is None:
             raise HTTPException(status_code=502, detail="Failed to fetch executors")
 
@@ -198,7 +177,7 @@ async def list_executors_page(
                 rows = await fetch_all_executors(client, max_items=offset + limit + 1)
             except Exception as e:
                 logger.exception("Failed to page executors for server %s", name)
-                raise _executor_error("Failed to fetch executors", e)
+                raise upstream_error("Failed to fetch executors", e)
             return _offset_page(rows, offset, limit)
         # Cold cache on the first page: fall through to opaque API cursors,
         # which page the rest of the scroll in one request each.
@@ -220,7 +199,7 @@ async def list_executors_page(
         result = await client.executors.search_executors(**kwargs)
     except Exception as e:
         logger.exception("Failed to page executors for server %s", name)
-        raise _executor_error("Failed to fetch executors", e)
+        raise upstream_error("Failed to fetch executors", e)
 
     page = _extract_executors_list(result)
     next_cursor = None
@@ -321,7 +300,7 @@ async def executors_summary(
         executors = await fetch_all_executors(client)
     except Exception as e:
         logger.exception("Failed to summarize executors for server %s", name)
-        raise _executor_error("Failed to fetch executors", e)
+        raise upstream_error("Failed to fetch executors", e)
 
     summary = await _usd_summary(
         name, period, summarize_executors_by_quote(executors, now - window)
@@ -350,7 +329,7 @@ async def create_executor_endpoint(
     try:
         result = await create_executor(client, config, account_name=body.account_name)
     except Exception as e:
-        raise _executor_error("Failed to create executor", e)
+        raise upstream_error("Failed to create executor", e)
     executor_id = ""
     if isinstance(result, dict):
         executor_id = str(result.get("executor_id") or result.get("id") or "")
@@ -375,7 +354,7 @@ async def stop_executor_endpoint(
     try:
         result = await stop_executor(client, executor_id, keep_position=keep_position)
     except Exception as e:
-        raise _executor_error("Failed to stop executor", e)
+        raise upstream_error("Failed to stop executor", e)
     return {"status": "ok", "result": result}
 
 
@@ -393,7 +372,7 @@ async def get_positions_held(
         result = await client.executors.get_positions_summary()
     except Exception as e:
         logger.exception("Failed to fetch held positions for server %s", name)
-        raise _executor_error("Failed to fetch positions", e)
+        raise upstream_error("Failed to fetch positions", e)
 
     # Normalize: extract positions list from various shapes
     if isinstance(result, dict):
@@ -436,5 +415,5 @@ async def clear_position_held(
         )
     except Exception as e:
         logger.exception("Failed to clear held position on server %s", name)
-        raise _executor_error("Failed to clear position", e)
+        raise upstream_error("Failed to clear position", e)
     return {"status": "ok", "result": result}
diff --git a/condor/web/routes/market.py b/condor/web/routes/market.py
index 680f0eb3..032bc931 100644
--- a/condor/web/routes/market.py
+++ b/condor/web/routes/market.py
@@ -42,6 +42,7 @@ def _candle_cache_put(key: tuple, value: list, now: float) -> None:
     TradingRulesResponse,
     WebUser,
 )
+from condor.web.routes._errors import upstream_error
 
 router = APIRouter(tags=["market"])
 
@@ -81,7 +82,8 @@ async def get_connectors(name: str, user: WebUser = Depends(get_current_user)):
             name, ServerDataType.CANDLE_CONNECTORS
         )
     except Exception as e:
-        raise HTTPException(status_code=502, detail=str(e))
+        logger.exception("Failed to fetch candle connectors from '%s'", name)
+        raise upstream_error("Failed to fetch connectors", e)
     return result
 
 
@@ -99,7 +101,8 @@ async def get_connected_exchanges(name: str, user: WebUser = Depends(get_current
             name, ServerDataType.CONNECTORS
         )
     except Exception as e:
-        raise HTTPException(status_code=502, detail=str(e))
+        logger.exception("Failed to fetch connected exchanges from '%s'", name)
+        raise upstream_error("Failed to fetch connectors", e)
     return result or []
 
 
@@ -220,7 +223,10 @@ async def get_price(
             trading_pair=trading_pair,
         )
     except Exception as e:
-        raise HTTPException(status_code=502, detail=str(e))
+        logger.exception(
+            "Failed to fetch price for %s on %s of '%s'", trading_pair, connector, name
+        )
+        raise upstream_error("Failed to fetch price", e)
 
     if result is None:
         raise HTTPException(status_code=502, detail="Failed to fetch price")
@@ -260,7 +266,8 @@ async def get_rates(
     try:
         rates = await resolve(name, trading_pairs, connector=body.get("connector"))
     except Exception as e:
-        raise HTTPException(status_code=502, detail=str(e))
+        logger.exception("Failed to resolve rates on '%s'", name)
+        raise upstream_error("Failed to fetch rates", e)
 
     return RatesResponse(rates=rates)
 
@@ -290,7 +297,10 @@ async def get_trading_rules(
             name, ServerDataType.TRADING_RULES, connector_name=connector
         )
     except Exception as e:
-        raise HTTPException(status_code=502, detail=str(e))
+        logger.exception(
+            "Failed to fetch trading rules for '%s' on '%s'", connector, name
+        )
+        raise upstream_error("Failed to fetch trading rules", e)
 
     if not isinstance(result, dict):
         return TradingRulesResponse(connector=connector, rules=[])
@@ -328,7 +338,8 @@ async def get_tickers(
     try:
         result = await get_connector_tickers(name, connector)
     except Exception as e:
-        raise HTTPException(status_code=502, detail=str(e))
+        logger.exception("Failed to fetch tickers for '%s' on '%s'", connector, name)
+        raise upstream_error("Failed to fetch tickers", e)
 
     if not isinstance(result, dict):
         return TickersResponse(connector=connector, tickers=[])
@@ -366,7 +377,13 @@ async def get_order_book(
             connector_name=connector, trading_pair=trading_pair
         )
     except Exception as e:
-        raise HTTPException(status_code=502, detail=str(e))
+        logger.exception(
+            "Failed to fetch order book for %s on %s of '%s'",
+            trading_pair,
+            connector,
+            name,
+        )
+        raise upstream_error("Failed to fetch order book", e)
 
     bids = []
     asks = []
@@ -505,7 +522,13 @@ async def get_candles(
                 connector, trading_pair, interval, limit
             )
         except Exception as e:
-            raise HTTPException(status_code=502, detail=str(e))
+            logger.exception(
+                "Failed to fetch candles for %s on %s of '%s'",
+                trading_pair,
+                connector,
+                name,
+            )
+            raise upstream_error("Failed to fetch candles", e)
 
     candles_raw = (
         result
diff --git a/condor/web/routes/settings.py b/condor/web/routes/settings.py
index b7408a5f..ba8e3676 100644
--- a/condor/web/routes/settings.py
+++ b/condor/web/routes/settings.py
@@ -16,6 +16,7 @@
     UpdateServerRequest,
     WebUser,
 )
+from condor.web.routes._errors import upstream_error
 from config_manager import ServerPermission, get_config_manager
 
 logger = logging.getLogger(__name__)
@@ -35,8 +36,15 @@ def _require_owner(cm, user_id: int, server_name: str):
 async def _get_client(cm, server_name: str):
     try:
         return await cm.get_client(server_name)
-    except Exception as e:
+    except ValueError as e:
+        # The config manager's own rejection ("no such server"). Its text names
+        # nothing the caller did not already type, so it can be shown as-is.
         raise HTTPException(status_code=502, detail=f"Cannot connect to server: {e}")
+    except Exception as e:
+        # Anything else came off the wire, and its string carries the backend
+        # address — log it, show the caller only the safe description.
+        logger.exception("Cannot connect to server '%s'", server_name)
+        raise upstream_error("Cannot connect to server", e)
 
 
 # ── Servers ──
@@ -179,7 +187,8 @@ async def gateway_pull(
         result = await client.docker.pull_image(image_name, tag)
         return {"pulled": True, "image": req.image, "result": result}
     except Exception as e:
-        raise HTTPException(status_code=500, detail=str(e))
+        logger.exception("Failed to pull gateway image '%s' on '%s'", req.image, server)
+        raise upstream_error("Failed to pull gateway image", e)
 
 
 @router.get("/gateway/pull-status")
@@ -195,7 +204,8 @@ async def gateway_pull_status(
         result = await client.docker.get_pull_status()
         return result
     except Exception as e:
-        raise HTTPException(status_code=500, detail=str(e))
+        logger.exception("Failed to fetch gateway pull status from '%s'", server)
+        raise upstream_error("Failed to fetch pull status", e)
 
 
 @router.post("/gateway/start")
@@ -217,7 +227,8 @@ async def gateway_start(
         )
         return {"started": True, "result": result}
     except Exception as e:
-        raise HTTPException(status_code=500, detail=str(e))
+        logger.exception("Failed to start gateway on '%s'", server)
+        raise upstream_error("Failed to start gateway", e)
 
 
 @router.post("/gateway/stop")
@@ -233,7 +244,8 @@ async def gateway_stop(
         result = await client.gateway.stop()
         return {"stopped": True, "result": result}
     except Exception as e:
-        raise HTTPException(status_code=500, detail=str(e))
+        logger.exception("Failed to stop gateway on '%s'", server)
+        raise upstream_error("Failed to stop gateway", e)
 
 
 @router.post("/gateway/restart")
@@ -249,7 +261,8 @@ async def gateway_restart(
         result = await client.gateway.restart()
         return {"restarted": True, "result": result}
     except Exception as e:
-        raise HTTPException(status_code=500, detail=str(e))
+        logger.exception("Failed to restart gateway on '%s'", server)
+        raise upstream_error("Failed to restart gateway", e)
 
 
 @router.get("/gateway/logs")
@@ -265,7 +278,8 @@ async def gateway_logs(
         logs = await client.gateway.get_logs()
         return {"logs": logs}
     except Exception as e:
-        raise HTTPException(status_code=500, detail=str(e))
+        logger.exception("Failed to fetch gateway logs from '%s'", server)
+        raise upstream_error("Failed to fetch gateway logs", e)
 
 
 # ── Voice Preferences ──
@@ -361,7 +375,8 @@ async def list_credentials(
                     )
         return {"credentials": credentials}
     except Exception as e:
-        raise HTTPException(status_code=500, detail=str(e))
+        logger.exception("Failed to list credentials on '%s'", server)
+        raise upstream_error("Failed to list credentials", e)
 
 
 @router.get("/connectors")
@@ -418,7 +433,10 @@ async def connector_config_map(
         config_map = await client.connectors.get_config_map(name)
         return {"config_map": config_map}
     except Exception as e:
-        raise HTTPException(status_code=500, detail=str(e))
+        logger.exception(
+            "Failed to fetch config map for connector '%s' on '%s'", name, server
+        )
+        raise upstream_error("Failed to fetch connector config map", e)
 
 
 @router.post("/credentials")
@@ -443,7 +461,10 @@ async def add_credential(
         get_server_data_service().invalidate(server, ServerDataType.CONNECTORS)
         return {"added": True, "result": result}
     except Exception as e:
-        raise HTTPException(status_code=500, detail=str(e))
+        logger.exception(
+            "Failed to add credentials for '%s' on '%s'", req.connector_name, server
+        )
+        raise upstream_error("Failed to add credentials", e)
 
 
 @router.delete("/credentials/{connector}")
@@ -469,7 +490,10 @@ async def delete_credential(
         sds.invalidate(server, ServerDataType.PORTFOLIO)
         return {"deleted": True, "result": result}
     except Exception as e:
-        raise HTTPException(status_code=500, detail=str(e))
+        logger.exception(
+            "Failed to delete credentials for '%s' on '%s'", connector, server
+        )
+        raise upstream_error("Failed to delete credentials", e)
 
 
 # ── Custom OpenAI-compatible LLM endpoints ──
diff --git a/tests/test_route_upstream_errors.py b/tests/test_route_upstream_errors.py
new file mode 100644
index 00000000..b879773b
--- /dev/null
+++ b/tests/test_route_upstream_errors.py
@@ -0,0 +1,297 @@
+"""Tests for SEC-130: no route module names the backend in a failed response.
+
+SEC-116 established the rule for the executor mutations and SEC-126 extended it
+to the executor reads: ``str(exc)`` on an ``aiohttp`` client exception embeds the
+backend's own URL, so raising it as an ``HTTPException`` detail publishes the
+internal host and port to anyone who can provoke a backend blip. Four more route
+modules — ``bots``, ``settings``, ``market``, ``controller_performance`` — were
+still doing exactly that at every backend call boundary.
+
+They now go through the same helper, lifted into ``condor/web/routes/_errors.py``
+so there is one implementation rather than five. These tests pin both halves of
+the contract: the client loses the address, and the operator does not — the full
+exception still reaches the server log, because a redaction that also destroys
+the diagnostic is not a fix.
+"""
+
+import asyncio
+import logging
+import re
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+from aiohttp import ClientConnectorError, ClientResponseError, RequestInfo
+from fastapi import HTTPException
+from multidict import CIMultiDict
+from yarl import URL
+
+import condor.web.routes.bots as bots_module
+import condor.web.routes.controller_performance as cperf_module
+import condor.web.routes.market as market_module
+import condor.web.routes.settings as settings_module
+from condor.web.models import WebUser
+
+# The internal address a trader on a shared server must never be shown.
+BACKEND_URL = "http://10.0.0.7:8000/bot-orchestration/status"
+BACKEND_HOST = "10.0.0.7"
+BACKEND_PORT = "8000"
+
+
+def _api_error(status: int, detail: str) -> ClientResponseError:
+    """The error the hummingbot client raises: API ``detail`` + backend URL."""
+    info = RequestInfo(
+        url=URL(BACKEND_URL),
+        method="GET",
+        headers=CIMultiDict(),
+        real_url=URL(BACKEND_URL),
+    )
+    return ClientResponseError(info, (), status=status, message=detail)
+
+
+def _transport_error() -> ClientConnectorError:
+    """What a backend outage raises: no HTTP answer, host in the string."""
+    return ClientConnectorError(
+        SimpleNamespace(host=BACKEND_HOST, port=int(BACKEND_PORT), ssl=None),
+        OSError(61, "Connection refused"),
+    )
+
+
+class _RaisingNamespace:
+    """Any method looked up on this raises the bound exception."""
+
+    def __init__(self, exc):
+        self._exc = exc
+
+    def __getattr__(self, _name):
+        async def _call(*_args, **_kwargs):
+            raise self._exc
+
+        return _call
+
+
+class FakeClient:
+    """API client whose every sub-API fails the same way."""
+
+    def __init__(self, exc):
+        self._exc = exc
+
+    def __getattr__(self, _name):
+        return _RaisingNamespace(self._exc)
+
+
+class _FakeCM:
+    def __init__(self, client):
+        self._client = client
+
+    def has_server_access(self, *_args, **_kwargs):
+        return True
+
+    async def get_client(self, _name):
+        return self._client
+
+
+_USER = WebUser(id=1, role="admin")
+
+
+# --- One backend-call endpoint per converted module ---
+
+
+def _bots_status():
+    return asyncio.run(bots_module.get_bot(name="srv", bot_id="bot-1", user=_USER))
+
+
+def _settings_pull_status():
+    return asyncio.run(settings_module.gateway_pull_status(server="srv", user=_USER))
+
+
+def _market_order_book():
+    return asyncio.run(
+        market_module.get_order_book(
+            name="srv",
+            connector="binance",
+            trading_pair="SOL-USDC",
+            depth=20,
+            user=_USER,
+        )
+    )
+
+
+def _cperf_delete_run():
+    return asyncio.run(
+        cperf_module.delete_bot_run(name="srv", bot_run_id=7, user=_USER)
+    )
+
+
+ENDPOINTS = [
+    pytest.param(bots_module, _bots_status, id="bots-get-bot-status"),
+    pytest.param(settings_module, _settings_pull_status, id="settings-pull-status"),
+    pytest.param(market_module, _market_order_book, id="market-order-book"),
+    pytest.param(cperf_module, _cperf_delete_run, id="cperf-delete-bot-run"),
+]
+
+
+@pytest.fixture
+def failing_backend(monkeypatch):
+    """Point a route module's config manager at a client that always fails."""
+
+    def _bind(module, exc):
+        monkeypatch.setattr(
+            module, "get_config_manager", lambda: _FakeCM(FakeClient(exc))
+        )
+
+    return _bind
+
+
+@pytest.mark.parametrize("module,call", ENDPOINTS)
+def test_a_backend_outage_never_shows_the_backend_address(
+    module, call, failing_backend
+):
+    exc = _transport_error()
+    # Precondition: the raw string really does carry the internal address.
+    assert BACKEND_HOST in str(exc)
+    failing_backend(module, exc)
+
+    with pytest.raises(HTTPException) as caught:
+        call()
+
+    assert caught.value.status_code == 502, "an unreachable backend is not a 400"
+    assert BACKEND_HOST not in caught.value.detail
+    assert BACKEND_PORT not in caught.value.detail
+    assert BACKEND_URL not in caught.value.detail
+
+
+@pytest.mark.parametrize("module,call", ENDPOINTS)
+def test_an_api_rejection_never_shows_the_backend_address(
+    module, call, failing_backend
+):
+    exc = _api_error(400, "unknown bot name")
+    assert BACKEND_HOST in str(exc)
+    failing_backend(module, exc)
+
+    with pytest.raises(HTTPException) as caught:
+        call()
+
+    assert caught.value.status_code == 400, "an upstream 4xx is the caller's own"
+    assert "unknown bot name" in caught.value.detail, "the API's own reason survives"
+    assert BACKEND_HOST not in caught.value.detail
+    assert BACKEND_PORT not in caught.value.detail
+
+
+@pytest.mark.parametrize("module,call", ENDPOINTS)
+def test_an_upstream_5xx_is_a_502(module, call, failing_backend):
+    failing_backend(module, _api_error(503, "backend restarting"))
+
+    with pytest.raises(HTTPException) as caught:
+        call()
+
+    assert caught.value.status_code == 502
+
+
+@pytest.mark.parametrize("module,call", ENDPOINTS)
+def test_the_full_exception_still_reaches_the_server_log(
+    module, call, failing_backend, caplog
+):
+    """Only the client loses the address — the operator keeps the diagnostic."""
+    failing_backend(module, _transport_error())
+
+    with caplog.at_level(logging.ERROR, logger=module.__name__):
+        with pytest.raises(HTTPException):
+            call()
+
+    assert BACKEND_HOST in caplog.text, "diagnostics were lost, not just redacted"
+    assert any(
+        record.exc_info for record in caplog.records
+    ), "the traceback is what makes the log entry actionable"
+
+
+# --- The settings helper every settings endpoint funnels through ---
+
+
+def test_a_client_that_cannot_be_built_does_not_name_the_backend_either(monkeypatch):
+    """``_get_client`` interpolated the exception straight into the detail."""
+
+    class _UnreachableCM:
+        def has_server_access(self, *_a, **_kw):
+            return True
+
+        async def get_client(self, _name):
+            raise _transport_error()
+
+    monkeypatch.setattr(settings_module, "get_config_manager", _UnreachableCM)
+
+    with pytest.raises(HTTPException) as caught:
+        asyncio.run(settings_module.gateway_pull_status(server="srv", user=_USER))
+
+    assert caught.value.status_code == 502
+    assert BACKEND_HOST not in caught.value.detail
+    assert BACKEND_PORT not in caught.value.detail
+
+
+def test_an_unknown_server_still_says_so(monkeypatch):
+    """The config manager's own ValueError names only what the caller typed."""
+
+    class _NoSuchServerCM:
+        def has_server_access(self, *_a, **_kw):
+            return True
+
+        async def get_client(self, name):
+            raise ValueError(f"Server '{name}' not found")
+
+    monkeypatch.setattr(settings_module, "get_config_manager", _NoSuchServerCM)
+
+    with pytest.raises(HTTPException) as caught:
+        asyncio.run(settings_module.gateway_pull_status(server="srv", user=_USER))
+
+    assert "not found" in caught.value.detail
+
+
+# --- The pattern must not creep back in ---
+
+_LEAK = re.compile(r"detail=str\((e|exc)\)")
+_BARE_EXCEPT = re.compile(r"^\s*except (Exception|BaseException) as (e|exc):")
+
+CONVERTED_MODULES = [bots_module, settings_module, market_module, cperf_module]
+
+
+@pytest.mark.parametrize(
+    "module", CONVERTED_MODULES, ids=lambda m: m.__name__.rsplit(".", 1)[-1]
+)
+def test_no_backend_call_stringifies_the_exception_into_the_detail(module):
+    """A bare ``except Exception`` is what catches the aiohttp client errors.
+
+    The handful of ``detail=str(e)`` sites left in these modules catch a *named*
+    domain exception — a rejected identifier, an unparseable URL — whose message
+    is our own text about the caller's own input. Those are the correct message
+    for the caller and carry no address. What must never come back is the bare
+    catch-all feeding the exception string to the client.
+    """
+    lines = Path(module.__file__).read_text().split("\n")
+
+    offenders = []
+    for index, line in enumerate(lines):
+        if not _LEAK.search(line):
+            continue
+        clause = next(
+            (
+                lines[back]
+                for back in range(index, -1, -1)
+                if lines[back].lstrip().startswith("except ")
+            ),
+            "",
+        )
+        if _BARE_EXCEPT.match(clause):
+            offenders.append(f"{module.__file__}:{index + 1}: {line.strip()}")
+
+    assert not offenders, "a backend call leaks the exception string:\n" + "\n".join(
+        offenders
+    )
+
+
+def test_the_shared_helper_is_the_only_mapping():
+    """Each converted module raises through the shared helper, not its own copy."""
+    for module in CONVERTED_MODULES:
+        source = Path(module.__file__).read_text()
+        assert "from condor.web.routes._errors import upstream_error" in source
+        assert "raise upstream_error(" in source
+        assert "describe_executor_error" not in source, "no second sanitizer"

From 5096c16f9f3f74738cb1e34abce2f42bc6adadbe Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Tue, 11 Aug 2026 23:33:28 +0300
Subject: [PATCH 013/116] Let an install opt in to telling us how it is used
 (FEAT-023)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Condor is self-hosted, so the project learns nothing about adoption, feature
usage, reliability or agent economics unless an install chooses to say. This is
the machinery for that choice, and nothing else yet: no call site emits.

The whole thing is built around the fact that this process holds exchange API
keys. Consent is opt-in and its default is silence: an install with no answer
recorded resolves to level `off`, at which emit() returns before it has looked
at its arguments — no buffer, no spool file, no directory. schema.py declares
every event and every property, and sanitize() drops anything undeclared, so
"we never collect balances, keys, pairs or prompts" is a property of the code
rather than a promise the call sites are trusted to keep.

No collector address is compiled in. With CONDOR_TELEMETRY_URL unset — the
shipped state — the send path is inert and events can only reach a capped local
outbox, which is the correct behaviour until the ingest service exists.

emit() never raises and never does I/O in the host process; it appends to a
bounded ring, and a token bucket keeps a crash loop from turning `error` into a
flood. The MCP server runs in its own process with no job_queue, so it spools to
its own pid-scoped file and the host drains it.
---
 condor/telemetry/__init__.py |  82 +++++++
 condor/telemetry/consent.py  | 255 ++++++++++++++++++++
 condor/telemetry/context.py  | 147 ++++++++++++
 condor/telemetry/emitter.py  | 178 ++++++++++++++
 condor/telemetry/outbox.py   | 224 +++++++++++++++++
 condor/telemetry/prompt.py   | 127 ++++++++++
 condor/telemetry/schema.py   | 324 +++++++++++++++++++++++++
 condor/telemetry/taps.py     | 453 +++++++++++++++++++++++++++++++++++
 config_manager.py            |  24 ++
 utils/config.py              |  15 ++
 10 files changed, 1829 insertions(+)
 create mode 100644 condor/telemetry/__init__.py
 create mode 100644 condor/telemetry/consent.py
 create mode 100644 condor/telemetry/context.py
 create mode 100644 condor/telemetry/emitter.py
 create mode 100644 condor/telemetry/outbox.py
 create mode 100644 condor/telemetry/prompt.py
 create mode 100644 condor/telemetry/schema.py
 create mode 100644 condor/telemetry/taps.py

diff --git a/condor/telemetry/__init__.py b/condor/telemetry/__init__.py
new file mode 100644
index 00000000..57760619
--- /dev/null
+++ b/condor/telemetry/__init__.py
@@ -0,0 +1,82 @@
+"""Anonymous, opt-in usage telemetry (FEAT-023).
+
+Condor is self-hosted, so the project sees nothing about how installs are used
+unless an install chooses to tell it. This package is that channel — and,
+because the same process holds exchange API keys, it is built to be auditable in
+one sitting rather than to be clever.
+
+The four facts that define it:
+
+- **Off by default.** A fresh clone has no consent recorded, which resolves to
+  level ``off``, at which :func:`emit` returns before doing anything at all. No
+  buffer, no file, no directory.
+- **Opt-in, once, by the admin.** One inline-keyboard prompt on boot offers
+  full usage, install-count-only, or no. The answer is durable and reversible.
+- **Allowlisted.** :mod:`condor.telemetry.schema` declares every event and every
+  property. Anything undeclared is dropped by construction, which is what makes
+  the "never collected" list in ``PRIVACY.md`` a property of the code.
+- **Nothing transmits without an endpoint.** No collector URL is compiled in.
+  Unset ``CONDOR_TELEMETRY_URL`` means the send path is inert and events only
+  ever reach a capped local file.
+
+Public surface — call sites should need nothing else::
+
+    from condor import telemetry
+    telemetry.emit("command", name="portfolio", surface="telegram")
+"""
+
+from condor.telemetry.consent import (
+    DENIED,
+    GRANTED,
+    OFF,
+    PING,
+    UNKNOWN,
+    USAGE,
+    is_on,
+    level,
+)
+from condor.telemetry.consent import state as consent_state
+from condor.telemetry.emitter import emit, flush
+
+__all__ = [
+    "emit",
+    "flush",
+    "level",
+    "is_on",
+    "consent_state",
+    "init",
+    "shutdown",
+    "OFF",
+    "PING",
+    "USAGE",
+    "UNKNOWN",
+    "GRANTED",
+    "DENIED",
+]
+
+
+def init(hosted: bool = True) -> str:
+    """Prime this process. Returns the effective level.
+
+    ``hosted`` marks a process that owns a flush job, so events buffer in memory
+    instead of going straight to a spool file. The MCP subprocess passes False.
+
+    Priming does two things and only two: it resolves the level once so
+    :func:`emit` never has to read the disk on a hot path, and — only if the
+    level is not ``off`` — it materializes the install's random ids. An install
+    that never opted in is left exactly as it was found.
+    """
+    from condor.telemetry import consent, emitter
+
+    emitter.set_hosted(hosted)
+    effective = consent.refresh()
+    if effective != consent.OFF:
+        consent.ensure_identity()
+    return effective
+
+
+def shutdown(reason: str = "signal") -> None:
+    """Record that the process is going down. Sending is still the job's problem."""
+    from condor.telemetry import context
+
+    emit("shutdown", reason=reason, uptime_h=context.uptime_h())
diff --git a/condor/telemetry/consent.py b/condor/telemetry/consent.py
new file mode 100644
index 00000000..d59c8416
--- /dev/null
+++ b/condor/telemetry/consent.py
@@ -0,0 +1,255 @@
+"""Consent: the three-state machine that decides whether anything happens at all.
+
+The install — not the individual user — is the unit of consent, because the
+admin owns the install. The states are ``unknown`` (the default on a fresh
+clone), ``granted`` and ``denied``, stored in ``config.yml`` under ``telemetry``
+alongside the install's identity.
+
+Two rules matter more than the rest:
+
+**Unknown means off.** Not "buffered until someone decides" — off. An install
+whose admin has never answered the prompt collects nothing, holds nothing in
+memory, and writes no spool file. The original design buffered pre-consent
+events and simply refused to send them; recording data before permission is a
+worse default than losing it, so this narrows that decision. Nothing is lost
+that we had any right to.
+
+**The environment wins.** ``CONDOR_TELEMETRY`` in ``utils/config.py`` overrides
+the stored answer in both directions, so a headless or containerized install is
+never blocked on a Telegram prompt, and an operator can force ``off`` no matter
+what is on disk.
+
+Reads never create ``config.yml``. On an install that has not been configured at
+all, :func:`state` answers ``unknown`` from nothing.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+import uuid
+from pathlib import Path
+
+log = logging.getLogger(__name__)
+
+OFF = "off"
+PING = "ping"
+USAGE = "usage"
+LEVELS = (OFF, PING, USAGE)
+
+UNKNOWN = "unknown"
+GRANTED = "granted"
+DENIED = "denied"
+
+# Answer -> level, the three buttons of the admin prompt.
+ANSWER_LEVELS = {"usage": USAGE, "ping": PING, "off": OFF}
+
+_cached_level: str | None = None
+
+
+def _config_path() -> Path:
+    from config_manager import ConfigManager
+
+    existing = ConfigManager._instance
+    return Path(existing.config_path if existing else "config.yml")
+
+
+def _cm():
+    """The ConfigManager, but only if reading it cannot create a config file."""
+    from config_manager import ConfigManager
+
+    if ConfigManager._instance is None and not Path("config.yml").exists():
+        return None
+    try:
+        return ConfigManager.instance()
+    except Exception:  # pragma: no cover - a broken config must not break a tap
+        log.debug("Telemetry could not read config", exc_info=True)
+        return None
+
+
+def _section() -> dict:
+    cm = _cm()
+    if cm is None:
+        return {}
+    try:
+        return cm.get_telemetry()
+    except Exception:  # pragma: no cover
+        return {}
+
+
+def _update(**changes) -> None:
+    cm = _cm()
+    if cm is None:
+        from config_manager import get_config_manager
+
+        cm = get_config_manager()
+    cm.update_telemetry(**changes)
+    refresh()
+
+
+def _env_level() -> str | None:
+    """The operator's override, or None when unset/nonsense."""
+    from utils.config import CONDOR_TELEMETRY
+
+    if CONDOR_TELEMETRY in LEVELS:
+        return CONDOR_TELEMETRY
+    if CONDOR_TELEMETRY:
+        log.warning(
+            "Ignoring CONDOR_TELEMETRY=%r: expected one of %s",
+            CONDOR_TELEMETRY,
+            ", ".join(LEVELS),
+        )
+    return None
+
+
+def state() -> str:
+    """``unknown`` | ``granted`` | ``denied``."""
+    value = _section().get("consent")
+    return value if value in (UNKNOWN, GRANTED, DENIED) else UNKNOWN
+
+
+def level() -> str:
+    """The effective level. Cached, because :func:`emit` reads it every time."""
+    global _cached_level
+    if _cached_level is None:
+        _cached_level = _compute_level()
+    return _cached_level
+
+
+def _compute_level() -> str:
+    env = _env_level()
+    if env is not None:
+        return env
+    if state() != GRANTED:
+        return OFF
+    stored = _section().get("level")
+    return stored if stored in LEVELS else USAGE
+
+
+def refresh() -> str:
+    """Drop the cached level and recompute it. Called after any state change."""
+    global _cached_level
+    _cached_level = None
+    return level()
+
+
+def is_on() -> bool:
+    return level() != OFF
+
+
+def env_overridden() -> bool:
+    """True when the operator has pinned the level, so no prompt should be sent."""
+    return _env_level() is not None
+
+
+# ── Identity ─────────────────────────────────────────────────────────────
+# Both ids are random. Neither is derived from a MAC address, a hostname, a
+# username or a token, so neither can be reversed into anything about the host.
+
+
+def ensure_identity() -> dict:
+    """Create the install's ids if they do not exist yet. Writes ``config.yml``.
+
+    Called from :func:`condor.telemetry.init` only when telemetry is actually
+    on, so a fresh install that never opts in never grows the section — and
+    ``emit()`` never has to touch the disk to find an id.
+    """
+    section = _section()
+    changes = {}
+    if not section.get("install_id"):
+        changes["install_id"] = uuid.uuid4().hex
+    if not section.get("install_secret"):
+        changes["install_secret"] = uuid.uuid4().hex
+    if changes:
+        _update(**changes)
+        section = _section()
+    return section
+
+
+def install_id() -> str:
+    return _section().get("install_id") or ""
+
+
+def install_secret() -> str:
+    """Never transmitted, never logged. Only ever salts a local hash."""
+    return _section().get("install_secret") or ""
+
+
+# ── Transitions ──────────────────────────────────────────────────────────
+
+
+def grant(answer: str) -> str:
+    """Record a positive answer. ``answer`` is one of :data:`ANSWER_LEVELS`."""
+    chosen = ANSWER_LEVELS.get(answer, USAGE)
+    if chosen == OFF:
+        return deny()
+    _update(
+        consent=GRANTED,
+        level=chosen,
+        decided_at=time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+    )
+    ensure_identity()
+    return chosen
+
+
+def deny() -> str:
+    """Record a refusal and destroy whatever was already on disk.
+
+    Denial deletes the spool and the outbox rather than merely ignoring them:
+    an answer of "no" should leave nothing behind to be sent by a later bug.
+    """
+    _update(
+        consent=DENIED,
+        level=OFF,
+        decided_at=time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+    )
+    from condor.telemetry import emitter, outbox
+
+    emitter.discard_buffer()
+    outbox.purge()
+    return OFF
+
+
+def set_level(new_level: str) -> str:
+    """Change the level of an install that has already consented."""
+    if new_level not in LEVELS:
+        return level()
+    if new_level == OFF:
+        return deny()
+    _update(consent=GRANTED, level=new_level)
+    ensure_identity()
+    return new_level
+
+
+# ── First-use tracking ───────────────────────────────────────────────────
+
+
+def mark_feature_seen(feature: str) -> bool:
+    """True the first time this install ever uses ``feature``, False after.
+
+    Backs the ``feature_first_use`` activation funnel. Only called when
+    telemetry is on, so an opted-out install never accumulates the list.
+    """
+    section = _section()
+    seen = list(section.get("features_seen") or [])
+    if feature in seen:
+        return False
+    seen.append(feature)
+    _update(features_seen=seen[-200:])
+    return True
+
+
+# ── Prompt bookkeeping ───────────────────────────────────────────────────
+
+
+def should_prompt(version: str = "") -> bool:
+    """Has this install never been asked (or not since this version)?"""
+    if env_overridden() or state() != UNKNOWN:
+        return False
+    asked = _section().get("prompted_version")
+    return asked != (version or "unknown")
+
+
+def mark_prompted(version: str = "") -> None:
+    """Written *before* the prompt is sent, so a crash loop cannot re-ask forever."""
+    _update(prompted_version=version or "unknown")
diff --git a/condor/telemetry/context.py b/condor/telemetry/context.py
new file mode 100644
index 00000000..e5202e82
--- /dev/null
+++ b/condor/telemetry/context.py
@@ -0,0 +1,147 @@
+"""The install context: who is reporting, not who is using.
+
+Everything here describes the *deployment* — a random id, a git sha, a platform
+triple, and a handful of counts and booleans. It is computed once per process
+and sent once per batch rather than once per event, which is both cheaper and a
+smaller surface to audit.
+
+What is deliberately not here: hostname, IP, MAC, username, home directory,
+timezone, locale, server names or URLs, and any count that could be traced to a
+person. ``user_count`` is a number, never a list.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import platform
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+log = logging.getLogger(__name__)
+
+_REPO = Path(__file__).resolve().parent.parent.parent
+_started_at = time.monotonic()
+
+_app: dict | None = None
+
+
+def uptime_h() -> float:
+    return round((time.monotonic() - _started_at) / 3600.0, 3)
+
+
+def _git(*args: str) -> str:
+    """A short, bounded git read. Returns '' rather than raising, ever."""
+    try:
+        out = subprocess.run(
+            ["git", *args],
+            cwd=str(_REPO),
+            capture_output=True,
+            text=True,
+            timeout=3,
+        )
+        return out.stdout.strip() if out.returncode == 0 else ""
+    except Exception:
+        return ""
+
+
+def _in_docker() -> bool:
+    try:
+        if Path("/.dockerenv").exists():
+            return True
+        cgroup = Path("/proc/self/cgroup")
+        return cgroup.exists() and "docker" in cgroup.read_text()
+    except Exception:
+        return False
+
+
+def app() -> dict:
+    """Version and platform. Computed once — the git calls are not free."""
+    global _app
+    if _app is None:
+        # An install deployed from a tarball rather than a clone reports
+        # "unknown", which the collector treats as its own bucket.
+        _app = {
+            "version": _git("rev-parse", "--short", "HEAD") or "unknown",
+            "branch": _git("rev-parse", "--abbrev-ref", "HEAD") or "unknown",
+            "python": f"{sys.version_info.major}.{sys.version_info.minor}",
+            "os": platform.system().lower(),
+            "arch": platform.machine().lower(),
+            "in_docker": _in_docker(),
+        }
+    return dict(_app)
+
+
+def version() -> str:
+    return app()["version"]
+
+
+def _llm_providers() -> list[str]:
+    """Which provider *slots* are configured. Names only — never a key, never a
+    prefix of a key, never its length."""
+    found = []
+    for name, var in (
+        ("openai", "OPENAI_API_KEY"),
+        ("anthropic", "ANTHROPIC_API_KEY"),
+        ("openrouter", "OPENROUTER_API_KEY"),
+        ("google", "GEMINI_API_KEY"),
+        ("groq", "GROQ_API_KEY"),
+        ("deepseek", "DEEPSEEK_API_KEY"),
+    ):
+        if os.environ.get(var, "").strip():
+            found.append(name)
+    return found
+
+
+def config_shape() -> dict:
+    """Counts and capability flags. Every field is a bool, an int, or a fixed name."""
+    shape: dict = {
+        "has_web": True,
+        "has_gateway": False,
+        "has_hb_api": False,
+        "llm_providers": _llm_providers(),
+        "user_count": 0,
+        "server_count": 0,
+        "agent_count": 0,
+    }
+    try:
+        from condor.telemetry.consent import _cm
+
+        cm = _cm()
+        if cm is not None:
+            servers = cm.list_servers() or {}
+            shape["server_count"] = len(servers)
+            shape["has_hb_api"] = bool(servers)
+            shape["user_count"] = len(cm.get_all_users() or [])
+    except Exception:
+        log.debug("Telemetry could not read config shape", exc_info=True)
+    try:
+        agents_dir = _REPO / "agents"
+        shape["agent_count"] = sum(
+            1 for p in agents_dir.iterdir() if (p / "AGENT.md").is_file()
+        )
+    except Exception:
+        pass
+    try:
+        shape["has_gateway"] = bool(os.environ.get("GATEWAY_URL", "").strip())
+    except Exception:
+        pass
+    return shape
+
+
+def envelope(events: list[dict], dropped: int, level: str) -> dict:
+    """The wire format. One context, many events, one idempotency key each."""
+    from condor.telemetry import consent
+
+    return {
+        "schema": 1,
+        "install_id": consent.install_id(),
+        "level": level,
+        "sent_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        "app": app(),
+        "config": config_shape(),
+        "dropped": dropped,
+        "events": events,
+    }
diff --git a/condor/telemetry/emitter.py b/condor/telemetry/emitter.py
new file mode 100644
index 00000000..b740b546
--- /dev/null
+++ b/condor/telemetry/emitter.py
@@ -0,0 +1,178 @@
+"""The emitter: one function, four gates, and a contract that makes it safe.
+
+``emit()`` is called from order paths, agent turns and error handlers. Its
+contract is what makes that acceptable:
+
+1. **It never raises.** Every failure inside it is swallowed. Telemetry that can
+   break the bot is worse than no telemetry, so the whole body is wrapped and
+   the fallback is silence.
+2. **It never blocks and never does I/O** in the host process. It appends to a
+   bounded ``deque``; the network is somebody else's job, 15 minutes later.
+3. **It is off unless someone said yes.** The first gate is a cached level read,
+   and on an install that has not opted in that read returns ``off`` and the
+   function returns before it has looked at its own arguments.
+4. **It cannot emit what the schema does not declare.** Properties are
+   allowlisted, type-checked and truncated by :mod:`condor.telemetry.schema`.
+
+The rate limiter is the fourth gate and exists for one specific failure: an
+error loop turning the ``error`` event into a self-inflicted flood. Overflow
+increments ``dropped``, which rides in the envelope — the collector sees an
+honest count instead of a suspiciously quiet incident.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+import uuid
+from collections import deque
+
+log = logging.getLogger(__name__)
+
+RING_MAX = 2000
+RATE_PER_MIN = 60
+FLUSH_THRESHOLD = 200
+
+_buffer: deque[dict] = deque(maxlen=RING_MAX)
+_dropped = 0
+_tokens: dict[str, tuple[float, float]] = {}
+
+# False until a process registers a flush job (see condor.telemetry.init). A
+# process without one — the out-of-process MCP server — writes straight to its
+# own spool file instead, because an in-memory ring there would be lost on exit.
+_hosted = False
+
+
+def set_hosted(value: bool) -> None:
+    global _hosted
+    _hosted = value
+
+
+def is_hosted() -> bool:
+    return _hosted
+
+
+def _take_token(name: str) -> bool:
+    """Token bucket, :data:`RATE_PER_MIN` per event name per minute."""
+    now = time.monotonic()
+    tokens, last = _tokens.get(name, (float(RATE_PER_MIN), now))
+    tokens = min(float(RATE_PER_MIN), tokens + (now - last) * RATE_PER_MIN / 60.0)
+    if tokens < 1.0:
+        _tokens[name] = (tokens, now)
+        return False
+    _tokens[name] = (tokens - 1.0, now)
+    return True
+
+
+def emit(name: str, /, **props) -> None:
+    """Record one event. Synchronous, never raises, never does I/O.
+
+    The event name is positional-only so that an event may legitimately declare
+    a property called ``name`` (``command`` does) without colliding with it.
+
+    Unknown event names and undeclared properties are dropped rather than
+    reported, so a stale call site degrades to silence instead of an exception
+    on a trading path.
+    """
+    global _dropped
+    try:
+        from condor.telemetry import consent, schema
+
+        level = consent.level()
+        if level == consent.OFF:
+            return
+        if not schema.allowed_at(name, level):
+            return
+        if not _take_token(name):
+            _dropped += 1
+            return
+        clean = schema.sanitize(name, props)
+        if clean is None:
+            return
+        event = {
+            "id": uuid.uuid4().hex,
+            "ts": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+            "name": name,
+            "props": clean,
+        }
+        if _hosted:
+            if len(_buffer) == RING_MAX:
+                _dropped += 1  # the deque is about to evict the oldest
+            _buffer.append(event)
+        else:
+            from condor.telemetry import outbox
+
+            outbox.spool(event)
+    except Exception:  # noqa: BLE001 - the whole point of this function
+        try:
+            log.debug("Telemetry emit failed for %r", name, exc_info=True)
+        except Exception:
+            pass
+
+
+def buffered() -> int:
+    return len(_buffer)
+
+
+def dropped() -> int:
+    return _dropped
+
+
+def should_flush() -> bool:
+    return len(_buffer) >= FLUSH_THRESHOLD
+
+
+def drain() -> tuple[list[dict], int]:
+    """Take the ring and the dropped count together, and reset both."""
+    global _dropped
+    events = list(_buffer)
+    _buffer.clear()
+    count, _dropped = _dropped, 0
+    return events, count
+
+
+def discard_buffer() -> None:
+    """Throw the ring away without sending it. Used when consent is denied."""
+    global _dropped
+    _buffer.clear()
+    _dropped = 0
+    _tokens.clear()
+
+
+async def flush(reason: str = "job") -> int:
+    """Try to deliver everything pending. Returns the number of events sent.
+
+    Returns 0 without reading a file when consent is not granted, and 0 without
+    touching the network when no endpoint is configured — the shipped state, in
+    which events simply accumulate in the capped outbox.
+    """
+    try:
+        from condor.telemetry import consent, context, outbox
+
+        if consent.state() != consent.GRANTED or consent.level() == consent.OFF:
+            return 0
+
+        events, dropped_count = drain()
+        events.extend(outbox.drain_spools())
+        events.extend(outbox.take_stashed())
+        if not events:
+            return 0
+
+        if not outbox.endpoint():
+            # Nowhere to go yet (the collector is FEAT-024). Park them; the cap
+            # in outbox.py is what keeps this honest on a long-running install.
+            outbox.stash(events)
+            return 0
+
+        sent = 0
+        for batch in outbox.batches(events):
+            envelope = context.envelope(batch, dropped_count, consent.level())
+            dropped_count = 0
+            if await outbox.post(envelope):
+                sent += len(batch)
+            else:
+                outbox.stash(batch)
+        return sent
+    except Exception:
+        log.debug("Telemetry flush failed (%s)", reason, exc_info=True)
+        return 0
diff --git a/condor/telemetry/outbox.py b/condor/telemetry/outbox.py
new file mode 100644
index 00000000..8f4b5f7e
--- /dev/null
+++ b/condor/telemetry/outbox.py
@@ -0,0 +1,224 @@
+"""Durable spool and the (deliberately inert) send path.
+
+Two files live under ``condor/.runtime/telemetry/``, the same gitignored place
+the rest of the runtime keeps its append-only facts:
+
+``spool.<pid>.jsonl``
+    Written by processes that have no flush job of their own — in practice the
+    MCP server, which the agent spawns in its own process group with its own
+    interpreter and no ``job_queue``. Each process owns its own file, so there
+    is no locking and no interleaving; the host drains and deletes them.
+
+``outbox.jsonl``
+    Where a batch goes when it could not be delivered. Capped at
+    :data:`MAX_OUTBOX_EVENTS` events and :data:`MAX_OUTBOX_AGE_S`, oldest first,
+    so an install that never reaches a collector accumulates a bounded file and
+    then quietly drops the excess. That is the intended behaviour, not a bug.
+
+**Nothing is transmitted unless an operator sets ``CONDOR_TELEMETRY_URL``.** No
+collector address is compiled into this repository. With the variable unset —
+which is the shipped state — :func:`post` returns ``False`` without importing a
+network client, and every event's whole life is a local file that
+:func:`purge` can delete.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import time
+from pathlib import Path
+
+log = logging.getLogger(__name__)
+
+MAX_OUTBOX_EVENTS = 5000
+MAX_OUTBOX_AGE_S = 7 * 24 * 3600
+MAX_BATCH_BYTES = 512 * 1024
+POST_TIMEOUT_S = 10
+
+
+def root() -> Path:
+    """Where the spool lives. Derived like every other runtime store."""
+    from condor.agents.agent import _DATA_ROOT
+
+    return Path(_DATA_ROOT).parent / "condor" / ".runtime" / "telemetry"
+
+
+def spool_path(pid: int | None = None) -> Path:
+    return root() / f"spool.{pid or os.getpid()}.jsonl"
+
+
+def outbox_path() -> Path:
+    return root() / "outbox.jsonl"
+
+
+def _append(path: Path, records: list[dict]) -> None:
+    if not records:
+        return
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "a", encoding="utf-8") as fh:
+        for record in records:
+            fh.write(json.dumps(record, separators=(",", ":")) + "\n")
+
+
+def _read(path: Path) -> list[dict]:
+    if not path.exists():
+        return []
+    events = []
+    try:
+        with open(path, "r", encoding="utf-8") as fh:
+            for line in fh:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    events.append(json.loads(line))
+                except ValueError:
+                    continue  # a torn last line from a killed process
+    except OSError:
+        log.debug("Telemetry could not read %s", path, exc_info=True)
+    return events
+
+
+def spool(event: dict) -> None:
+    """Append one event to this process's own spool file."""
+    _append(spool_path(), [event])
+
+
+def drain_spools() -> list[dict]:
+    """Take everything other processes left behind, including our own file.
+
+    A spool file still being written by a live process is left alone unless it
+    is ours: deleting it would lose whatever landed between read and unlink.
+    """
+    directory = root()
+    if not directory.is_dir():
+        return []
+    mine = os.getpid()
+    events: list[dict] = []
+    for path in sorted(directory.glob("spool.*.jsonl")):
+        try:
+            pid = int(path.name.split(".")[1])
+        except (IndexError, ValueError):
+            continue
+        if pid != mine and _alive(pid):
+            continue
+        events.extend(_read(path))
+        try:
+            path.unlink()
+        except OSError:
+            pass
+    return events
+
+
+def _alive(pid: int) -> bool:
+    try:
+        os.kill(pid, 0)
+        return True
+    except (ProcessLookupError, ValueError):
+        return False
+    except PermissionError:
+        return True
+
+
+def stash(events: list[dict]) -> None:
+    """Park undeliverable events, then enforce the cap."""
+    if not events:
+        return
+    _append(outbox_path(), events)
+    _trim()
+
+
+def take_stashed() -> list[dict]:
+    """Read and clear the outbox, so a flush can retry it alongside fresh events."""
+    path = outbox_path()
+    events = _read(path)
+    try:
+        path.unlink()
+    except OSError:
+        pass
+    return events
+
+
+def _trim() -> None:
+    path = outbox_path()
+    events = _read(path)
+    cutoff = time.time() - MAX_OUTBOX_AGE_S
+    kept = [e for e in events if _epoch(e) >= cutoff][-MAX_OUTBOX_EVENTS:]
+    if len(kept) == len(events):
+        return
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = path.with_suffix(".tmp")
+        with open(tmp, "w", encoding="utf-8") as fh:
+            for record in kept:
+                fh.write(json.dumps(record, separators=(",", ":")) + "\n")
+        tmp.replace(path)
+    except OSError:
+        log.debug("Telemetry could not trim the outbox", exc_info=True)
+
+
+def _epoch(event: dict) -> float:
+    try:
+        return time.mktime(time.strptime(event["ts"], "%Y-%m-%dT%H:%M:%SZ"))
+    except Exception:
+        return time.time()
+
+
+def purge() -> None:
+    """Delete every trace. Called when consent is denied or withdrawn."""
+    directory = root()
+    if not directory.is_dir():
+        return
+    for path in list(directory.glob("*.jsonl")) + list(directory.glob("*.tmp")):
+        try:
+            path.unlink()
+        except OSError:
+            pass
+    try:
+        directory.rmdir()
+    except OSError:
+        pass
+
+
+def batches(events: list[dict]) -> list[list[dict]]:
+    """Split into envelopes no bigger than :data:`MAX_BATCH_BYTES`."""
+    out: list[list[dict]] = []
+    current: list[dict] = []
+    size = 0
+    for event in events:
+        length = len(json.dumps(event, separators=(",", ":")))
+        if current and size + length > MAX_BATCH_BYTES:
+            out.append(current)
+            current, size = [], 0
+        current.append(event)
+        size += length
+    if current:
+        out.append(current)
+    return out
+
+
+def endpoint() -> str | None:
+    """The collector URL, or None — which is the shipped default."""
+    from utils.config import CONDOR_TELEMETRY_URL
+
+    return CONDOR_TELEMETRY_URL
+
+
+async def post(envelope: dict) -> bool:
+    """Deliver one envelope. Returns False — without touching the network — when
+    no endpoint is configured, which is the state this repository ships in."""
+    url = endpoint()
+    if not url:
+        return False
+    try:
+        import aiohttp
+
+        timeout = aiohttp.ClientTimeout(total=POST_TIMEOUT_S)
+        async with aiohttp.ClientSession(timeout=timeout) as session:
+            async with session.post(url, json=envelope) as response:
+                return 200 <= response.status < 300
+    except Exception:
+        log.debug("Telemetry POST failed; events stay in the outbox", exc_info=True)
+        return False
diff --git a/condor/telemetry/prompt.py b/condor/telemetry/prompt.py
new file mode 100644
index 00000000..9c184637
--- /dev/null
+++ b/condor/telemetry/prompt.py
@@ -0,0 +1,127 @@
+"""The one-tap consent prompt, and the callback that answers it.
+
+Opt-in only works if asking is cheap, so this is a single message with three
+buttons next to the "Condor is online" notification the admin already gets. It
+is sent at most once per version, the intent is written to disk *before* the
+message goes out (a crash loop must not re-ask forever), and until it is
+answered the install emits nothing at all.
+"""
+
+from __future__ import annotations
+
+import logging
+
+log = logging.getLogger(__name__)
+
+CALLBACK_PREFIX = "telemetry"
+
+_TEXT = (
+    "Help improve Condor?\n\n"
+    "Condor can send an anonymous, allowlisted usage summary to the project: "
+    "which commands and screens get used, what breaks, and which models agents "
+    "run. It is off right now and stays off unless you say yes.\n\n"
+    "Never included: API keys, wallet addresses, server names or URLs, "
+    "trading pairs, amounts, balances, positions, prompts or agent replies, "
+    "and no Telegram id or username.\n\n"
+    "Full details in PRIVACY.md at the root of the repo. "
+    "You can change this any time from the dashboard settings."
+)
+
+
+def keyboard():
+    from telegram import InlineKeyboardButton, InlineKeyboardMarkup
+
+    return InlineKeyboardMarkup(
+        [
+            [
+                InlineKeyboardButton(
+                    "Yes, help improve Condor", callback_data=f"{CALLBACK_PREFIX}:usage"
+                )
+            ],
+            [
+                InlineKeyboardButton(
+                    "Only count my install", callback_data=f"{CALLBACK_PREFIX}:ping"
+                )
+            ],
+            [InlineKeyboardButton("No thanks", callback_data=f"{CALLBACK_PREFIX}:off")],
+        ]
+    )
+
+
+async def maybe_prompt_admin(bot) -> bool:
+    """Ask the admin once, if there is anything to ask. Never raises."""
+    try:
+        from utils.config import ADMIN_USER_ID
+
+        if not ADMIN_USER_ID:
+            return False
+
+        from condor.telemetry import consent, context
+
+        version = context.version()
+        if not consent.should_prompt(version):
+            return False
+
+        # Written first: if sending or the process dies right after, the admin
+        # gets asked again on the next version, not on the next boot loop.
+        consent.mark_prompted(version)
+        await bot.send_message(
+            chat_id=int(ADMIN_USER_ID), text=_TEXT, reply_markup=keyboard()
+        )
+        return True
+    except Exception:  # noqa: BLE001
+        log.debug("Could not send the telemetry consent prompt", exc_info=True)
+        return False
+
+
+async def callback_handler(update, context) -> None:
+    """Handle ``telemetry:usage|ping|off``. Admin only — it is an install-wide
+    setting, and the admin owns the install."""
+    query = update.callback_query
+    try:
+        await query.answer()
+    except Exception:  # noqa: BLE001
+        pass
+
+    try:
+        from condor.telemetry import consent
+        from condor.telemetry.consent import _cm
+
+        user = getattr(update, "effective_user", None)
+        cm = _cm()
+        if cm is None or user is None or not cm.is_admin(int(user.id)):
+            await query.edit_message_text(
+                "Only the admin can change the telemetry setting."
+            )
+            return
+
+        answer = (
+            (query.data or "").split(":", 1)[1] if ":" in (query.data or "") else ""
+        )
+        if answer == "off":
+            consent.deny()
+            await query.edit_message_text(
+                "Telemetry stays off. Nothing was collected, and the local "
+                "buffer has been deleted."
+            )
+            return
+
+        chosen = consent.grant(answer)
+        from condor.telemetry import emitter
+
+        emitter.emit("install")
+        if chosen == consent.PING:
+            await query.edit_message_text(
+                "Thanks. Condor will only report that this install exists and "
+                "which version it runs. Change it any time in the dashboard "
+                "settings; details in PRIVACY.md."
+            )
+        else:
+            await query.edit_message_text(
+                "Thanks. Condor will send anonymous usage and reliability "
+                "events. No keys, addresses, pairs, amounts or prompts ever "
+                "leave this machine. Change it any time in the dashboard "
+                "settings; details in PRIVACY.md."
+            )
+    except Exception:  # noqa: BLE001
+        log.exception("Telemetry consent callback failed")
diff --git a/condor/telemetry/schema.py b/condor/telemetry/schema.py
new file mode 100644
index 00000000..3f8ce848
--- /dev/null
+++ b/condor/telemetry/schema.py
@@ -0,0 +1,324 @@
+"""THE TAXONOMY — the allowlist that makes the privacy promise a property of code.
+
+Every event Condor can emit is declared here, with every property it is allowed
+to carry and the shape that property must have. :func:`sanitize` is the only way
+an event reaches a buffer, and it **drops** anything not declared rather than
+passing it through. That is deliberate: the "never collected" list in
+``PRIVACY.md`` is not a convention the call sites are trusted to honour, it is
+what this module structurally cannot let past.
+
+Consequences worth stating out loud, because they are the point:
+
+- An undeclared property is discarded, whatever it is called. A tap that grows a
+  ``wallet=`` argument by accident leaks nothing.
+- Free-form strings are capped at :data:`MAX_STR` characters, so nothing long
+  enough to be a key, an address, a prompt or a URL survives intact.
+- Enum properties are snapped to their allowlist or to ``other``, so cardinality
+  is bounded by this file rather than by whatever the caller happened to hold.
+
+Deliberately absent, and asserted by ``tests/test_telemetry.py``: amounts,
+balances, PnL, trading pairs, order ids, wallet addresses, server names, URLs,
+hostnames, IPs, API keys, Telegram ids or usernames, prompts, agent replies,
+routine configs, journal text, and exception message strings.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+# One place to change the blast radius of any single value.
+MAX_STR = 64
+MAX_MAP_KEYS = 20
+MAX_LIST = 5
+
+# Free-form strings keep only characters our own identifiers use. It is a second
+# fence behind the allowlist: even a declared string property cannot carry a
+# sentence, a path with a home directory in it, or a URL with a token in it.
+_SAFE_CHARS = re.compile(r"[^A-Za-z0-9._:/@#-]+")
+
+
+@dataclass(frozen=True)
+class PropSpec:
+    """What one property of one event is allowed to be."""
+
+    kind: str  # str | int | float | bool | enum | map | list
+    allowed: tuple[str, ...] = field(default=())
+
+    def __post_init__(self) -> None:
+        if self.kind == "enum" and not self.allowed:
+            raise ValueError("enum PropSpec needs an allowlist")
+
+
+def _s() -> PropSpec:
+    return PropSpec("str")
+
+
+def _i() -> PropSpec:
+    return PropSpec("int")
+
+
+def _f() -> PropSpec:
+    return PropSpec("float")
+
+
+def _b() -> PropSpec:
+    return PropSpec("bool")
+
+
+def _e(*allowed: str) -> PropSpec:
+    return PropSpec("enum", tuple(allowed))
+
+
+SURFACES = ("telegram", "web", "mcp", "strategy", "other")
+
+# The commands we ship. Anything else a user types is reported as `other`, so a
+# typo, a third-party bot's command, or a private fork's addition can never
+# widen the value space.
+COMMANDS = (
+    "start",
+    "portfolio",
+    "bots",
+    "new_bot",
+    "trade",
+    "swap",
+    "lp",
+    "routines",
+    "executors",
+    "agent",
+    "stop",
+    "delegations",
+    "memory",
+    "cancel",
+    "servers",
+    "keys",
+    "gateway",
+    "admin",
+    "update",
+    "web",
+)
+
+MODULES = (
+    "bots",
+    "cex",
+    "dex",
+    "trade",
+    "agents",
+    "routines",
+    "config",
+    "portfolio",
+    "executors",
+    "admin",
+    "start",
+    "other",
+)
+
+# Events an install at level `ping` may send. Everything else needs `usage`.
+PING_EVENTS = frozenset({"install", "heartbeat", "version_change", "shutdown"})
+
+
+EVENTS: dict[str, dict[str, PropSpec]] = {
+    # ── Adoption & retention ─────────────────────────────────────────────
+    # `install` carries no properties: the envelope context is the payload.
+    "install": {},
+    "heartbeat": {
+        "uptime_h": _f(),
+        "active_users_24h": _i(),
+        "surfaces": PropSpec("map"),
+        # `health` rides here rather than being its own event.
+        "hb_api_online": _b(),
+        "gateway_online": _b(),
+        "hb_api_version": _s(),
+    },
+    "version_change": {
+        # Named `from_version`/`to_version`, not `from`/`to`: `from` is a Python
+        # keyword and emit() takes keyword arguments.
+        "from_version": _s(),
+        "to_version": _s(),
+        "was_behind": _i(),
+    },
+    "shutdown": {
+        "reason": _e("signal", "crash", "restart"),
+        "uptime_h": _f(),
+    },
+    # ── Feature usage ────────────────────────────────────────────────────
+    "command": {
+        "name": _e(*COMMANDS, "other"),
+        "surface": _e(*SURFACES),
+        "user_hash": _s(),
+        "authorized": _b(),
+    },
+    "action": {
+        "module": _e(*MODULES),
+        "verb": _s(),
+        "surface": _e(*SURFACES),
+        "status": _i(),
+    },
+    "feature_first_use": {"feature": _s()},
+    "bot_deploy": {
+        "controller_type": _s(),
+        "connector": _s(),
+        "is_paper": _b(),
+    },
+    "executor_deploy": {"executor_type": _s(), "connector": _s()},
+    "trade": {
+        # No trading pair, and no amount. See PRIVACY.md: an install that trades
+        # one pair, plus timestamps, is a deanonymizable position disclosure.
+        "venue": _e("cex", "dex"),
+        "connector": _s(),
+        "side": _e("buy", "sell", "other"),
+        "order_type": _s(),
+    },
+    "routine_run": {
+        "routine": _s(),
+        "kind": _e("oneshot", "continuous", "other"),
+        "trigger": _e("manual", "schedule", "background", "web", "mcp", "other"),
+        "duration_ms": _i(),
+        "ok": _b(),
+    },
+    # ── Reliability ──────────────────────────────────────────────────────
+    "error": {
+        "where": _s(),
+        "exc_type": _s(),
+        # A hash of the message, never the message. Grouping still works; the
+        # balance, hostname or key that message might have contained does not
+        # survive the hash.
+        "sig": _s(),
+        "frames": PropSpec("list"),
+        "surface": _e(*SURFACES),
+        "fatal": _b(),
+    },
+    "upstream_error": {
+        "service": _e("hb_api", "gateway", "llm", "telegram", "other"),
+        "op": _s(),
+        "status": _s(),
+    },
+    # ── Agent economics ──────────────────────────────────────────────────
+    "agent_turn": {
+        "kind": _e("chat", "consult", "delegate", "tick", "other"),
+        "provider": _s(),
+        "model": _s(),
+        "tool_calls": _i(),
+        "duration_ms": _i(),
+        "outcome": _e("done", "error", "aborted"),
+        "tokens_in": _i(),
+        "tokens_out": _i(),
+        "surface": _e(*SURFACES),
+        # `agent_tools` rides here: a bounded map of tool name -> count.
+        "tools": PropSpec("map"),
+    },
+    # An MCP tool call observed from the out-of-process server, which cannot see
+    # the turn it belongs to (see condor/telemetry/outbox.py). Not in the
+    # original design's table; added so the subprocess spool has something
+    # declared to carry.
+    "mcp_tool": {"tool": _s(), "ok": _b(), "duration_ms": _i()},
+    "strategy_run": {
+        "mode": _e("dry_run", "run_once", "loop", "other"),
+        "frequency_sec": _i(),
+        "ticks": _i(),
+        "bot_mode": _s(),
+        "has_risk_limits": _b(),
+        "stopped_by": _s(),
+    },
+    "confirmation": {
+        "tool": _s(),
+        "decision": _e("allow", "deny", "timeout"),
+    },
+}
+
+
+def is_known(name: str) -> bool:
+    return name in EVENTS
+
+
+def allowed_at(name: str, level: str) -> bool:
+    """Is this event permitted at this telemetry level?"""
+    if level == "usage":
+        return name in EVENTS
+    if level == "ping":
+        return name in PING_EVENTS
+    return False
+
+
+def clean_str(value: object) -> str | None:
+    """Reduce any value to a short, identifier-shaped string, or reject it."""
+    if isinstance(value, bool) or not isinstance(value, (str, int, float)):
+        return None
+    text = _SAFE_CHARS.sub("_", str(value)).strip("_")
+    if not text:
+        return None
+    return text[:MAX_STR]
+
+
+def _coerce(spec: PropSpec, value: object) -> object | None:
+    """Force one value into its declared shape, or return None to drop it."""
+    if value is None:
+        return None
+
+    if spec.kind == "bool":
+        return value if isinstance(value, bool) else None
+
+    if spec.kind == "int":
+        # bool is an int in Python; a bool in an int slot is a caller bug.
+        if isinstance(value, bool) or not isinstance(value, (int, float)):
+            return None
+        return int(value)
+
+    if spec.kind == "float":
+        if isinstance(value, bool) or not isinstance(value, (int, float)):
+            return None
+        return round(float(value), 3)
+
+    if spec.kind == "str":
+        return clean_str(value)
+
+    if spec.kind == "enum":
+        text = clean_str(value)
+        if text is None:
+            return None
+        return text if text in spec.allowed else "other"
+
+    if spec.kind == "list":
+        if not isinstance(value, (list, tuple)):
+            return None
+        out = [s for s in (clean_str(v) for v in value[:MAX_LIST]) if s]
+        return out or None
+
+    if spec.kind == "map":
+        if not isinstance(value, dict):
+            return None
+        out: dict[str, int] = {}
+        for key, count in list(value.items())[:MAX_MAP_KEYS]:
+            safe_key = clean_str(key)
+            if safe_key is None:
+                continue
+            if isinstance(count, bool) or not isinstance(count, (int, float)):
+                continue
+            out[safe_key] = int(count)
+        return out or None
+
+    return None
+
+
+def sanitize(name: str, props: dict | None) -> dict | None:
+    """Return the emittable form of one event, or None if it is not emittable.
+
+    Undeclared properties are dropped silently — the caller is not trusted, and
+    a warning that names the offending value would only move the leak into the
+    log file.
+    """
+    spec = EVENTS.get(name)
+    if spec is None:
+        return None
+    if not props:
+        return {}
+
+    clean: dict = {}
+    for key, value in props.items():
+        prop_spec = spec.get(key)
+        if prop_spec is None:
+            continue
+        coerced = _coerce(prop_spec, value)
+        if coerced is not None:
+            clean[key] = coerced
+    return clean
diff --git a/condor/telemetry/taps.py b/condor/telemetry/taps.py
new file mode 100644
index 00000000..181d29b7
--- /dev/null
+++ b/condor/telemetry/taps.py
@@ -0,0 +1,453 @@
+"""The taps: the only code that turns something happening into an event.
+
+Call sites stay one line long and stay dumb. Everything that decides *what* is
+allowed to be said lives here and in :mod:`condor.telemetry.schema`, so the
+privacy review has two files to read rather than fifteen.
+
+Every public function here is defensive to the point of paranoia: a tap runs
+inside a command handler, an error handler, an order path and a tick loop, and
+a tap that raises would turn "we learned nothing" into "the bot broke". They all
+swallow, and :func:`condor.telemetry.emitter.emit` swallows again underneath.
+"""
+
+from __future__ import annotations
+
+import functools
+import hashlib
+import logging
+import re
+import time
+import traceback
+from pathlib import Path
+
+from condor.telemetry.emitter import emit
+
+log = logging.getLogger(__name__)
+
+TELEMETRY_FLUSH_JOB = "telemetry_flush"
+TELEMETRY_HEARTBEAT_JOB = "telemetry_heartbeat"
+FLUSH_INTERVAL_S = 15 * 60
+HEARTBEAT_INTERVAL_S = 6 * 3600
+
+_REPO = Path(__file__).resolve().parent.parent.parent
+# Frames from our own packages only. A frame in site-packages tells us nothing
+# actionable and its path can carry a username.
+_OWN_PACKAGES = ("condor", "handlers", "utils", "mcp_servers", "routines")
+
+# Rolling, in-memory only, never persisted and never transmitted as a set —
+# only its cardinality reaches an envelope.
+_seen_users: dict[str, float] = {}
+_surface_counts: dict[str, int] = {}
+
+# A leading run of lowercase and underscores. Deliberately strict: callback data
+# like ``admin:approve_12345`` or ``bots:view_MyBotName`` carries an identifier
+# after the verb, and cutting at the first digit or capital drops it.
+_VERB = re.compile(r"^[a-z][a-z_]{0,31}")
+
+
+def _quiet(fn):
+    """A tap must never be the reason a handler failed."""
+
+    @functools.wraps(fn)
+    def wrapper(*args, **kwargs):
+        try:
+            return fn(*args, **kwargs)
+        except Exception:  # noqa: BLE001
+            log.debug("Telemetry tap %s failed", fn.__name__, exc_info=True)
+            return None
+
+    return wrapper
+
+
+def _quiet_async(fn):
+    @functools.wraps(fn)
+    async def wrapper(*args, **kwargs):
+        try:
+            return await fn(*args, **kwargs)
+        except Exception:  # noqa: BLE001
+            log.debug("Telemetry tap %s failed", fn.__name__, exc_info=True)
+            return None
+
+    return wrapper
+
+
+def _on() -> bool:
+    from condor.telemetry import consent
+
+    return consent.level() != consent.OFF
+
+
+# ── Identity ─────────────────────────────────────────────────────────────
+
+
+@_quiet
+def user_hash(user_id) -> str | None:
+    """A per-install pseudonym for one Telegram user.
+
+    Salted with the install's own secret, which never leaves the machine, so the
+    result counts distinct users within an install and is useless for correlating
+    the same person across two installs. The Telegram id itself is never sent.
+    """
+    from condor.telemetry import consent
+
+    secret = consent.install_secret()
+    if not secret or user_id is None:
+        return None
+    digest = hashlib.sha256(f"{secret}:{user_id}".encode()).hexdigest()
+    return digest[:16]
+
+
+def _note_user(hashed: str | None, surface: str) -> None:
+    if hashed:
+        _seen_users[hashed] = time.time()
+    _surface_counts[surface] = _surface_counts.get(surface, 0) + 1
+
+
+@_quiet
+def feature_first_use(feature: str) -> None:
+    """Fire once per install, ever. The activation funnel."""
+    if not _on():
+        return
+    from condor.telemetry import consent
+
+    if consent.mark_feature_seen(feature):
+        emit("feature_first_use", feature=feature)
+
+
+def _verb_of(segment: str) -> str:
+    match = _VERB.match((segment or "").strip())
+    return (match.group(0).rstrip("_") if match else "") or "other"
+
+
+# ── Telegram ─────────────────────────────────────────────────────────────
+
+
+async def telegram_tap(update, context) -> None:
+    """Observe every update, in ``group=-1``, without ever deciding anything.
+
+    Registered before the real handlers so it sees commands and callbacks from
+    unauthorized users too — who is knocking is signal. It reads authorization
+    state; it must never call into ``@restricted``, or a read would become an
+    access-control side effect.
+    """
+    try:
+        if not _on():
+            return
+        user = getattr(update, "effective_user", None)
+        hashed = user_hash(getattr(user, "id", None)) if user else None
+        authorized = _is_authorized(getattr(user, "id", None))
+
+        message = getattr(update, "message", None)
+        text = (getattr(message, "text", None) or "") if message else ""
+        if text.startswith("/"):
+            raw = text[1:].split(maxsplit=1)[0].split("@")[0].lower()
+            _note_user(hashed, "telegram")
+            emit(
+                "command",
+                name=raw,
+                surface="telegram",
+                user_hash=hashed,
+                authorized=authorized,
+            )
+            if authorized:
+                feature_first_use(f"command:{_verb_of(raw)}")
+            return
+
+        query = getattr(update, "callback_query", None)
+        data = (getattr(query, "data", None) or "") if query else ""
+        if data:
+            module, _, rest = data.partition(":")
+            _note_user(hashed, "telegram")
+            emit(
+                "action",
+                module=module.lower(),
+                verb=_verb_of(rest.split(":")[0]),
+                surface="telegram",
+            )
+    except Exception:  # noqa: BLE001
+        log.debug("Telegram telemetry tap failed", exc_info=True)
+
+
+@_quiet
+def _is_authorized(user_id) -> bool:
+    from condor.telemetry.consent import _cm
+
+    cm = _cm()
+    return bool(cm and user_id is not None and cm.is_approved(int(user_id)))
+
+
+# ── Errors ───────────────────────────────────────────────────────────────
+
+
+def _frames(exc: BaseException) -> list[str]:
+    """Up to five ``file:line`` pairs from our own packages, repo-relative.
+
+    Absolute paths are not sent: they contain the operator's home directory and
+    often their username.
+    """
+    out: list[str] = []
+    for frame in traceback.extract_tb(exc.__traceback__):
+        try:
+            path = Path(frame.filename).resolve().relative_to(_REPO)
+        except (ValueError, OSError):
+            continue
+        if path.parts and path.parts[0] in _OWN_PACKAGES or path.name == "main.py":
+            out.append(f"{path.as_posix()}:{frame.lineno}")
+    return out[-5:]
+
+
+@_quiet
+def on_error(
+    exc: BaseException | None, where: str, surface: str = "other", fatal: bool = False
+) -> None:
+    """Report that something broke — the shape of it, never its words.
+
+    Only the exception *type*, a hash of its message, and our own stack frames.
+    Message strings are where balances, hostnames, URLs and keys leak, so they
+    are hashed and discarded: grouping still works, disclosure does not.
+    """
+    if exc is None or not _on():
+        return
+    signature = hashlib.sha256(str(exc).encode("utf-8", "replace")).hexdigest()[:12]
+    emit(
+        "error",
+        where=where,
+        exc_type=type(exc).__name__,
+        sig=signature,
+        frames=_frames(exc),
+        surface=surface,
+        fatal=fatal,
+    )
+
+
+@_quiet
+def on_upstream_error(service: str, op: str, status) -> None:
+    """A dependency answered badly: which one, which operation, which code."""
+    emit("upstream_error", service=service, op=op, status=str(status))
+
+
+# ── Web ──────────────────────────────────────────────────────────────────
+
+
+def _route_action(request) -> tuple[str, str] | None:
+    """Turn a matched route *template* into (module, verb).
+
+    The template, never the URL: ``/api/v1/bots/{name}`` rather than
+    ``/api/v1/bots/my-arb-bot``. Cardinality is bounded by our own router, and
+    no path parameter — a bot name, a server name, a report id — is ever read.
+    """
+    route = request.scope.get("route")
+    template = getattr(route, "path", None)
+    if not template:
+        return None
+    parts = [p for p in template.strip("/").split("/") if p]
+    if parts[:2] == ["api", "v1"]:
+        parts = parts[2:]
+    if not parts:
+        return None
+    module = parts[0].lower()
+    static = [p for p in parts[1:] if not p.startswith("{")]
+    verb = _verb_of("_".join(static)) if static else request.method.lower()
+    return module, verb
+
+
+@_quiet_async
+async def web_tap(request, call_next):
+    """ASGI middleware: one ``action`` per API call, with its status code."""
+    response = await call_next(request)
+    try:
+        if _on() and str(request.url.path).startswith("/api/"):
+            action = _route_action(request)
+            if action:
+                module, verb = action
+                _surface_counts["web"] = _surface_counts.get("web", 0) + 1
+                emit(
+                    "action",
+                    module=module,
+                    verb=verb,
+                    surface="web",
+                    status=response.status_code,
+                )
+    except Exception:  # noqa: BLE001
+        log.debug("Web telemetry tap failed", exc_info=True)
+    return response
+
+
+# ── Agents, strategies, routines, confirmations ──────────────────────────
+
+
+@_quiet
+def agent_turn(
+    *,
+    kind: str,
+    provider: str = "",
+    model: str = "",
+    tool_calls: int = 0,
+    duration_ms: int = 0,
+    outcome: str = "done",
+    surface: str = "other",
+    tools: dict | None = None,
+) -> None:
+    """One turn through ``condor.runtime.client.prompt`` — the single funnel
+    Telegram, the dashboard and MCP all cross."""
+    _surface_counts[surface] = _surface_counts.get(surface, 0) + 1
+    emit(
+        "agent_turn",
+        kind=kind,
+        provider=provider,
+        model=model,
+        tool_calls=tool_calls,
+        duration_ms=duration_ms,
+        outcome=outcome,
+        surface=surface,
+        tools=tools,
+    )
+
+
+@_quiet
+def strategy_run(config: dict | None, *, ticks: int = 0, stopped_by: str = "") -> None:
+    """A tick-engine session ended. Shape of the run only — never its journal."""
+    config = config or {}
+    emit(
+        "strategy_run",
+        mode=config.get("execution_mode", "loop"),
+        frequency_sec=config.get("frequency_sec"),
+        ticks=ticks,
+        bot_mode=config.get("bot_mode"),
+        has_risk_limits=bool(config.get("risk_limits")),
+        stopped_by=stopped_by,
+    )
+
+
+@_quiet
+def routine_run(
+    *, routine: str, kind: str, trigger: str, duration_ms: int, ok: bool
+) -> None:
+    """A routine ran. ``routine`` is the shipped name, or ``custom`` when the
+    file is not one of ours — a user's private routine name is theirs."""
+    emit(
+        "routine_run",
+        routine=routine,
+        kind=kind,
+        trigger=trigger,
+        duration_ms=duration_ms,
+        ok=ok,
+    )
+
+
+def shipped_routine_name(name: str) -> str:
+    """``name`` if the routine ships in this repo, else ``custom``."""
+    try:
+        if (_REPO / "routines" / f"{name}.py").exists():
+            return name
+    except Exception:  # noqa: BLE001
+        pass
+    return "custom"
+
+
+@_quiet
+def confirmation(tool: str, decision: str) -> None:
+    emit("confirmation", tool=tool, decision=decision)
+
+
+@_quiet
+def version_change(from_version: str, to_version: str, was_behind: int = 0) -> None:
+    emit(
+        "version_change",
+        from_version=from_version,
+        to_version=to_version,
+        was_behind=was_behind,
+    )
+
+
+def tracked(tool_name: str):
+    """Decorator for an MCP tool, which runs in its own process.
+
+    That process has no ``job_queue`` and no shared heap, so the event goes
+    straight to its own ``spool.<pid>.jsonl`` and the host drains it later. Only
+    the tool name, whether it worked, and how long it took — never arguments,
+    never results.
+    """
+
+    def decorator(fn):
+        @functools.wraps(fn)
+        async def wrapper(*args, **kwargs):
+            started = time.monotonic()
+            ok = True
+            try:
+                return await fn(*args, **kwargs)
+            except Exception:
+                ok = False
+                raise
+            finally:
+                emit(
+                    "mcp_tool",
+                    tool=tool_name,
+                    ok=ok,
+                    duration_ms=int((time.monotonic() - started) * 1000),
+                )
+
+        return wrapper
+
+    return decorator
+
+
+# ── Jobs ─────────────────────────────────────────────────────────────────
+
+
+async def flush_job(context) -> None:
+    """The only place in the process that may talk to a collector."""
+    from condor.telemetry import emitter
+
+    await emitter.flush("job")
+
+
+async def heartbeat_job(context) -> None:
+    """Proof of life from an install that did nothing else this cycle."""
+    try:
+        if not _on():
+            return
+        from condor.telemetry import context as ctx
+
+        cutoff = time.time() - 24 * 3600
+        for hashed, seen in list(_seen_users.items()):
+            if seen < cutoff:
+                _seen_users.pop(hashed, None)
+        surfaces = dict(_surface_counts)
+        _surface_counts.clear()
+        emit(
+            "heartbeat",
+            uptime_h=ctx.uptime_h(),
+            active_users_24h=len(_seen_users),
+            surfaces=surfaces,
+        )
+    except Exception:  # noqa: BLE001
+        log.debug("Heartbeat tap failed", exc_info=True)
+
+
+def register_jobs(application) -> None:
+    """Register the flush and heartbeat jobs, the house pattern from
+    ``handlers.admin.update.schedule_update_checks``.
+
+    Registered unconditionally: the jobs are cheap, and both return immediately
+    when consent is absent. That keeps a mid-run opt-in working without a
+    restart.
+    """
+    try:
+        queue = getattr(application, "job_queue", None)
+        if queue is None:
+            return
+        for name in (TELEMETRY_FLUSH_JOB, TELEMETRY_HEARTBEAT_JOB):
+            for job in queue.get_jobs_by_name(name):
+                job.schedule_removal()
+        queue.run_repeating(
+            flush_job, interval=FLUSH_INTERVAL_S, first=60, name=TELEMETRY_FLUSH_JOB
+        )
+        queue.run_repeating(
+            heartbeat_job,
+            interval=HEARTBEAT_INTERVAL_S,
+            first=120,
+            name=TELEMETRY_HEARTBEAT_JOB,
+        )
+    except Exception:  # noqa: BLE001
+        log.debug("Could not register telemetry jobs", exc_info=True)
diff --git a/config_manager.py b/config_manager.py
index 4182acab..cf2dc723 100644
--- a/config_manager.py
+++ b/config_manager.py
@@ -150,6 +150,7 @@ def _load_config(self):
         self._data.setdefault("server_access", {})
         self._data.setdefault("chat_defaults", {})
         self._data.setdefault("user_preferences", {})
+        self._data.setdefault("telemetry", {})
         # Migrate audit_log from config.yml to separate file (one-time)
         if "audit_log" in self._data:
             self._audit_log = self._data.pop("audit_log")
@@ -174,6 +175,7 @@ def _default_data(self) -> dict:
             "server_access": {},
             "chat_defaults": {},
             "user_preferences": {},
+            "telemetry": {},
             "version": self.VERSION,
         }
 
@@ -216,6 +218,7 @@ def _save_config(self):
                 "server_access": self._data.get("server_access", {}),
                 "chat_defaults": self._data.get("chat_defaults", {}),
                 "web_jwt_secret": self._data.get("web_jwt_secret"),
+                "telemetry": self._data.get("telemetry", {}),
                 "version": self._data.get("version", self.VERSION),
             }
             # Keep a copy of the last known-good file before truncating it,
@@ -586,6 +589,27 @@ async def close_all_clients(self):
     # USER MANAGEMENT
     # =========================================================================
 
+    # ── Telemetry (FEAT-023) ──
+    # Consent and the install's random identity live here because this file is
+    # the one durable, process-wide store the MCP subprocess can also read.
+    # Nothing in this section is transmitted except `install_id` and `level`;
+    # `install_secret` never leaves the machine. See PRIVACY.md.
+
+    def get_telemetry(self) -> dict:
+        """The telemetry section. Empty dict on an install that never opted in."""
+        section = self._data.get("telemetry")
+        return dict(section) if isinstance(section, dict) else {}
+
+    def update_telemetry(self, **changes) -> dict:
+        """Merge keys into the telemetry section and persist."""
+        section = self._data.setdefault("telemetry", {})
+        if not isinstance(section, dict):
+            section = {}
+            self._data["telemetry"] = section
+        section.update(changes)
+        self._save_config()
+        return dict(section)
+
     def get_user(self, user_id: int) -> Optional[dict]:
         """Get user record."""
         return self._data.get("users", {}).get(user_id)
diff --git a/utils/config.py b/utils/config.py
index 14d7631a..c0d6e160 100644
--- a/utils/config.py
+++ b/utils/config.py
@@ -31,3 +31,18 @@
 else:
     WEB_PORT = int(_web_port_raw) if _web_port_raw else 8088
     WEB_URL = f"http://localhost:{WEB_PORT}"
+
+# ── Telemetry (FEAT-023) ──
+# Opt-in and OFF by default. Nothing is collected, buffered or sent unless the
+# install's admin has explicitly consented, or an operator sets CONDOR_TELEMETRY
+# here. An unset value is *not* "on": it means "no override", and the stored
+# consent decides — whose default is `unknown`, which emits nothing.
+#   off   - nothing, ever. emit() returns immediately.
+#   ping  - install / heartbeat / version_change / shutdown only.
+#   usage - the full allowlisted taxonomy in condor/telemetry/schema.py.
+CONDOR_TELEMETRY = os.environ.get("CONDOR_TELEMETRY", "").strip().lower() or None
+
+# Where a batch would be POSTed. Deliberately unset by default and NOT baked
+# into the source: with no URL the send path is inert, and events can only ever
+# accumulate in the local capped outbox. See PRIVACY.md.
+CONDOR_TELEMETRY_URL = os.environ.get("CONDOR_TELEMETRY_URL", "").strip() or None

From 5412f80cc36cda91691d8cee569070cdf93965fe Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Tue, 11 Aug 2026 23:37:51 +0300
Subject: [PATCH 014/116] Tap the seams that already exist, instead of every
 call site (FEAT-023)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Instrumentation goes where the codebase already funnels things, so almost no
handler is touched and nothing has to be kept in sync by hand:

- main.py: one TypeHandler in group -1 sees every command and every callback,
  because PTB dispatches each update to every group. It reads authorization
  state but never calls into @restricted — observing must not become an
  access-control side effect. The error handler reports the exception type, a
  hash of the message and our own stack frames; never the message.
- web/app.py: one middleware, keyed on the matched route *template*, so
  cardinality is bounded by our own router and no path parameter is ever read.
- runtime/client.py: prompt() is the one funnel Telegram, the dashboard and MCP
  all cross, and its finally: already runs on abandonment. Tool calls are
  counted by ACP `kind`, not by `title` — a title is free text and routinely
  contains a file path.
- engine.py, routine_store.py, confirmations.py, updater.py: session shape,
  routine outcome, approval decision, version adoption.
- mcp/server.py: the server runs in its own process with no job_queue, so its
  13 tools spool to a pid-scoped file the host drains.

The consent prompt rides next to the "Condor is online" message the admin
already gets, since that is the one moment they are looking. Three buttons,
written to disk before it is sent so a crash loop cannot re-ask forever.

The web middleware deliberately lets call_next raise: swallowing it would turn
an unhandled route exception into "no response returned" instead of the 500 it
is. Everything else swallows, twice.
---
 condor/agents/engine.py         | 14 +++++++++
 condor/routine_store.py         | 20 ++++++++++++
 condor/runtime/client.py        | 52 ++++++++++++++++++++++++++++++-
 condor/runtime/confirmations.py | 11 +++++++
 condor/telemetry/taps.py        | 21 +++++--------
 condor/web/app.py               |  7 +++++
 main.py                         | 55 +++++++++++++++++++++++++++++++++
 mcp_servers/condor/server.py    | 25 +++++++++++++++
 utils/updater.py                | 20 ++++++++++++
 9 files changed, 210 insertions(+), 15 deletions(-)

diff --git a/condor/agents/engine.py b/condor/agents/engine.py
index 820cdbe4..a390fcdb 100644
--- a/condor/agents/engine.py
+++ b/condor/agents/engine.py
@@ -28,6 +28,7 @@
 )
 from condor.acp.pydantic_ai_client import PydanticAIClient, is_pydantic_ai_model
 from condor.runtime.registry_file import LoopState
+from condor.telemetry import taps as telemetry_taps
 
 from .agent import Agent
 from .journal import JournalManager, next_experiment_number, next_session_number
@@ -110,6 +111,9 @@ class TickEngine:
     _cached_routines_section: str | None = field(default=None, init=False, repr=False)
     _adoption_done: bool = field(default=False, init=False, repr=False)
     _mode_mismatch_noted: bool = field(default=False, init=False, repr=False)
+    # Why the loop ended, for the strategy_run telemetry event: "user" unless
+    # something in the loop set it first.
+    _last_stop_reason: str = field(default="user", init=False, repr=False)
     # Session canvas + live report (FEAT-036). Both None for experiments, which
     # keep no journal and therefore no narrative to render.
     _session_report: "SessionReport | None" = field(
@@ -261,6 +265,13 @@ async def stop(self) -> None:
         # from there; the gap in between belongs to no session, which is the truth.
         if self.ledger is not None:
             self.ledger.release()
+        # Shape of the session for telemetry (FEAT-023): mode, cadence and tick
+        # count. Never the playbook, the journal, the pairs or the positions.
+        telemetry_taps.strategy_run(
+            self.config,
+            ticks=getattr(self.journal, "tick_count", 0) or 0,
+            stopped_by=self._last_stop_reason,
+        )
         if self.journal:
             self.journal.close()
         _supervisor().unregister(self.agent_id, LoopState.STOPPED)
@@ -282,6 +293,7 @@ async def _run_shutdown(self, reason: str) -> None:
         if self._shutting_down:
             return
         self._shutting_down = True
+        self._last_stop_reason = "shutdown"
         # Halt the loop so no next/concurrent tick fights the winddown.
         self._running = False
         self._paused = True
@@ -394,6 +406,7 @@ async def _loop(self) -> None:
                         label,
                     )
                     await self._notify(f"Agent {self.agent_id}: {label} complete.")
+                    self._last_stop_reason = "complete"
                     self._running = False
                     _supervisor().unregister(self.agent_id, LoopState.COMPLETED)
                     return
@@ -409,6 +422,7 @@ async def _loop(self) -> None:
                     await self._notify(
                         f"Agent {self.agent_id}: completed {max_ticks} ticks (max_ticks limit)."
                     )
+                    self._last_stop_reason = "max_ticks"
                     self._running = False
                     self.journal.close()
                     _supervisor().unregister(self.agent_id, LoopState.COMPLETED)
diff --git a/condor/routine_store.py b/condor/routine_store.py
index e3ff7124..63f90513 100644
--- a/condor/routine_store.py
+++ b/condor/routine_store.py
@@ -17,6 +17,7 @@
 
 import condor.reports as reports
 from condor import routine_hooks
+from condor.telemetry import taps as telemetry_taps
 from routines.base import (
     RoutineResult,
     discover_routines,
@@ -412,6 +413,7 @@ async def _execute_and_record(
         failed_status: str | None = None,
         fire_hooks: bool = True,
         agent: str = "",
+        trigger: str = "other",
     ) -> None:
         """Run a routine once, store the result, update instance metadata, fire hooks.
 
@@ -479,6 +481,20 @@ async def _execute_and_record(
                 }
             )
 
+        # Usage telemetry (FEAT-023): whether it ran, how it was triggered and
+        # how long it took. The routine's own name only when the file ships in
+        # this repo — a user's private routine is called `custom` — and never
+        # its config, its output or its error text.
+        telemetry_taps.routine_run(
+            routine=telemetry_taps.shipped_routine_name(
+                (routine.name or "").split("/")[-1]
+            ),
+            kind="continuous" if getattr(routine, "continuous", False) else "oneshot",
+            trigger=trigger,
+            duration_ms=int(duration * 1000),
+            ok=not failed,
+        )
+
         await self._report_run(instance_id, summary, error_msg)
 
         if fire_hooks:
@@ -547,6 +563,7 @@ async def _run_oneshot(
         server_name: str,
         user_id: int = 0,
         agent: str = "",
+        trigger: str = "manual",
     ) -> None:
         await self._execute_and_record(
             instance_id,
@@ -557,6 +574,7 @@ async def _run_oneshot(
             status_after="completed",
             failed_status="failed",
             agent=agent,
+            trigger=trigger,
         )
 
     async def start_continuous(
@@ -618,6 +636,7 @@ async def _run_continuous(
             status_after="stopped",
             fire_hooks=False,
             agent=agent,
+            trigger="manual",
         )
 
     async def schedule(
@@ -670,6 +689,7 @@ async def _run_scheduled(
                     server_name,
                     user_id,
                     status_after="scheduled",
+                    trigger="schedule",
                 )
                 # A cancel that lands mid-run is swallowed (and recorded) by
                 # _execute_and_record; stop() removed the instance, so bail out
diff --git a/condor/runtime/client.py b/condor/runtime/client.py
index ad41437f..881f6e4b 100644
--- a/condor/runtime/client.py
+++ b/condor/runtime/client.py
@@ -14,13 +14,16 @@
 
 import logging
 import os
+import time
 from typing import AsyncIterator, Literal
 
+from condor.acp.pydantic_ai_client import model_prefix
 from condor.runtime import conversations
-from condor.runtime.events import RuntimeEvent
+from condor.runtime.events import EventType, RuntimeEvent
 from condor.runtime.keys import SessionKey
 from condor.runtime.models import PromptRequest, SessionInfo, SessionSpec
 from condor.runtime.timeouts import TIMEOUTS
+from condor.telemetry import taps as telemetry_taps
 
 log = logging.getLogger(__name__)
 
@@ -134,6 +137,27 @@ def _deny_pending_confirmations(raw_key: str) -> None:
         log.info("Denied %d pending confirmation(s) on steering %s", denied, raw_key)
 
 
+# Session surfaces are short codes; the telemetry taxonomy spells them out.
+_SURFACES = {"tg": "telegram", "web": "web", "mcp": "mcp", "": "other"}
+
+
+def _turn_kind(req: PromptRequest, key: SessionKey) -> str:
+    """Which kind of turn this was, from what the request already carries."""
+    kind = (getattr(req, "user_kind", "") or "").lower()
+    if kind in ("consult", "delegate", "tick"):
+        return kind
+    return "chat"
+
+
+def _model_of(agent_key: str) -> str:
+    """The model id without any custom-endpoint nickname.
+
+    ``custom@venice:llama-3.3-70b`` reports ``llama-3.3-70b``: the nickname is
+    something the operator typed and may name their employer or their host.
+    """
+    return agent_key.split(":", 1)[1] if ":" in agent_key else agent_key
+
+
 async def prompt(
     key: SessionKey,
     req: PromptRequest,
@@ -197,12 +221,25 @@ async def prompt(
         # as a system note rather than as the user's words.
         user_kind=req.user_kind,
     )
+    # Turn shape for telemetry (FEAT-023): counts and categories only. Nothing
+    # about what was asked, answered, or which file a tool touched.
+    started = time.monotonic()
+    tool_kinds: dict[str, int] = {}
+    outcome = "aborted"
     try:
         async for event in session.prompt_stream(req.text, lock_timeout=lock_timeout):
             runtime_event = RuntimeEvent.from_acp(event, session_key=raw_key)
+            if runtime_event.type is EventType.TOOL_CALL:
+                # The ACP `kind` ("read", "execute", …), never the `title`: a
+                # title is free text and routinely contains a file path.
+                kind = str(runtime_event.field("kind") or "other")
+                tool_kinds[kind] = tool_kinds.get(kind, 0) + 1
+            elif runtime_event.type is EventType.DONE:
+                outcome = "done"
             recorder.observe(runtime_event)
             yield runtime_event
     except Exception as exc:  # noqa: BLE001 - surfaced to the caller as an event
+        outcome = "error"
         log.exception("Prompt failed for session %s", raw_key)
         failure = RuntimeEvent.error(str(exc), session_key=raw_key)
         recorder.observe(failure)
@@ -214,6 +251,19 @@ async def prompt(
         # abandoned async generator only ever gets GeneratorExit. Losing the
         # half-written reply is the bug this feature exists to fix.
         recorder.flush()
+        # Here for the same reason: this is the one funnel Telegram, the
+        # dashboard and MCP all cross, and it is the only place that sees an
+        # abandoned turn end.
+        telemetry_taps.agent_turn(
+            kind=_turn_kind(req, key),
+            provider=model_prefix(session.agent_key) or "acp",
+            model=_model_of(session.agent_key),
+            tool_calls=sum(tool_kinds.values()),
+            duration_ms=int((time.monotonic() - started) * 1000),
+            outcome=outcome,
+            surface=_SURFACES.get(getattr(key, "surface", ""), "other"),
+            tools=tool_kinds,
+        )
 
 
 async def prompt_once(key: SessionKey, text: str) -> str:
diff --git a/condor/runtime/confirmations.py b/condor/runtime/confirmations.py
index c065a718..d18821e6 100644
--- a/condor/runtime/confirmations.py
+++ b/condor/runtime/confirmations.py
@@ -26,6 +26,7 @@
 from typing import Any, Protocol
 
 from condor.runtime.timeouts import TIMEOUTS
+from condor.telemetry import taps as telemetry_taps
 
 log = logging.getLogger(__name__)
 
@@ -44,6 +45,12 @@ class ConfirmationStatus(str, Enum):
     TIMEOUT = "timeout"
 
 
+def _tool_of(pending: "PendingConfirmation") -> str:
+    """The tool name out of a tool_call payload, for telemetry only."""
+    call = pending.tool_call or {}
+    return str(call.get("name") or call.get("kind") or "unknown")
+
+
 @dataclass
 class PendingConfirmation:
     """One approval request, awaiting a human."""
@@ -184,6 +191,9 @@ async def resolve(
         )
         pending.selected_option_id = option_id
         pending._event.set()
+        # Which tool was asked about and what was decided (FEAT-023). Never the
+        # summary, the arguments or who decided.
+        telemetry_taps.confirmation(_tool_of(pending), "allow" if approved else "deny")
         return True
 
     def get(self, confirmation_id: str) -> PendingConfirmation | None:
@@ -236,6 +246,7 @@ def sweep(self) -> int:
             ):
                 pending.status = ConfirmationStatus.TIMEOUT
                 pending._event.set()  # wake any waiter immediately
+                telemetry_taps.confirmation(_tool_of(pending), "timeout")
             elif pending.status is not ConfirmationStatus.PENDING:
                 # Give the waiter a grace period to read the outcome first.
                 if now - pending.expires_at > CLEANUP_INTERVAL:
diff --git a/condor/telemetry/taps.py b/condor/telemetry/taps.py
index 181d29b7..c32117e5 100644
--- a/condor/telemetry/taps.py
+++ b/condor/telemetry/taps.py
@@ -59,18 +59,6 @@ def wrapper(*args, **kwargs):
     return wrapper
 
 
-def _quiet_async(fn):
-    @functools.wraps(fn)
-    async def wrapper(*args, **kwargs):
-        try:
-            return await fn(*args, **kwargs)
-        except Exception:  # noqa: BLE001
-            log.debug("Telemetry tap %s failed", fn.__name__, exc_info=True)
-            return None
-
-    return wrapper
-
-
 def _on() -> bool:
     from condor.telemetry import consent
 
@@ -251,9 +239,14 @@ def _route_action(request) -> tuple[str, str] | None:
     return module, verb
 
 
-@_quiet_async
 async def web_tap(request, call_next):
-    """ASGI middleware: one ``action`` per API call, with its status code."""
+    """ASGI middleware: one ``action`` per API call, with its status code.
+
+    Deliberately not wrapped in a swallow-everything decorator: ``call_next``
+    must be allowed to raise, or an unhandled route exception would surface as
+    "no response returned" instead of the 500 it is. Only the observation is
+    guarded.
+    """
     response = await call_next(request)
     try:
         if _on() and str(request.url.path).startswith("/api/"):
diff --git a/condor/web/app.py b/condor/web/app.py
index e5da32c2..c85930f5 100644
--- a/condor/web/app.py
+++ b/condor/web/app.py
@@ -9,6 +9,7 @@
 from fastapi.responses import FileResponse
 from fastapi.staticfiles import StaticFiles
 
+from condor.telemetry.taps import web_tap
 from condor.web.routes import (
     agents,
     archived,
@@ -62,6 +63,12 @@ def create_app() -> FastAPI:
         allow_headers=["*"],
     )
 
+    # Usage telemetry (FEAT-023). Reports the matched route *template*
+    # (`/api/v1/bots/{name}`), never the URL, so cardinality is bounded by our
+    # own router and no path parameter — a bot name, a server name, a report id
+    # — is ever read. No-op unless the admin opted in.
+    app.middleware("http")(web_tap)
+
     # ── API routes ──
     app.include_router(auth.router, prefix="/api/v1")
     app.include_router(servers.router, prefix="/api/v1")
diff --git a/main.py b/main.py
index a5d96b0e..db1b7c4c 100644
--- a/main.py
+++ b/main.py
@@ -15,10 +15,12 @@
     CommandHandler,
     ContextTypes,
     MessageHandler,
+    TypeHandler,
     filters,
 )
 
 from condor.persistence import SafePicklePersistence
+from condor.telemetry import taps as telemetry_taps
 from handlers import cancel_command, clear_all_input_states
 from utils.auth import restricted
 from utils.config import TELEGRAM_TOKEN, WEB_PORT, WEB_URL
@@ -301,6 +303,13 @@ def register_handlers(application: Application) -> None:
     # Clear existing handlers
     application.handlers.clear()
 
+    # Usage telemetry observer (FEAT-023). PTB dispatches every update to every
+    # group, so one handler in group -1 sees every command and every callback
+    # without touching a single handler below. It only reads — it must never
+    # call into @restricted, or observing would become an authorization side
+    # effect — and it is a no-op unless the admin opted in.
+    application.add_handler(TypeHandler(Update, telemetry_taps.telegram_tap), group=-1)
+
     # Add command handlers
     application.add_handler(CommandHandler("start", start))
     application.add_handler(CommandHandler("portfolio", portfolio_command))
@@ -378,6 +387,16 @@ def register_handlers(application: Application) -> None:
         CallbackQueryHandler(admin_callback_handler, pattern="^admin:")
     )
 
+    # Telemetry consent prompt (FEAT-023): three buttons, admin only
+    from condor.telemetry import prompt as telemetry_prompt
+
+    application.add_handler(
+        CallbackQueryHandler(
+            telemetry_prompt.callback_handler,
+            pattern=f"^{telemetry_prompt.CALLBACK_PREFIX}:",
+        )
+    )
+
     # Add callback query handler for portfolio settings
     application.add_handler(get_portfolio_callback_handler())
 
@@ -594,6 +613,20 @@ async def startup(application: Application) -> None:
 
     schedule_update_checks(application)
 
+    # Usage telemetry (FEAT-023). init() resolves the consent level once so the
+    # taps never read the disk on a hot path, and only materializes the
+    # install's random ids when telemetry is actually on. The jobs are
+    # registered either way and return immediately while consent is absent, so
+    # opting in mid-run works without a restart.
+    from condor import telemetry
+
+    try:
+        level = telemetry.init(hosted=True)
+        telemetry_taps.register_jobs(application)
+        logger.info("Telemetry level: %s", level)
+    except Exception:
+        logger.exception("Telemetry init failed (continuing without it)")
+
     # Start file watcher
     asyncio.create_task(watch_and_reload(application))
 
@@ -647,6 +680,16 @@ async def teardown(application: Application) -> None:
 
     await hummingbot_client.close()
 
+    # Record the clean exit and give the outbox one last chance. Both are no-ops
+    # unless the admin opted in, and neither can fail the shutdown.
+    try:
+        from condor import telemetry
+
+        telemetry.shutdown("signal")
+        await telemetry.flush("teardown")
+    except Exception:
+        logger.debug("Telemetry teardown failed", exc_info=True)
+
 
 async def watch_and_reload(application: Application) -> None:
     """Watch for file changes and reload handlers automatically."""
@@ -716,9 +759,14 @@ def get_persistence() -> SafePicklePersistence:
 async def error_handler(update: object, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Handle errors gracefully."""
     if isinstance(context.error, NetworkError):
+        # Expected and self-healing; reported as an upstream blip, not a bug.
+        telemetry_taps.on_upstream_error("telegram", "poll", "network")
         logger.warning(f"Network error (will retry): {context.error}")
         return
 
+    # Type, a hash of the message, and our own stack frames. Never the message
+    # itself — that is where balances, hostnames and keys leak.
+    telemetry_taps.on_error(context.error, where="telegram", surface="telegram")
     logger.exception("Exception while handling an update:", exc_info=context.error)
 
 
@@ -841,6 +889,13 @@ async def _run_dual(application: Application) -> None:
         except Exception as e:
             logger.warning(f"Failed to send startup notification to admin: {e}")
 
+        # Ask, once, whether this install wants to be counted (FEAT-023). Sent
+        # next to the boot notification because that is the one moment the admin
+        # is already looking. Until it is answered, nothing is collected.
+        from condor.telemetry.prompt import maybe_prompt_admin
+
+        await maybe_prompt_admin(application.bot)
+
     logger.info("Starting Condor: Telegram bot + web dashboard on port %s", WEB_PORT)
 
     # Handle shutdown signals
diff --git a/mcp_servers/condor/server.py b/mcp_servers/condor/server.py
index 008f5be0..657cd025 100644
--- a/mcp_servers/condor/server.py
+++ b/mcp_servers/condor/server.py
@@ -6,6 +6,7 @@
 
 from mcp.server.fastmcp import FastMCP
 
+from condor.telemetry import taps as telemetry_taps
 from mcp_servers.condor.middleware import handle_errors
 from mcp_servers.condor.tools import available_models as available_models_tool
 from mcp_servers.condor.tools import consult as consult_tool
@@ -282,6 +283,7 @@ def _build_instructions() -> str:
 
 @mcp.tool()
 @handle_errors("consult agent")
+@telemetry_taps.tracked("consult")
 async def consult(agent: str, task: str, context: str = "") -> dict:
     """Consult a specialized domain agent and get its answer.
 
@@ -303,6 +305,7 @@ async def consult(agent: str, task: str, context: str = "") -> dict:
 
 @mcp.tool()
 @handle_errors("delegate task")
+@telemetry_taps.tracked("delegate")
 async def delegate(
     action: str,
     agent: str = "",
@@ -359,6 +362,7 @@ async def delegate(
 
 @mcp.tool()
 @handle_errors("send notification")
+@telemetry_taps.tracked("send_notification")
 async def send_notification(
     text: str,
     parse_mode: str = "Markdown",
@@ -377,6 +381,7 @@ async def send_notification(
 
 @mcp.tool()
 @handle_errors("manage routines")
+@telemetry_taps.tracked("manage_routines")
 async def manage_routines(
     action: str,
     name: str | None = None,
@@ -451,6 +456,7 @@ async def manage_routines(
 
 @mcp.tool()
 @handle_errors("manage servers")
+@telemetry_taps.tracked("manage_servers")
 async def manage_servers(
     action: str,
     name: str | None = None,
@@ -473,6 +479,7 @@ async def manage_servers(
 
 @mcp.tool()
 @handle_errors("get user context")
+@telemetry_taps.tracked("get_user_context")
 async def get_user_context() -> dict:
     """Get the current user's context within Condor.
 
@@ -487,6 +494,7 @@ async def get_user_context() -> dict:
 
 @mcp.tool()
 @handle_errors("get available models")
+@telemetry_taps.tracked("get_available_models")
 async def get_available_models(
     openrouter_query: str = "", openrouter_limit: int = 20
 ) -> dict:
@@ -543,6 +551,7 @@ async def get_available_models(
 
 @mcp.tool()
 @handle_errors("manage trading agent")
+@telemetry_taps.tracked("manage_trading_agent")
 async def manage_trading_agent(
     action: str,
     agent_id: str | None = None,
@@ -657,6 +666,7 @@ async def manage_trading_agent(
 
 @mcp.tool()
 @handle_errors("manage memory")
+@telemetry_taps.tracked("manage_memory")
 async def manage_memory(
     action: str,
     name: str | None = None,
@@ -710,6 +720,7 @@ async def manage_memory(
 
 @mcp.tool()
 @handle_errors("manage skill")
+@telemetry_taps.tracked("manage_skill")
 async def manage_skill(
     action: str,
     name: str | None = None,
@@ -818,6 +829,7 @@ async def manage_skill(
 
 @mcp.tool()
 @handle_errors("manage notes")
+@telemetry_taps.tracked("manage_notes")
 async def manage_notes(
     action: str,
     key: str | None = None,
@@ -855,6 +867,7 @@ async def manage_notes(
 
 @mcp.tool()
 @handle_errors("journal read")
+@telemetry_taps.tracked("trading_agent_journal_read")
 async def trading_agent_journal_read(
     agent_id: str,
     section: str = "recent",
@@ -882,6 +895,7 @@ async def trading_agent_journal_read(
 
 @mcp.tool()
 @handle_errors("journal write")
+@telemetry_taps.tracked("trading_agent_journal_write")
 async def trading_agent_journal_write(
     agent_id: str,
     entry_type: str,
@@ -933,4 +947,15 @@ async def trading_agent_journal_write(
 
 
 if __name__ == "__main__":
+    # This server runs in its own process, spawned by the agent: a different
+    # interpreter, a different heap, and no job_queue. hosted=False makes emit()
+    # append to `spool.<pid>.jsonl`, which the host process drains and deletes.
+    # Still a no-op unless the install opted in.
+    try:
+        from condor import telemetry
+
+        telemetry.init(hosted=False)
+    except Exception:  # noqa: BLE001 - never block the server on telemetry
+        pass
+
     mcp.run()
diff --git a/utils/updater.py b/utils/updater.py
index e5e9df78..63692b04 100644
--- a/utils/updater.py
+++ b/utils/updater.py
@@ -179,11 +179,31 @@ async def pull_updates(repo_dir: str = CONDOR_DIR) -> tuple[bool, str]:
             "Cannot update: there are uncommitted changes. Please commit or stash first.",
         )
 
+    # The sha we are leaving, so a successful pull can report what it moved.
+    before = await get_local_commit(repo_dir)
+
     # Pull
     rc, output = await _run_git("pull", "origin", branch, repo_dir=repo_dir)
     if rc != 0:
         return False, f"Pull failed:\n{output}"
 
+    # Version adoption telemetry (FEAT-023): two short shas and how far behind
+    # this install had drifted. Only for the Condor repo itself, and a no-op
+    # unless the admin opted in.
+    try:
+        after = await get_local_commit(repo_dir)
+        if repo_dir == CONDOR_DIR and before and after and before != after:
+            _, behind = await _run_git(
+                "rev-list", "--count", f"{before}..{after}", repo_dir=repo_dir
+            )
+            from condor.telemetry import taps as telemetry_taps
+
+            telemetry_taps.version_change(
+                before, after, int(behind) if behind.strip().isdigit() else 0
+            )
+    except Exception:
+        logger.debug("Could not record version change", exc_info=True)
+
     return True, output
 
 

From e9e93618b050742b56cef24430f28a7939172a59 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Tue, 11 Aug 2026 23:42:11 +0300
Subject: [PATCH 015/116] Say plainly what telemetry collects, and prove it in
 tests (FEAT-023)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

PRIVACY.md is the deliverable a suspicious user actually reads: a table of what
is collected, a longer table of what never is, where it goes (nowhere, without
a configured endpoint), and three ways to turn it off — including a one-line
command that prints the authoritative answer. The README links it from the
block that already opens the file with a security warning.

tests/test_telemetry.py is the other half, because a privacy claim that is not
asserted is a promise. The load-bearing tests are the negative ones:

- a fresh install with no consent emits nothing and creates no directory, at
  the emitter and again at the Telegram seam;
- every declared event is fed a props dict stuffed with amounts, balances,
  keys, wallets, pairs, server URLs, user ids, prompts and a 10 KB string, and
  none of it survives sanitize();
- an exception's message never appears in its event, only the type and a hash;
- `admin:approve_843214321` reports `approve`;
- emit() returns cleanly from an unknown event, a repr that raises, None props
  and a thread with no event loop — and a schema that throws cannot reach the
  caller, which is the blast-radius guarantee main.py depends on.

Also a settings endpoint so the answer is reversible without editing YAML:
GET/PUT /api/v1/settings/telemetry, admin only, and 409 when CONDOR_TELEMETRY
pins the level from the environment. Turning it off is a withdrawal — the
buffer and the outbox are deleted, not merely ignored.
---
 PRIVACY.md                    | 143 ++++++++++
 README.md                     |   6 +
 condor/telemetry/prompt.py    |  12 +-
 condor/web/routes/settings.py |  56 ++++
 tests/test_telemetry.py       | 514 ++++++++++++++++++++++++++++++++++
 5 files changed, 725 insertions(+), 6 deletions(-)
 create mode 100644 PRIVACY.md
 create mode 100644 tests/test_telemetry.py

diff --git a/PRIVACY.md b/PRIVACY.md
new file mode 100644
index 00000000..3cfc426f
--- /dev/null
+++ b/PRIVACY.md
@@ -0,0 +1,143 @@
+# Privacy
+
+Condor is self-hosted. It runs on your machine, holds your exchange API keys,
+and places your orders. So the default for anything that could leave that
+machine is **off**, and this document is the complete statement of what the one
+optional exception does.
+
+**Short version:** a fresh install sends nothing. It has no telemetry consent
+recorded, which resolves to level `off`, at which the emitter returns before it
+has looked at its arguments — no buffer, no file, no directory. Nothing changes
+until an admin taps "yes" on a prompt. Even then, this repository has no
+collector address compiled into it: with `CONDOR_TELEMETRY_URL` unset, the send
+path is inert and events can only ever reach a capped local file.
+
+The whole mechanism is about 900 lines in [`condor/telemetry/`](condor/telemetry/).
+It is meant to be read, not trusted.
+
+---
+
+## What is collected, if you opt in
+
+There are three levels. You choose one; you can change it later.
+
+| Level | What it sends |
+|---|---|
+| `off` | Nothing, ever. The emitter is a no-op. **This is the default.** |
+| `ping` | Only that this install exists: `install`, `heartbeat`, `version_change`, `shutdown`. |
+| `usage` | The above plus the feature, reliability and agent events below. |
+
+Every batch carries one context block describing the *deployment*, not you:
+
+| Field | Example | Why |
+|---|---|---|
+| `install_id` | a random UUID | Count installs and retention. Generated once, from `uuid4`. Not derived from your MAC, hostname, username, or any token. |
+| `app.version`, `app.branch` | `54ad4dc`, `main` | Which commit is actually running, so we know what to support. |
+| `app.python`, `app.os`, `app.arch`, `app.in_docker` | `3.12`, `linux`, `arm64`, `true` | What to test against. |
+| `config.*` | `has_gateway: true`, `user_count: 3`, `server_count: 2`, `llm_providers: ["openai"]` | Counts and capability flags. Numbers and fixed provider *names* — never a server name, never a URL, never a key. |
+| `dropped` | `0` | How many events the rate limiter discarded. An honest count, so a quiet incident is visibly quiet. |
+
+And the events themselves:
+
+| Event | What it carries |
+|---|---|
+| `command` | Which of our ~20 commands was used (anything else is `other`), the surface, and whether the sender was an approved user. |
+| `action` | A module (`bots`, `dex`, `agents`, …) and a verb (`view`, `deploy`, `start`). On the web, derived from the matched route *template* — `/api/v1/bots/{name}`, never the URL. |
+| `feature_first_use` | The first time this install ever uses a feature. |
+| `bot_deploy`, `executor_deploy`, `trade` | Connector name, controller/executor type, side, order type, paper-or-not. |
+| `routine_run` | The routine's name **only if it ships in this repo** — a routine you wrote is reported as `custom` — plus how it was triggered, how long it took, and whether it worked. |
+| `error` | The exception *type*, a SHA-256 hash of its message, and up to five `file:line` frames from our own packages, relative to the repo root. |
+| `upstream_error` | Which dependency (`hb_api`, `gateway`, `llm`, `telegram`), which operation, which status code. |
+| `agent_turn` | Provider and model id, tool-call count by category, duration, outcome. |
+| `mcp_tool` | Which MCP tool ran, whether it worked, how long it took. |
+| `strategy_run` | Execution mode, tick frequency, tick count, whether risk limits were configured, why it stopped. |
+| `confirmation` | Which tool was asked about, and whether it was allowed, denied, or timed out. |
+| `heartbeat` | Uptime, a *count* of distinct users active in the last 24h, and a per-surface activity count. |
+
+## What is never collected
+
+This is not a policy the call sites are asked to respect. Every event and every
+property is declared in [`condor/telemetry/schema.py`](condor/telemetry/schema.py),
+and anything undeclared is **dropped** on the way in. Free-form strings are
+truncated to 64 characters and stripped to identifier-shaped characters, so
+nothing long enough to be a key, an address, a prompt or a URL survives intact.
+[`tests/test_telemetry.py`](tests/test_telemetry.py) asserts it.
+
+Never sent, under any level:
+
+- **Secrets** — API keys, secret keys, passphrases, private keys, your Telegram bot token.
+- **Money** — order amounts, balances, portfolio value, PnL, position sizes, leverage.
+- **Positions** — trading pairs. Deliberately excluded: an install that trades one pair, plus event timestamps, is a deanonymizable disclosure of what you hold. Connector *names* are sent; pairs are not.
+- **Addresses and identifiers** — wallet addresses, order ids, transaction hashes.
+- **Your infrastructure** — server names, URLs, hostnames, IP addresses, file paths outside this repo, your home directory or username.
+- **People** — Telegram user ids, usernames, chat ids, display names.
+- **Content** — prompts, agent replies, journal entries, notes, routine configs, report bodies, and exception *message* strings.
+
+Two of those deserve a note, because they are where this kind of thing usually
+leaks:
+
+- **Exception messages are hashed, not sent.** A message string is the single
+  most common carrier of a balance, a hostname or a key. We send
+  `sha256(message)[:12]`, which groups identical errors together and discloses
+  nothing.
+- **Agent tool calls are counted by category, not by title.** A tool call's
+  title is free text and routinely contains a file path. We count the ACP
+  `kind` (`read`, `execute`, …) instead.
+
+### The one derived identifier
+
+`user_hash` lets the collector count how many distinct people use an install
+without knowing who they are. It is `sha256(install_secret + telegram_user_id)`,
+truncated to 16 characters, where `install_secret` is a random UUID that **never
+leaves your machine**. The Telegram id is never sent, and because the salt is
+per-install, the same person on two installs produces two unrelated hashes.
+
+## Where it goes
+
+Nowhere, unless you configure a destination.
+
+No collector URL is compiled into this repository. Events are buffered in memory
+and, when a batch cannot be delivered, appended to
+`condor/.runtime/telemetry/outbox.jsonl`, which is capped at 5,000 events and 7
+days — oldest dropped. With `CONDOR_TELEMETRY_URL` unset, that is the entire
+life cycle: a local file, capped, that you can delete.
+
+You can read exactly what would be sent:
+
+```bash
+cat condor/.runtime/telemetry/outbox.jsonl | jq .
+```
+
+## How to turn it off — or check it is off
+
+It is already off unless you turned it on. To be certain:
+
+```bash
+# The authoritative answer. Prints "off" on a default install.
+uv run python -c "from condor.telemetry import consent; print(consent.level())"
+```
+
+Three ways to control it, in order of precedence:
+
+1. **Environment** — `CONDOR_TELEMETRY=off` in your `.env`. This overrides
+   everything, in both directions, and is the right answer for a headless or
+   containerized install. `CONDOR_TELEMETRY_URL` is what enables sending at all;
+   leave it unset and nothing can be transmitted.
+2. **The dashboard API** — `PUT /api/v1/settings/telemetry?level=off` (admin
+   only). `GET` the same path to see the current state.
+3. **`config.yml`** — edit the `telemetry` section directly:
+
+   ```yaml
+   telemetry:
+     consent: denied
+     level: off
+   ```
+
+Turning it off is a **withdrawal, not a pause**: the in-memory buffer and the
+outbox file are deleted, so nothing already recorded can be sent afterwards.
+
+## Changes to this document
+
+Adding anything to the collected list requires a change to `schema.py`, a change
+to this file, and re-asking for consent. In particular, adding trading pairs
+would make positions inferable from timing and must not be done quietly.
diff --git a/README.md b/README.md
index 663a40be..1728aab6 100644
--- a/README.md
+++ b/README.md
@@ -10,6 +10,12 @@ A Telegram bot for monitoring and trading with Hummingbot via the **Hummingbot A
 >
 > Full walkthrough: [Securing Condor and Hummingbot API with Tailscale](https://hummingbot.org/blog/posts/securing-condor-and-hummingbot-api-with-tailscale/) · [Hummingbot API Tailscale guide](https://hummingbot.org/hummingbot-api/tailscale/)
 
+> **Privacy:** Condor collects nothing by default. It ships with usage telemetry
+> **off** and no collector address, and it stays that way unless an admin
+> explicitly opts in from the one prompt it sends on first boot. What that
+> option would and would not collect — and how to verify it is off — is spelled
+> out in [PRIVACY.md](PRIVACY.md).
+
 ## Features
 
 - **Portfolio Dashboard** - Comprehensive portfolio view with PNL tracking, 24h changes, and graphical analysis
diff --git a/condor/telemetry/prompt.py b/condor/telemetry/prompt.py
index 9c184637..dd3ee095 100644
--- a/condor/telemetry/prompt.py
+++ b/condor/telemetry/prompt.py
@@ -23,8 +23,8 @@
     "Never included: API keys, wallet addresses, server names or URLs, "
     "trading pairs, amounts, balances, positions, prompts or agent replies, "
     "and no Telegram id or username.\n\n"
-    "Full details in PRIVACY.md at the root of the repo. "
-    "You can change this any time from the dashboard settings."
+    "Full details in PRIVACY.md at the root of the repo, which also says how "
+    "to change or withdraw this answer at any time."
 )
 
 
@@ -113,15 +113,15 @@ async def callback_handler(update, context) -> None:
         if chosen == consent.PING:
             await query.edit_message_text(
                 "Thanks. Condor will only report that this install exists and "
-                "which version it runs. Change it any time in the dashboard "
-                "settings; details in PRIVACY.md."
+                "which version it runs. PRIVACY.md says how to change or "
+                "withdraw this."
             )
         else:
             await query.edit_message_text(
                 "Thanks. Condor will send anonymous usage and reliability "
                 "events. No keys, addresses, pairs, amounts or prompts ever "
-                "leave this machine. Change it any time in the dashboard "
-                "settings; details in PRIVACY.md."
+                "leave this machine. PRIVACY.md says how to change or withdraw "
+                "this."
             )
     except Exception:  # noqa: BLE001
         log.exception("Telemetry consent callback failed")
diff --git a/condor/web/routes/settings.py b/condor/web/routes/settings.py
index ba8e3676..cd82f4ad 100644
--- a/condor/web/routes/settings.py
+++ b/condor/web/routes/settings.py
@@ -607,3 +607,59 @@ async def delete_custom_provider(
     if not remove_custom_provider(load_user_data_for(user.id), name):
         raise HTTPException(status_code=404, detail=f"No saved endpoint '{name}'")
     return {"deleted": True, "name": name}
+
+
+# ── Telemetry (FEAT-023) ──
+
+
+@router.get("/telemetry")
+async def get_telemetry_settings(user: WebUser = Depends(get_current_user)):
+    """What this install has agreed to, and whether it could send anything.
+
+    ``endpoint_configured`` is the honest answer to "is this thing on": with no
+    ``CONDOR_TELEMETRY_URL`` set — the shipped state — nothing can be
+    transmitted no matter what the consent says, and events only accumulate in
+    a capped local file.
+    """
+    from condor.telemetry import consent, emitter, outbox
+
+    return {
+        "consent": consent.state(),
+        "level": consent.level(),
+        "env_overridden": consent.env_overridden(),
+        "endpoint_configured": bool(outbox.endpoint()),
+        "pending_events": emitter.buffered(),
+        "privacy_doc": "PRIVACY.md",
+    }
+
+
+@router.put("/telemetry")
+async def set_telemetry_settings(
+    level: str = Query(..., description="off | ping | usage"),
+    user: WebUser = Depends(get_current_user),
+):
+    """Change the install's telemetry level. Admin only, and reversible.
+
+    Setting ``off`` is a withdrawal, not a pause: the buffer and the outbox are
+    deleted, so nothing already recorded can be sent later.
+    """
+    from condor.telemetry import consent
+
+    cm = get_config_manager()
+    if not cm.is_admin(user.id):
+        raise HTTPException(
+            status_code=403,
+            detail="Telemetry is an install-wide setting; only the admin can change it",
+        )
+    if level not in consent.LEVELS:
+        raise HTTPException(
+            status_code=400, detail=f"level must be one of {', '.join(consent.LEVELS)}"
+        )
+    if consent.env_overridden():
+        raise HTTPException(
+            status_code=409,
+            detail="CONDOR_TELEMETRY is set in the environment and overrides this setting",
+        )
+
+    applied = consent.set_level(level)
+    return {"level": applied, "consent": consent.state()}
diff --git a/tests/test_telemetry.py b/tests/test_telemetry.py
new file mode 100644
index 00000000..739844a1
--- /dev/null
+++ b/tests/test_telemetry.py
@@ -0,0 +1,514 @@
+"""Telemetry (FEAT-023) — the tests that make the privacy promise checkable.
+
+The interesting assertions here are the negative ones. Most of this file exists
+to prove that things do *not* happen: that a default install emits nothing, that
+forbidden values cannot reach an envelope even when a caller hands them over,
+and that a tap can never take the host down with it.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import threading
+import time
+
+import pytest
+
+from condor.telemetry import consent, context, emitter, outbox, schema, taps
+
+
+@pytest.fixture
+def install(tmp_path, monkeypatch):
+    """An isolated install: its own config.yml, its own runtime dir, no env."""
+    import config_manager as cm_module
+
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setattr("utils.config.CONDOR_TELEMETRY", None, raising=False)
+    monkeypatch.setattr("utils.config.CONDOR_TELEMETRY_URL", None, raising=False)
+    monkeypatch.setattr(
+        "condor.agents.agent._DATA_ROOT", str(tmp_path / "data"), raising=False
+    )
+    cm_module.ConfigManager.reset_instance()
+    emitter.discard_buffer()
+    emitter.set_hosted(True)
+    consent.refresh()
+    yield tmp_path
+    cm_module.ConfigManager.reset_instance()
+    emitter.discard_buffer()
+    consent.refresh()
+
+
+def _grant(level="usage"):
+    from config_manager import get_config_manager
+
+    get_config_manager()  # materialize config.yml in the tmp cwd
+    consent.grant(level)
+
+
+# ── The default is silence ───────────────────────────────────────────────
+
+
+def test_a_fresh_install_is_off_and_stays_off(install):
+    """No consent recorded means no telemetry — not "buffered until asked"."""
+    assert consent.state() == consent.UNKNOWN
+    assert consent.level() == consent.OFF
+
+    for name in schema.EVENTS:
+        emitter.emit(name, surface="telegram")
+
+    assert emitter.buffered() == 0
+    assert emitter.dropped() == 0
+
+
+def test_nothing_is_written_to_disk_when_off(install):
+    """Acceptance criterion: no condor/.runtime/telemetry directory is created."""
+    emitter.set_hosted(False)  # the spooling path, which is the one that does I/O
+    emitter.emit("command", name="portfolio", surface="telegram")
+    assert not outbox.root().exists()
+    assert not (install / "config.yml").exists()
+
+
+def test_env_off_overrides_a_granted_consent(install, monkeypatch):
+    _grant("usage")
+    assert consent.level() == consent.USAGE
+
+    monkeypatch.setattr("utils.config.CONDOR_TELEMETRY", "off", raising=False)
+    consent.refresh()
+
+    assert consent.level() == consent.OFF
+    emitter.emit("command", name="bots", surface="telegram")
+    assert emitter.buffered() == 0
+
+
+def test_a_nonsense_env_level_is_ignored_not_obeyed(install, monkeypatch):
+    monkeypatch.setattr("utils.config.CONDOR_TELEMETRY", "yes-please", raising=False)
+    consent.refresh()
+    assert consent.level() == consent.OFF
+
+
+def test_ping_level_sends_only_the_adoption_events(install):
+    _grant("ping")
+    emitter.emit("heartbeat", uptime_h=1.0)
+    emitter.emit("command", name="portfolio", surface="telegram")
+    emitter.emit("trade", venue="cex", connector="binance", side="buy")
+
+    names = [e["name"] for e in emitter.drain()[0]]
+    assert names == ["heartbeat"]
+
+
+# ── Nothing transmits ────────────────────────────────────────────────────
+
+
+def test_flush_is_a_no_op_without_consent(install, monkeypatch):
+    """A full session of activity must produce zero outbound requests."""
+    calls = []
+    monkeypatch.setattr(outbox, "post", lambda env: calls.append(env))
+
+    for _ in range(50):
+        emitter.emit("command", name="portfolio", surface="telegram")
+    taps.on_error(RuntimeError("boom"), where="test")
+
+    assert asyncio.run(emitter.flush("test")) == 0
+    assert calls == []
+    assert not outbox.root().exists()
+
+
+def test_no_endpoint_means_events_only_ever_reach_a_local_file(install):
+    """The shipped state: consent granted, but nowhere to send. Nothing leaves."""
+    _grant("usage")
+    emitter.emit("command", name="portfolio", surface="telegram")
+
+    assert outbox.endpoint() is None
+    assert asyncio.run(emitter.flush("test")) == 0
+
+    stashed = outbox.take_stashed()
+    assert [e["name"] for e in stashed] == ["command"]
+
+
+def test_undelivered_events_are_retried_and_never_duplicated(install, monkeypatch):
+    _grant("usage")
+    monkeypatch.setattr(outbox, "endpoint", lambda: "http://collector.invalid")
+
+    attempts = []
+
+    async def failing_post(envelope):
+        attempts.append(envelope)
+        return False
+
+    monkeypatch.setattr(outbox, "post", failing_post)
+    emitter.emit("command", name="bots", surface="telegram")
+    assert asyncio.run(emitter.flush("first")) == 0
+
+    sent = []
+
+    async def ok_post(envelope):
+        sent.append(envelope)
+        return True
+
+    monkeypatch.setattr(outbox, "post", ok_post)
+    assert asyncio.run(emitter.flush("retry")) == 1
+
+    ids = [e["id"] for env in sent for e in env["events"]]
+    assert len(ids) == len(set(ids)) == 1
+
+
+def test_the_outbox_respects_its_cap(install):
+    _grant("usage")
+    now = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+    events = [
+        {"id": str(i), "ts": now, "name": "command", "props": {}}
+        for i in range(outbox.MAX_OUTBOX_EVENTS + 250)
+    ]
+    outbox.stash(events)
+    assert len(outbox.take_stashed()) == outbox.MAX_OUTBOX_EVENTS
+
+
+def test_denying_consent_destroys_what_was_collected(install):
+    _grant("usage")
+    emitter.emit("command", name="portfolio", surface="telegram")
+    outbox.stash(
+        [
+            {
+                "id": "x",
+                "ts": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+                "name": "command",
+            }
+        ]
+    )
+    assert outbox.outbox_path().exists()
+
+    consent.deny()
+
+    assert consent.level() == consent.OFF
+    assert emitter.buffered() == 0
+    assert not outbox.outbox_path().exists()
+
+
+# ── The leak test ────────────────────────────────────────────────────────
+
+FORBIDDEN = {
+    "amount": 12345.67,
+    "balance": 98765.43,
+    "pnl": -420.0,
+    "api_key": "sk-live-DEADBEEFCAFE",
+    "secret_key": "topsecret",
+    "wallet": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
+    "wallet_address": "0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef",
+    "trading_pair": "SOL-USDC",
+    "pair": "BTC-USDT",
+    "server_url": "http://10.0.0.4:8000",
+    "server_name": "my-vps",
+    "hostname": "trading-box.local",
+    "user_id": 843214321,
+    "username": "federico",
+    "chat_id": 12345,
+    "prompt": "buy me some sol",
+    "reply": "sure thing",
+    "order_id": "OID-99182",
+    "message": "Insufficient balance: 12.5 SOL",
+    "big": "x" * 10_000,
+}
+
+
+def test_no_forbidden_value_survives_any_declared_event(install):
+    """Feed every event a props dict stuffed with everything we promised never
+    to collect, and assert none of it comes out the other side."""
+    _grant("usage")
+
+    for name in schema.EVENTS:
+        clean = schema.sanitize(name, dict(FORBIDDEN))
+        blob = json.dumps(clean)
+
+        for key, value in FORBIDDEN.items():
+            assert key not in clean, f"{name} let through the key {key!r}"
+            assert str(value) not in blob, f"{name} let through the value of {key!r}"
+
+        for value in clean.values():
+            if isinstance(value, str):
+                assert len(value) <= schema.MAX_STR
+            if isinstance(value, list):
+                assert all(len(v) <= schema.MAX_STR for v in value)
+
+
+def test_an_undeclared_property_is_dropped_not_passed_through(install):
+    clean = schema.sanitize(
+        "trade",
+        {"venue": "cex", "connector": "binance", "amount": 5.0, "pair": "SOL-USDC"},
+    )
+    assert clean == {"venue": "cex", "connector": "binance"}
+
+
+def test_an_unknown_enum_value_is_snapped_to_other(install):
+    clean = schema.sanitize(
+        "command", {"name": "totally_made_up", "surface": "carrier_pigeon"}
+    )
+    assert clean == {"name": "other", "surface": "other"}
+
+
+def test_a_long_free_form_string_is_truncated(install):
+    clean = schema.sanitize("upstream_error", {"service": "llm", "op": "z" * 500})
+    assert len(clean["op"]) == schema.MAX_STR
+
+
+# ── emit() never raises ──────────────────────────────────────────────────
+
+
+class Unserializable:
+    def __repr__(self):  # pragma: no cover - must never be reached in a payload
+        raise RuntimeError("even repr explodes")
+
+
+def test_emit_survives_everything_a_caller_can_do_to_it(install):
+    _grant("usage")
+
+    emitter.emit("no_such_event_name", whatever=1)
+    emitter.emit("command", name=Unserializable(), surface=Unserializable())
+    emitter.emit("command", **{})
+    emitter.emit("error", frames=None, sig=None, where=None)
+
+    # And from a thread that has no event loop at all.
+    failures = []
+
+    def in_thread():
+        try:
+            emitter.emit("command", name="portfolio", surface="telegram")
+        except BaseException as exc:  # pragma: no cover - the assertion is below
+            failures.append(exc)
+
+    thread = threading.Thread(target=in_thread)
+    thread.start()
+    thread.join()
+    assert failures == []
+
+
+def test_a_broken_schema_cannot_break_the_caller(install, monkeypatch):
+    """The blast-radius test: telemetry failing must never propagate."""
+    _grant("usage")
+
+    def explode(*_a, **_kw):
+        raise ValueError("schema is on fire")
+
+    monkeypatch.setattr(schema, "sanitize", explode)
+    emitter.emit("command", name="portfolio", surface="telegram")  # must not raise
+
+    monkeypatch.setattr(consent, "level", explode)
+    emitter.emit("command", name="portfolio", surface="telegram")  # must not raise
+
+    # Undone here, not at teardown: the `install` fixture unwinds after
+    # monkeypatch and would otherwise call the exploding stub itself.
+    monkeypatch.undo()
+
+
+def test_a_broken_tap_cannot_break_a_handler(install, monkeypatch):
+    _grant("usage")
+    monkeypatch.setattr(taps, "emit", lambda *a, **kw: 1 / 0)
+
+    taps.on_error(RuntimeError("x"), where="test")
+    taps.confirmation("manage_bots", "allow")
+    taps.strategy_run({"execution_mode": "loop"}, ticks=3)
+    taps.routine_run(
+        routine="x", kind="oneshot", trigger="manual", duration_ms=1, ok=True
+    )
+    taps.agent_turn(kind="chat")
+    taps.version_change("aaa", "bbb", 2)
+
+
+def test_the_web_tap_lets_route_exceptions_through(install):
+    """Swallowing here would turn a 500 into "no response returned"."""
+    _grant("usage")
+
+    class Req:
+        url = type("U", (), {"path": "/api/v1/bots"})()
+        method = "GET"
+        scope = {}
+
+    async def boom(_request):
+        raise RuntimeError("the route failed")
+
+    with pytest.raises(RuntimeError, match="the route failed"):
+        asyncio.run(taps.web_tap(Req(), boom))
+
+
+# ── The taps report shapes, not content ──────────────────────────────────
+
+
+def test_an_error_reports_its_type_and_a_hash_never_its_message(install):
+    _grant("usage")
+    secret = "Insufficient balance 12.5 SOL on wallet 7xKXtg2CW87d97TXJSD"
+    try:
+        raise ValueError(secret)
+    except ValueError as exc:
+        taps.on_error(exc, where="handlers.trading", surface="telegram")
+
+    event = emitter.drain()[0][0]
+    blob = json.dumps(event)
+    assert event["props"]["exc_type"] == "ValueError"
+    assert secret not in blob
+    assert "12.5" not in blob
+    assert len(event["props"]["sig"]) == 12
+    # Frames are repo-relative, so no home directory and no username.
+    for frame in event["props"].get("frames", []):
+        assert not frame.startswith("/")
+
+
+def test_a_callback_verb_drops_the_identifier_after_it(install):
+    """`admin:approve_12345` must report `approve`, never the id."""
+    assert taps._verb_of("approve_12345") == "approve"
+    assert taps._verb_of("view_MyPrivateBotName") == "view"
+    assert taps._verb_of("set_slippage") == "set_slippage"
+
+
+def test_the_user_hash_is_not_the_telegram_id_and_is_install_scoped(install):
+    _grant("usage")
+    first = taps.user_hash(843214321)
+    assert first and "843214321" not in first
+    assert len(first) == 16
+    assert taps.user_hash(843214321) == first
+
+    # A different install secret yields a different hash for the same person.
+    consent._update(install_secret="a-completely-different-secret")
+    assert taps.user_hash(843214321) != first
+
+
+def test_a_private_routine_is_reported_as_custom(install):
+    assert taps.shipped_routine_name("definitely_not_a_shipped_routine") == "custom"
+
+
+def test_the_install_context_carries_no_identity(install):
+    _grant("usage")
+    blob = json.dumps(context.envelope([], 0, "usage"))
+    import getpass
+    import socket
+
+    for identifying in (socket.gethostname(), getpass.getuser(), str(install)):
+        if identifying:
+            assert identifying not in blob
+
+
+# ── Out of process ───────────────────────────────────────────────────────
+
+
+def test_a_process_without_a_flush_job_spools_to_its_own_file(install):
+    """The MCP server has its own interpreter and no job_queue; an in-memory
+    ring there would be silently lost."""
+    _grant("usage")
+    emitter.set_hosted(False)
+    emitter.emit("mcp_tool", tool="manage_bots", ok=True, duration_ms=12)
+
+    assert emitter.buffered() == 0
+    assert outbox.spool_path().exists()
+
+    emitter.set_hosted(True)
+    drained = outbox.drain_spools()
+    assert [e["name"] for e in drained] == ["mcp_tool"]
+    assert not outbox.spool_path().exists()
+
+
+# ── Cost and limits ──────────────────────────────────────────────────────
+
+
+def test_the_rate_limiter_confesses_instead_of_flooding(install):
+    _grant("usage")
+    for _ in range(emitter.RATE_PER_MIN + 40):
+        emitter.emit("error", where="loop", exc_type="ValueError", sig="abc")
+
+    events, dropped = emitter.drain()
+    assert len(events) == emitter.RATE_PER_MIN
+    assert dropped == 40
+
+
+def test_emit_costs_under_50_microseconds_on_the_hot_path(install):
+    _grant("usage")
+    iterations = 2000
+    started = time.perf_counter()
+    for _ in range(iterations):
+        emitter.emit("command", name="portfolio", surface="telegram")
+    per_call = (time.perf_counter() - started) / iterations
+    assert per_call < 50e-6, f"emit() took {per_call * 1e6:.1f}us"
+
+
+def test_emit_is_free_when_off(install):
+    """The gate a trading path actually pays for."""
+    iterations = 2000
+    started = time.perf_counter()
+    for _ in range(iterations):
+        emitter.emit("command", name="portfolio", surface="telegram")
+    per_call = (time.perf_counter() - started) / iterations
+    assert per_call < 50e-6
+
+
+def test_the_ring_cannot_grow_without_bound(install):
+    _grant("usage")
+    for _ in range(emitter.RING_MAX * 2):
+        emitter._buffer.append({"id": "x", "name": "command", "props": {}})
+    assert emitter.buffered() == emitter.RING_MAX
+
+
+# ── The Telegram seam ────────────────────────────────────────────────────
+
+
+class _FakeUpdate:
+    """Just enough of an Update for the tap, which only ever reads."""
+
+    def __init__(self, text: str = "", callback: str = "", user_id: int = 55):
+        self.effective_user = type("U", (), {"id": user_id})()
+        self.message = type("M", (), {"text": text})() if text else None
+        self.callback_query = type("C", (), {"data": callback})() if callback else None
+
+
+def test_the_telegram_tap_reports_the_command_never_the_message(install):
+    _grant("usage")
+    asyncio.run(taps.telegram_tap(_FakeUpdate(text="/trade SOL-USDC buy 12.5"), None))
+
+    events = [e for e in emitter.drain()[0] if e["name"] == "command"]
+    assert len(events) == 1
+    blob = json.dumps(events[0])
+    assert events[0]["props"]["name"] == "trade"
+    assert "SOL-USDC" not in blob and "12.5" not in blob
+
+
+def test_an_unknown_command_does_not_widen_the_value_space(install):
+    _grant("usage")
+    asyncio.run(taps.telegram_tap(_FakeUpdate(text="/some_private_fork_command"), None))
+    events = [e for e in emitter.drain()[0] if e["name"] == "command"]
+    assert events[0]["props"]["name"] == "other"
+
+
+def test_a_callback_reports_module_and_verb_only(install):
+    _grant("usage")
+    asyncio.run(
+        taps.telegram_tap(_FakeUpdate(callback="admin:approve_843214321"), None)
+    )
+    event = emitter.drain()[0][0]
+    assert event["name"] == "action"
+    assert event["props"] == {
+        "module": "admin",
+        "verb": "approve",
+        "surface": "telegram",
+    }
+    assert "843214321" not in json.dumps(event)
+
+
+def test_the_telegram_tap_emits_nothing_before_consent(install):
+    """The acceptance criterion, at the seam rather than at the emitter."""
+    assert consent.state() == consent.UNKNOWN
+    for update in (
+        _FakeUpdate(text="/portfolio"),
+        _FakeUpdate(text="/keys"),
+        _FakeUpdate(callback="bots:deploy_mybot"),
+    ):
+        asyncio.run(taps.telegram_tap(update, None))
+    assert emitter.buffered() == 0
+    assert not outbox.root().exists()
+
+
+def test_the_telegram_tap_never_raises_into_the_handler(install):
+    _grant("usage")
+
+    class Hostile:
+        @property
+        def effective_user(self):
+            raise RuntimeError("nope")
+
+    asyncio.run(taps.telegram_tap(Hostile(), None))  # must not raise

From a4e5f48134c0cd6956dddc71ada71e7e487508f4 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Wed, 12 Aug 2026 00:00:38 +0300
Subject: [PATCH 016/116] Accept an envelope from an install, once and only
 once (FEAT-024)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

FEAT-023 gave every consenting install a batched, anonymous event stream and
nowhere to send it. This is the receiving end: POST /v1/events, GET /health, and
the four tables underneath them.

ingest.py imports condor.telemetry.schema — the *same* module the emitter
sanitises with, not a copy. That is the entire reason the collector lives in
this repo rather than its own. A taxonomy that drifts between emitter and
validator is how this kind of system fails: the client starts sending a
property, the server silently drops it, and nobody notices for three months.

The endpoint is public and unauthenticated, because installs are anonymous by
design and there is no credential to issue without creating the identity we
explicitly do not want. So the pipeline is ordered cheapest-first and every step
assumes the caller is hostile:

- 1 MB body cap, counted as the stream arrives. Content-Length is checked first
  because it is free, but not trusted — a chunked request can understate it.
- Token bucket per source IP before the JSON parser runs, then per install_id
  before any database contact. X-Forwarded-For is ignored unless a proxy is
  declared trusted, since otherwise it is a one-header limit bypass. The
  limiter's key space is capped and evicts LRU: install_id is attacker-chosen,
  and an unbounded bucket-per-id map is a memory exhaustion primitive.
- Unknown schema versions, unknown levels, malformed ids and batches over 500
  events are refused whole. Unknown fields inside app/config are dropped rather
  than stored.
- No payload value is ever formatted into SQL, and no error response echoes any
  part of the request — every refusal is a constant, so this cannot be turned
  into a reflector or used as an oracle.

An unknown event name or an out-of-spec property is dropped and counted, and the
rest of the batch still lands. Rejecting an envelope over one bad event would
let a single client bug erase a day of otherwise good data; the `rejected`
counter is what makes client/server skew visible instead of silent.

install_days is written on the ingest path, from newly inserted rows only, so a
retry after a timeout cannot inflate a metric even though it legitimately
re-sends the batch. It is also what survives the 90-day raw retention.

store.py speaks Postgres and SQLite from one set of statements, differing only
in placeholder style and a jsonb cast. Postgres is what gets deployed; SQLite is
what lets the collector's tests run inside `uv run pytest` with no daemon,
against the same SQL production executes. asyncpg sits behind a new
telemetry-server extra and is imported nowhere else, so a bot that only emits
telemetry never installs a database driver.
---
 pyproject.toml                                |   3 +
 telemetry_server/__init__.py                  |  22 +
 telemetry_server/app.py                       |  90 +++++
 telemetry_server/config.py                    |  49 +++
 telemetry_server/ingest.py                    | 349 ++++++++++++++++
 telemetry_server/migrations/001_init.sql      |  85 ++++
 .../migrations/001_init.sqlite.sql            |  59 +++
 telemetry_server/store.py                     | 379 ++++++++++++++++++
 8 files changed, 1036 insertions(+)
 create mode 100644 telemetry_server/__init__.py
 create mode 100644 telemetry_server/app.py
 create mode 100644 telemetry_server/config.py
 create mode 100644 telemetry_server/ingest.py
 create mode 100644 telemetry_server/migrations/001_init.sql
 create mode 100644 telemetry_server/migrations/001_init.sqlite.sql
 create mode 100644 telemetry_server/store.py

diff --git a/pyproject.toml b/pyproject.toml
index 70d7398c..5c90f957 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -29,6 +29,9 @@ dependencies = [
 
 [project.optional-dependencies]
 dev = ["pytest", "pytest-asyncio", "black", "isort", "pre-commit"]
+# The telemetry collector (FEAT-024, telemetry_server/). Kept out of a normal
+# install: a bot that only *emits* telemetry has no use for a database driver.
+telemetry-server = ["asyncpg"]
 
 [tool.isort]
 profile = "black"
diff --git a/telemetry_server/__init__.py b/telemetry_server/__init__.py
new file mode 100644
index 00000000..0d8e4ace
--- /dev/null
+++ b/telemetry_server/__init__.py
@@ -0,0 +1,22 @@
+"""The receiving end of Condor's usage telemetry (FEAT-024).
+
+``condor/telemetry/`` (FEAT-023) makes every consenting install emit a batched,
+anonymous event stream. This package is what it reports to: a small FastAPI
+service that accepts those envelopes, stores them idempotently, rolls them up,
+and leaves five SQL files behind that answer the questions the exercise exists
+for.
+
+It lives in this repository on purpose. The alternative — a separate collector
+repo — forces the event taxonomy to exist in two places, and a taxonomy that
+drifts between emitter and validator is the classic failure of this kind of
+system: the client starts sending a property, the server silently drops it, and
+nobody notices for three months. :mod:`telemetry_server.ingest` imports
+:mod:`condor.telemetry.schema` **directly**, so drift is not unlikely, it is
+impossible.
+
+Nothing here is installed by default. ``asyncpg`` sits behind the
+``telemetry-server`` extra in ``pyproject.toml`` and is imported lazily, so a
+normal Condor install carries this directory as dead weight and nothing else.
+"""
+
+__all__ = ["__doc__"]
diff --git a/telemetry_server/app.py b/telemetry_server/app.py
new file mode 100644
index 00000000..39fa2a0b
--- /dev/null
+++ b/telemetry_server/app.py
@@ -0,0 +1,90 @@
+"""The collector service: two endpoints and a background rollup.
+
+``create_app()`` mirrors ``condor/web/app.py`` — a factory returning a
+configured :class:`~fastapi.FastAPI`, so the test suite builds an app against a
+throwaway database instead of importing a module-level singleton that has
+already opened a connection to whatever the environment pointed at.
+
+There is deliberately no read endpoint. Nothing here serves data back to an
+install, so the only thing this process will do for an anonymous caller is
+accept an envelope and say how much of it it kept.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.responses import JSONResponse
+
+from telemetry_server import config, ingest, rollup
+from telemetry_server.store import Store, open_store
+
+log = logging.getLogger(__name__)
+
+
+async def _rollup_loop(app: FastAPI) -> None:
+    """Recompute the permanent tables on a fixed interval.
+
+    A plain asyncio task rather than a scheduler dependency: the job is "run
+    this every few hours, never concurrently with itself", which is a loop, and
+    one service with no extra runtime is easier to reason about than one with a
+    scheduler in it.
+    """
+    interval = config.rollup_interval_s()
+    while True:
+        try:
+            await asyncio.sleep(interval)
+            await rollup.run(app.state.store)
+        except asyncio.CancelledError:
+            raise
+        except Exception:
+            log.exception("Telemetry rollup failed; will retry next interval")
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    if getattr(app.state, "store", None) is None:
+        app.state.store = await open_store(config.dsn())
+        app.state.owns_store = True
+    task = asyncio.create_task(_rollup_loop(app))
+    try:
+        yield
+    finally:
+        task.cancel()
+        with contextlib.suppress(asyncio.CancelledError):
+            await task
+        if getattr(app.state, "owns_store", False):
+            await app.state.store.close()
+
+
+def create_app(store: Store | None = None) -> FastAPI:
+    """Build the collector. Pass a ``store`` to drive it against a temp database."""
+    app = FastAPI(
+        title="Condor Telemetry Collector",
+        version="1.0.0",
+        lifespan=lifespan,
+        # The ingest contract is documented in this repository; a public schema
+        # browser on an unauthenticated endpoint is surface with no reader.
+        docs_url=None,
+        redoc_url=None,
+        openapi_url=None,
+    )
+    app.state.store = store
+    app.state.owns_store = False
+    app.include_router(ingest.router)
+
+    @app.get("/health")
+    async def health() -> JSONResponse:
+        """Liveness plus a real database round trip."""
+        try:
+            await app.state.store.ping()
+        except Exception:
+            log.exception("Telemetry collector health check failed")
+            return JSONResponse(status_code=503, content={"status": "degraded"})
+        return JSONResponse(status_code=200, content={"status": "ok"})
+
+    return app
diff --git a/telemetry_server/config.py b/telemetry_server/config.py
new file mode 100644
index 00000000..baa8c212
--- /dev/null
+++ b/telemetry_server/config.py
@@ -0,0 +1,49 @@
+"""Every knob the collector reads from its environment, in one place.
+
+The house pattern (``utils/config.py``) is a module of module-level reads rather
+than env lookups scattered through the code, so that what a deployment can
+change is one file long. These are read per call rather than at import, because
+the test suite sets them with ``monkeypatch.setenv``.
+"""
+
+from __future__ import annotations
+
+import os
+
+DEFAULT_DSN = "sqlite:///telemetry.db"
+DEFAULT_RETENTION_DAYS = 90
+DEFAULT_ROLLUP_INTERVAL_S = 6 * 3600
+
+
+def dsn() -> str:
+    """Where events go. A Postgres URL in production, a SQLite path otherwise."""
+    return os.environ.get("TELEMETRY_DSN", "").strip() or DEFAULT_DSN
+
+
+def trust_proxy() -> bool:
+    """Whether ``X-Forwarded-For`` may be believed.
+
+    Off unless an operator says otherwise, because the header is written by the
+    caller: trusting it on a directly-exposed service hands every client a
+    one-header rate-limit bypass.
+    """
+    return os.environ.get("TELEMETRY_TRUSTED_PROXY", "").strip().lower() in (
+        "1",
+        "true",
+        "yes",
+    )
+
+
+def retention_days() -> int:
+    """How long raw events live. Rollups are permanent regardless."""
+    try:
+        return max(1, int(os.environ.get("TELEMETRY_RETENTION_DAYS", "").strip()))
+    except ValueError:
+        return DEFAULT_RETENTION_DAYS
+
+
+def rollup_interval_s() -> int:
+    try:
+        return max(60, int(os.environ.get("TELEMETRY_ROLLUP_INTERVAL_S", "").strip()))
+    except ValueError:
+        return DEFAULT_ROLLUP_INTERVAL_S
diff --git a/telemetry_server/ingest.py b/telemetry_server/ingest.py
new file mode 100644
index 00000000..46937865
--- /dev/null
+++ b/telemetry_server/ingest.py
@@ -0,0 +1,349 @@
+"""``POST /v1/events`` — the one public, unauthenticated door.
+
+Installs are anonymous by design, so there is no credential to check: anything
+on the internet can POST here. The pipeline below is ordered so that everything
+cheap happens before anything expensive, and so that a hostile body is refused
+before it can cost a parse, a memory allocation, or a database round trip.
+
+1. **Body cap.** 1 MB, enforced while streaming. An oversized body is dropped
+   without ever being fully buffered or parsed.
+2. **Rate limit by source IP.** Token bucket, before the JSON parser runs.
+3. **Parse and validate the envelope.** Unknown ``schema`` versions and more
+   than :data:`MAX_EVENTS` events are refused whole.
+4. **Rate limit by ``install_id``**, now that we know it — still before any
+   database contact.
+5. **Validate each event** against :mod:`condor.telemetry.schema`, the same
+   module the client sanitises with. Offenders are dropped and counted; the
+   rest of the batch is still accepted, because rejecting a whole envelope over
+   one malformed event would let a single client bug erase a day of otherwise
+   good data.
+6. **Persist** in one transaction, with ``ON CONFLICT DO NOTHING``.
+
+Two rules hold everywhere in this module. Nothing from a payload is ever
+formatted into SQL — :mod:`telemetry_server.store` takes parameters only. And
+no error response ever echoes any part of the request: the replies are fixed
+strings, so this endpoint cannot be turned into a reflector or used to confirm
+what the server did with a probe.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+import uuid
+from collections import OrderedDict
+from datetime import datetime, timedelta, timezone
+
+from fastapi import APIRouter, Request
+from fastapi.responses import JSONResponse
+
+from condor.telemetry import schema
+
+log = logging.getLogger(__name__)
+
+router = APIRouter()
+
+KNOWN_SCHEMAS = frozenset({1})
+LEVELS = frozenset({"ping", "usage"})
+
+MAX_BODY_BYTES = 1024 * 1024
+MAX_EVENTS = 500
+MAX_PROPS = 64
+MAX_PROVIDERS = 10
+MAX_COUNT = 1_000_000
+MAX_DROPPED = 10_000_000
+# Client clocks on self-hosted boxes drift and occasionally lie. Anything
+# further out than this is the clock, not the event.
+CLOCK_SLACK = timedelta(hours=48)
+
+RATE_PER_HOUR = 60
+
+
+class RateLimiter:
+    """Token bucket per key, with a bounded key space.
+
+    The bound matters as much as the rate. ``install_id`` is attacker-chosen, so
+    a limiter that kept one bucket per id it has ever seen would be a memory
+    exhaustion primitive wearing a safety hat. Keys are held in an LRU capped at
+    :data:`max_keys`; evicting the least recently used one costs an attacker a
+    fresh bucket, which is exactly what they would have had anyway.
+    """
+
+    def __init__(self, per_hour: int = RATE_PER_HOUR, max_keys: int = 20_000) -> None:
+        self.per_hour = float(per_hour)
+        self.max_keys = max_keys
+        self._buckets: OrderedDict[str, tuple[float, float]] = OrderedDict()
+
+    def allow(self, key: str) -> bool:
+        now = time.monotonic()
+        tokens, last = self._buckets.pop(key, (self.per_hour, now))
+        tokens = min(self.per_hour, tokens + (now - last) * self.per_hour / 3600.0)
+        allowed = tokens >= 1.0
+        self._buckets[key] = (tokens - 1.0 if allowed else tokens, now)
+        while len(self._buckets) > self.max_keys:
+            self._buckets.popitem(last=False)
+        return allowed
+
+    def reset(self) -> None:
+        self._buckets.clear()
+
+
+by_ip = RateLimiter()
+by_install = RateLimiter()
+
+
+class Refused(Exception):
+    """A whole envelope is unusable. Carries a fixed, contentless reason."""
+
+    def __init__(self, status: int, reason: str) -> None:
+        super().__init__(reason)
+        self.status = status
+        self.reason = reason
+
+
+def _refuse(status: int, reason: str) -> JSONResponse:
+    """Every failure reply is a constant. No request data crosses back out."""
+    return JSONResponse(status_code=status, content={"error": reason})
+
+
+async def read_body(request: Request) -> bytes:
+    """Read at most :data:`MAX_BODY_BYTES`, refusing anything larger.
+
+    The declared ``Content-Length`` is checked first because it is free, but it
+    is not trusted: a chunked request can omit or understate it, so the stream
+    is counted as it arrives and abandoned the moment it crosses the cap.
+    """
+    declared = request.headers.get("content-length")
+    if declared is not None:
+        try:
+            if int(declared) > MAX_BODY_BYTES:
+                raise Refused(413, "body_too_large")
+        except ValueError:
+            raise Refused(400, "bad_request") from None
+
+    chunks: list[bytes] = []
+    size = 0
+    async for chunk in request.stream():
+        size += len(chunk)
+        if size > MAX_BODY_BYTES:
+            raise Refused(413, "body_too_large")
+        chunks.append(chunk)
+    return b"".join(chunks)
+
+
+def client_ip(request: Request) -> str:
+    """The peer address, or the forwarded one only where a proxy is trusted.
+
+    ``X-Forwarded-For`` is a client-supplied header. Honouring it by default
+    would hand every caller a free rate-limit bypass, so it is read only when
+    the operator has said there is a proxy in front (``TELEMETRY_TRUSTED_PROXY``).
+    """
+    from telemetry_server.config import trust_proxy
+
+    if trust_proxy():
+        forwarded = request.headers.get("x-forwarded-for", "")
+        first = forwarded.split(",")[0].strip()
+        if first:
+            return first[:64]
+    return request.client.host if request.client else "unknown"
+
+
+def _uuid_or_none(value: object) -> str | None:
+    if not isinstance(value, str) or len(value) > 45:
+        return None
+    try:
+        return str(uuid.UUID(value))
+    except ValueError:
+        return None
+
+
+def _ts_or_none(value: object) -> datetime | None:
+    if not isinstance(value, str) or len(value) > 40:
+        return None
+    try:
+        parsed = datetime.fromisoformat(value.strip().replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=timezone.utc)
+    return parsed.astimezone(timezone.utc)
+
+
+def clamp_ts(ts: datetime, received_at: datetime) -> datetime:
+    """Pull a lying clock back inside the window we are willing to believe."""
+    return max(received_at - CLOCK_SLACK, min(ts, received_at + CLOCK_SLACK))
+
+
+def _flag(value: object) -> bool | None:
+    return value if isinstance(value, bool) else None
+
+
+def _count(value: object) -> int | None:
+    if isinstance(value, bool) or not isinstance(value, int):
+        return None
+    return max(0, min(MAX_COUNT, value))
+
+
+def _install_row(envelope: dict, install_id: str, received_at: datetime) -> dict:
+    """Flatten ``app`` and ``config`` into the columns we keep.
+
+    Only declared keys are read. An unknown field in either sub-object is not
+    stored, not logged, and not reflected — it simply does not exist here.
+    """
+    app = envelope.get("app")
+    app = app if isinstance(app, dict) else {}
+    config = envelope.get("config")
+    config = config if isinstance(config, dict) else {}
+
+    providers = config.get("llm_providers")
+    if isinstance(providers, (list, tuple)):
+        clean = [schema.clean_str(p) for p in list(providers)[:MAX_PROVIDERS]]
+        providers = [p for p in clean if p]
+    else:
+        providers = []
+
+    return {
+        "install_id": install_id,
+        "received_at": received_at,
+        "level": envelope["level"],
+        "version": schema.clean_str(app.get("version")),
+        "branch": schema.clean_str(app.get("branch")),
+        "os": schema.clean_str(app.get("os")),
+        "arch": schema.clean_str(app.get("arch")),
+        "python": schema.clean_str(app.get("python")),
+        "in_docker": _flag(app.get("in_docker")),
+        "has_hb_api": _flag(config.get("has_hb_api")),
+        "has_gateway": _flag(config.get("has_gateway")),
+        "has_web": _flag(config.get("has_web")),
+        "user_count": _count(config.get("user_count")),
+        "server_count": _count(config.get("server_count")),
+        "agent_count": _count(config.get("agent_count")),
+        "llm_providers": providers,
+    }
+
+
+def validate(envelope: object, received_at: datetime) -> tuple[dict, list[dict], int]:
+    """Turn an untrusted body into rows, or raise :class:`Refused`.
+
+    Returns ``(install, events, rejected)``. ``rejected`` counts every offender
+    dropped — a whole event whose name we do not know, and each individual
+    property that fell outside its declared spec. Both are the early warning
+    that a taxonomy change broke something, so they are counted together and
+    reported back rather than swallowed.
+    """
+    if not isinstance(envelope, dict):
+        raise Refused(400, "invalid_envelope")
+    if envelope.get("schema") not in KNOWN_SCHEMAS:
+        raise Refused(400, "unknown_schema")
+
+    install_id = _uuid_or_none(envelope.get("install_id"))
+    if install_id is None:
+        raise Refused(400, "invalid_envelope")
+    if envelope.get("level") not in LEVELS:
+        raise Refused(400, "invalid_envelope")
+
+    raw_events = envelope.get("events")
+    if not isinstance(raw_events, list):
+        raise Refused(400, "invalid_envelope")
+    if len(raw_events) > MAX_EVENTS:
+        raise Refused(413, "too_many_events")
+
+    install = _install_row(envelope, install_id, received_at)
+
+    events: list[dict] = []
+    rejected = 0
+    seen: set[str] = set()
+    for raw in raw_events:
+        if not isinstance(raw, dict):
+            rejected += 1
+            continue
+        event_id = _uuid_or_none(raw.get("id"))
+        ts = _ts_or_none(raw.get("ts"))
+        name = raw.get("name")
+        props = raw.get("props")
+        if props is None:
+            props = {}
+        if (
+            event_id is None
+            or ts is None
+            or not isinstance(name, str)
+            or not schema.is_known(name)
+            or not isinstance(props, dict)
+            or len(props) > MAX_PROPS
+        ):
+            rejected += 1
+            continue
+        if event_id in seen:
+            # A duplicate inside one envelope: the database would swallow it,
+            # but counting it here keeps `accepted` equal to rows written.
+            rejected += 1
+            continue
+        seen.add(event_id)
+
+        clean = schema.sanitize(name, props)
+        if clean is None:
+            rejected += 1
+            continue
+        rejected += len(props) - len(clean)
+
+        events.append(
+            {
+                "id": event_id,
+                "install_id": install_id,
+                "ts": clamp_ts(ts, received_at),
+                "received_at": received_at,
+                "name": name,
+                "props": clean,
+            }
+        )
+
+    return install, events, rejected
+
+
+def _dropped(envelope: dict) -> int:
+    value = envelope.get("dropped")
+    if isinstance(value, bool) or not isinstance(value, int):
+        return 0
+    return max(0, min(MAX_DROPPED, value))
+
+
+@router.post("/v1/events")
+async def ingest(request: Request) -> JSONResponse:
+    try:
+        body = await read_body(request)
+    except Refused as refusal:
+        return _refuse(refusal.status, refusal.reason)
+
+    if not by_ip.allow(client_ip(request)):
+        return _refuse(429, "rate_limited")
+
+    try:
+        envelope = json.loads(body)
+    except ValueError:
+        return _refuse(400, "invalid_json")
+
+    try:
+        install, events, rejected = validate(envelope, _now())
+    except Refused as refusal:
+        return _refuse(refusal.status, refusal.reason)
+
+    if not by_install.allow(install["install_id"]):
+        return _refuse(429, "rate_limited")
+
+    store = request.app.state.store
+    try:
+        stored, duplicates = await store.record(install, events, _dropped(envelope))
+    except Exception:
+        # The reason a write failed is ours to read, never the caller's.
+        log.exception("Telemetry ingest could not persist an envelope")
+        return _refuse(503, "unavailable")
+
+    return JSONResponse(
+        status_code=202,
+        content={"accepted": stored, "rejected": rejected, "duplicates": duplicates},
+    )
+
+
+def _now() -> datetime:
+    return datetime.now(timezone.utc)
diff --git a/telemetry_server/migrations/001_init.sql b/telemetry_server/migrations/001_init.sql
new file mode 100644
index 00000000..6a00d091
--- /dev/null
+++ b/telemetry_server/migrations/001_init.sql
@@ -0,0 +1,85 @@
+-- Collector schema (FEAT-024), Postgres flavour. Idempotent: safe to re-run on
+-- every boot, which is how telemetry_server.app applies it.
+--
+-- `installs` is upserted on every envelope; `events` is append-only and
+-- partitioned by month so the 90-day retention is a DROP TABLE rather than a
+-- mass DELETE; `install_days` is written on the ingest path because it is what
+-- survives raw expiry and every retention question depends on it;
+-- `daily_metrics` is the nightly rollup and is permanent.
+
+CREATE TABLE IF NOT EXISTS installs (
+    install_id     uuid PRIMARY KEY,
+    first_seen     timestamptz NOT NULL,
+    last_seen      timestamptz NOT NULL,
+    level          text        NOT NULL,
+    version        text,
+    branch         text,
+    os             text,
+    arch           text,
+    python         text,
+    in_docker      boolean,
+    -- Capability flags the client actually sends (condor/telemetry/context.py
+    -- `config_shape`). The original design omitted them; the wire has them.
+    has_hb_api     boolean,
+    has_gateway    boolean,
+    has_web        boolean,
+    user_count     integer,
+    server_count   integer,
+    agent_count    integer,
+    llm_providers  text[],
+    dropped_total  bigint NOT NULL DEFAULT 0
+);
+
+CREATE TABLE IF NOT EXISTS events (
+    id          uuid        NOT NULL,
+    install_id  uuid        NOT NULL,
+    -- Both timestamps are kept on purpose. Client clocks on self-hosted boxes
+    -- drift and occasionally lie; ingest clamps `ts` to received_at +/- 48h,
+    -- dashboards count volume by `received_at`, and `ts` is only trusted for
+    -- ordering inside one install's session.
+    ts          timestamptz NOT NULL,
+    received_at timestamptz NOT NULL DEFAULT now(),
+    name        text        NOT NULL,
+    props       jsonb       NOT NULL DEFAULT '{}',
+    PRIMARY KEY (id, ts)
+) PARTITION BY RANGE (ts);
+
+CREATE INDEX IF NOT EXISTS events_name_ts ON events (name, ts);
+CREATE INDEX IF NOT EXISTS events_install_ts ON events (install_id, ts);
+
+CREATE TABLE IF NOT EXISTS install_days (
+    install_id uuid   NOT NULL,
+    day        date   NOT NULL,
+    events     bigint NOT NULL DEFAULT 0,
+    errors     bigint NOT NULL DEFAULT 0,
+    version    text,
+    PRIMARY KEY (install_id, day)
+);
+
+CREATE TABLE IF NOT EXISTS daily_metrics (
+    day    date    NOT NULL,
+    metric text    NOT NULL,
+    dim    text    NOT NULL DEFAULT '',
+    value  numeric NOT NULL,
+    PRIMARY KEY (day, metric, dim)
+);
+
+-- A partitioned table with no partition rejects every insert, so seed this
+-- month and next. telemetry_server.rollup keeps running a month ahead and drops
+-- what has aged out.
+DO $$
+DECLARE
+    start_month date := date_trunc('month', now())::date;
+    bound       date;
+BEGIN
+    FOR i IN 0..1 LOOP
+        bound := (start_month + (i || ' month')::interval)::date;
+        EXECUTE format(
+            'CREATE TABLE IF NOT EXISTS %I PARTITION OF events '
+            'FOR VALUES FROM (%L) TO (%L)',
+            'events_' || to_char(bound, 'YYYY_MM'),
+            bound,
+            (bound + interval '1 month')::date
+        );
+    END LOOP;
+END $$;
diff --git a/telemetry_server/migrations/001_init.sqlite.sql b/telemetry_server/migrations/001_init.sqlite.sql
new file mode 100644
index 00000000..39d72e42
--- /dev/null
+++ b/telemetry_server/migrations/001_init.sqlite.sql
@@ -0,0 +1,59 @@
+-- The same schema in SQLite, for the test suite and a single-box trial.
+--
+-- Three differences, all forced by the engine and none of them semantic:
+-- there is no partitioning (retention is a DELETE, which is fine at test
+-- volume), no array type (`llm_providers` is a JSON array in TEXT), and no
+-- native date/timestamp type (everything is ISO-8601 UTC text, which sorts and
+-- compares correctly). Column names, keys and conflict targets are identical to
+-- 001_init.sql so telemetry_server.store can share one set of statements.
+
+CREATE TABLE IF NOT EXISTS installs (
+    install_id     TEXT PRIMARY KEY,
+    first_seen     TEXT    NOT NULL,
+    last_seen      TEXT    NOT NULL,
+    level          TEXT    NOT NULL,
+    version        TEXT,
+    branch         TEXT,
+    os             TEXT,
+    arch           TEXT,
+    python         TEXT,
+    in_docker      INTEGER,
+    has_hb_api     INTEGER,
+    has_gateway    INTEGER,
+    has_web        INTEGER,
+    user_count     INTEGER,
+    server_count   INTEGER,
+    agent_count    INTEGER,
+    llm_providers  TEXT,
+    dropped_total  INTEGER NOT NULL DEFAULT 0
+);
+
+CREATE TABLE IF NOT EXISTS events (
+    id          TEXT NOT NULL,
+    install_id  TEXT NOT NULL,
+    ts          TEXT NOT NULL,
+    received_at TEXT NOT NULL,
+    name        TEXT NOT NULL,
+    props       TEXT NOT NULL DEFAULT '{}',
+    PRIMARY KEY (id, ts)
+);
+
+CREATE INDEX IF NOT EXISTS events_name_ts ON events (name, ts);
+CREATE INDEX IF NOT EXISTS events_install_ts ON events (install_id, ts);
+
+CREATE TABLE IF NOT EXISTS install_days (
+    install_id TEXT    NOT NULL,
+    day        TEXT    NOT NULL,
+    events     INTEGER NOT NULL DEFAULT 0,
+    errors     INTEGER NOT NULL DEFAULT 0,
+    version    TEXT,
+    PRIMARY KEY (install_id, day)
+);
+
+CREATE TABLE IF NOT EXISTS daily_metrics (
+    day    TEXT NOT NULL,
+    metric TEXT NOT NULL,
+    dim    TEXT NOT NULL DEFAULT '',
+    value  REAL NOT NULL,
+    PRIMARY KEY (day, metric, dim)
+);
diff --git a/telemetry_server/store.py b/telemetry_server/store.py
new file mode 100644
index 00000000..5efd8b2c
--- /dev/null
+++ b/telemetry_server/store.py
@@ -0,0 +1,379 @@
+"""Persistence for the collector — one interface, two backends.
+
+Production is Postgres (FEAT-024 chose it: known stack, ``ON CONFLICT`` gives
+idempotency in one line, monthly partitions make retention a ``DROP TABLE``).
+But a collector whose tests need a database daemon is a collector whose tests do
+not run, so the same interface also speaks SQLite, which is what the suite in
+``tests/test_telemetry_server.py`` drives. The two backends share their SQL:
+every statement is written once with ``$n`` placeholders and a ``{jsonb}`` cast
+hole, and each backend adapts only those two things. Sharing the statements is
+the point — a second copy would drift exactly the way a second copy of the event
+taxonomy would.
+
+Everything an envelope contributes is parameterised. No value from a payload is
+ever formatted into a statement; the only string interpolation in this file is
+the partition maintenance in :mod:`telemetry_server.rollup`, which builds names
+from dates it computed itself.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sqlite3
+import threading
+from datetime import date, datetime, timezone
+from pathlib import Path
+
+MIGRATIONS = Path(__file__).parent / "migrations"
+
+_PLACEHOLDER = re.compile(r"\$(\d+)")
+
+
+# ── The shared statements ────────────────────────────────────────────────
+# `$2` appears twice in the install upsert (first_seen and last_seen start
+# equal); the SQLite adapter re-orders arguments by order of appearance, so a
+# repeated placeholder is safe in both dialects.
+
+UPSERT_INSTALL = """
+INSERT INTO installs (
+    install_id, first_seen, last_seen, level, version, branch,
+    os, arch, python, in_docker, has_hb_api, has_gateway, has_web,
+    user_count, server_count, agent_count, llm_providers, dropped_total)
+VALUES ($1, $2, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12,
+        $13, $14, $15, $16, $17)
+ON CONFLICT (install_id) DO UPDATE SET
+    last_seen     = excluded.last_seen,
+    level         = excluded.level,
+    version       = excluded.version,
+    branch        = excluded.branch,
+    os            = excluded.os,
+    arch          = excluded.arch,
+    python        = excluded.python,
+    in_docker     = excluded.in_docker,
+    has_hb_api    = excluded.has_hb_api,
+    has_gateway   = excluded.has_gateway,
+    has_web       = excluded.has_web,
+    user_count    = excluded.user_count,
+    server_count  = excluded.server_count,
+    agent_count   = excluded.agent_count,
+    llm_providers = excluded.llm_providers,
+    dropped_total = installs.dropped_total + excluded.dropped_total
+"""
+# `first_seen` is deliberately absent from the DO UPDATE list: first contact is
+# a fact about the past and a later envelope has no business moving it.
+
+INSERT_EVENT = """
+INSERT INTO events (id, install_id, ts, received_at, name, props)
+VALUES ($1, $2, $3, $4, $5, $6{jsonb})
+ON CONFLICT DO NOTHING
+"""
+
+UPSERT_INSTALL_DAY = """
+INSERT INTO install_days (install_id, day, events, errors, version)
+VALUES ($1, $2, $3, $4, $5)
+ON CONFLICT (install_id, day) DO UPDATE SET
+    events  = install_days.events + excluded.events,
+    errors  = install_days.errors + excluded.errors,
+    version = excluded.version
+"""
+
+UPSERT_METRIC = """
+INSERT INTO daily_metrics (day, metric, dim, value)
+VALUES ($1, $2, $3, $4)
+ON CONFLICT (day, metric, dim) DO UPDATE SET value = excluded.value
+"""
+
+
+def _to_qmark(sql: str, args: tuple) -> tuple[str, list]:
+    """Rewrite ``$n`` placeholders as ``?`` and re-order args to match.
+
+    Re-ordering by order of appearance is what makes a repeated ``$n`` legal in
+    the shared statements above.
+    """
+    ordered: list = []
+
+    def swap(match: re.Match) -> str:
+        ordered.append(args[int(match.group(1)) - 1])
+        return "?"
+
+    return _PLACEHOLDER.sub(swap, sql), ordered
+
+
+class Store:
+    """What ingest and rollup are allowed to ask of a database.
+
+    Two SQL fragments differ between the dialects and cannot be parameterised —
+    casting a timestamp to a day, and reading one key out of a JSON column.
+    Subclasses expose them as :attr:`DAY` / :meth:`json_get` and
+    :mod:`telemetry_server.rollup` formats them into its aggregates. Every value
+    that reaches those aggregates is still a bound parameter; what is
+    interpolated is a constant chosen in this file and a key name chosen in
+    ``rollup.py``, never anything an envelope carried.
+    """
+
+    #: SQL expression turning ``events.received_at`` into a day.
+    DAY = "received_at::date"
+
+    def json_get(self, column: str, key: str) -> str:
+        """SQL reading one top-level key of a JSON column as text."""
+        return f"{column}->>'{key}'"
+
+    def json_num(self, column: str, key: str) -> str:
+        """SQL reading one top-level key of a JSON column as a number."""
+        return f"({column}->>'{key}')::numeric"
+
+    async def migrate(self) -> None:
+        raise NotImplementedError
+
+    async def ping(self) -> bool:
+        raise NotImplementedError
+
+    async def close(self) -> None:
+        raise NotImplementedError
+
+    async def record(
+        self, install: dict, events: list[dict], dropped: int
+    ) -> tuple[int, int]:
+        """Persist one validated envelope in a single transaction.
+
+        Returns ``(stored, duplicates)``. ``install_days`` is incremented from
+        *newly inserted* rows only, so the client's retry-after-timeout path
+        cannot inflate a metric even though it legitimately re-sends the batch.
+        """
+        raise NotImplementedError
+
+    async def fetch(self, sql: str, *args) -> list[tuple]:
+        raise NotImplementedError
+
+    async def execute(self, sql: str, *args) -> None:
+        raise NotImplementedError
+
+    async def put_metric(self, day: date, metric: str, dim: str, value: float) -> None:
+        await self.execute(UPSERT_METRIC, day, metric, dim, float(value))
+
+
+def _day_buckets(events: list[dict]) -> dict:
+    """Group inserted events into ``(day) -> (count, errors)``."""
+    buckets: dict[date, list[int]] = {}
+    for event in events:
+        day = event["ts"].astimezone(timezone.utc).date()
+        slot = buckets.setdefault(day, [0, 0])
+        slot[0] += 1
+        if event["name"] in ("error", "upstream_error"):
+            slot[1] += 1
+    return buckets
+
+
+class SqliteStore(Store):
+    """The test and small-deployment backend.
+
+    ``sqlite3`` is synchronous, so every call holds a :class:`threading.Lock`
+    for the microseconds it takes — a thread lock rather than an asyncio one
+    precisely because there is no ``await`` inside the critical section, and
+    because an :class:`asyncio.Lock` binds itself to the first event loop that
+    touches it, which a store built in one loop and served from another would
+    trip over immediately.
+    """
+
+    DAY = "substr(received_at, 1, 10)"
+
+    def json_get(self, column: str, key: str) -> str:
+        return f"json_extract({column}, '$.{key}')"
+
+    def json_num(self, column: str, key: str) -> str:
+        # json_extract already yields SQLite's own numeric affinity for a JSON
+        # number, so unlike Postgres there is nothing to cast.
+        return f"json_extract({column}, '$.{key}')"
+
+    def __init__(self, path: str) -> None:
+        self._path = path
+        self._lock = threading.Lock()
+        self._conn = sqlite3.connect(path, check_same_thread=False)
+        self._conn.execute("PRAGMA journal_mode=WAL")
+        self._conn.execute("PRAGMA foreign_keys=ON")
+
+    def _run(self, sql: str, args: tuple) -> sqlite3.Cursor:
+        # Only the shared INSERT carries the cast hole; leave every other
+        # statement's text alone so a stray brace in a rollup aggregate can
+        # never be mistaken for a format field.
+        if "{jsonb}" in sql:
+            sql = sql.format(jsonb="")
+        statement, ordered = _to_qmark(sql, _as_text_dates(args))
+        return self._conn.execute(statement, ordered)
+
+    async def migrate(self) -> None:
+        with self._lock:
+            self._conn.executescript(
+                (MIGRATIONS / "001_init.sqlite.sql").read_text(encoding="utf-8")
+            )
+            self._conn.commit()
+
+    async def ping(self) -> bool:
+        with self._lock:
+            self._conn.execute("SELECT 1").fetchone()
+        return True
+
+    async def close(self) -> None:
+        with self._lock:
+            self._conn.close()
+
+    async def record(
+        self, install: dict, events: list[dict], dropped: int
+    ) -> tuple[int, int]:
+        with self._lock:
+            try:
+                self._run(UPSERT_INSTALL, _install_args(install, dropped, json.dumps))
+                inserted: list[dict] = []
+                for event in events:
+                    cursor = self._run(
+                        INSERT_EVENT, _event_args(event, str, json.dumps)
+                    )
+                    if cursor.rowcount:
+                        inserted.append(event)
+                for day, (count, errors) in _day_buckets(inserted).items():
+                    self._run(
+                        UPSERT_INSTALL_DAY,
+                        (
+                            install["install_id"],
+                            day.isoformat(),
+                            count,
+                            errors,
+                            install["version"],
+                        ),
+                    )
+                self._conn.commit()
+            except Exception:
+                self._conn.rollback()
+                raise
+        return len(inserted), len(events) - len(inserted)
+
+    async def fetch(self, sql: str, *args) -> list[tuple]:
+        with self._lock:
+            return list(self._run(sql, args).fetchall())
+
+    async def execute(self, sql: str, *args) -> None:
+        with self._lock:
+            self._run(sql, args)
+            self._conn.commit()
+
+
+def _as_text_dates(args: tuple) -> tuple:
+    """SQLite has no date or timestamp type, and its implicit datetime adapter is
+    deprecated. Dates and timestamps go in as ISO-8601 text, matching the DDL and
+    sorting correctly."""
+    return tuple(a.isoformat() if isinstance(a, (date, datetime)) else a for a in args)
+
+
+class PostgresStore(Store):
+    """The production backend. ``asyncpg`` is imported here and nowhere else."""
+
+    def __init__(self, dsn: str) -> None:
+        self._dsn = dsn
+        self._pool = None
+
+    async def connect(self) -> None:
+        import asyncpg  # noqa: PLC0415 - behind the telemetry-server extra
+
+        self._pool = await asyncpg.create_pool(self._dsn, min_size=1, max_size=8)
+
+    async def migrate(self) -> None:
+        sql = (MIGRATIONS / "001_init.sql").read_text(encoding="utf-8")
+        async with self._pool.acquire() as conn:
+            await conn.execute(sql)
+
+    async def ping(self) -> bool:
+        async with self._pool.acquire() as conn:
+            await conn.fetchval("SELECT 1")
+        return True
+
+    async def close(self) -> None:
+        if self._pool is not None:
+            await self._pool.close()
+
+    async def record(
+        self, install: dict, events: list[dict], dropped: int
+    ) -> tuple[int, int]:
+        import uuid as _uuid
+
+        statement = INSERT_EVENT.format(jsonb="::jsonb")
+        async with self._pool.acquire() as conn:
+            async with conn.transaction():
+                await conn.execute(
+                    UPSERT_INSTALL, *_install_args(install, dropped, list)
+                )
+                inserted = []
+                for event in events:
+                    status = await conn.execute(
+                        statement, *_event_args(event, _uuid.UUID, json.dumps)
+                    )
+                    # asyncpg returns "INSERT 0 1", or "INSERT 0 0" when the
+                    # ON CONFLICT swallowed a retry.
+                    if status.rsplit(" ", 1)[-1] != "0":
+                        inserted.append(event)
+                for day, (count, errors) in _day_buckets(inserted).items():
+                    await conn.execute(
+                        UPSERT_INSTALL_DAY,
+                        _uuid.UUID(install["install_id"]),
+                        day,
+                        count,
+                        errors,
+                        install["version"],
+                    )
+        return len(inserted), len(events) - len(inserted)
+
+    async def fetch(self, sql: str, *args) -> list[tuple]:
+        async with self._pool.acquire() as conn:
+            return [tuple(r) for r in await conn.fetch(sql, *args)]
+
+    async def execute(self, sql: str, *args) -> None:
+        async with self._pool.acquire() as conn:
+            await conn.execute(sql, *args)
+
+
+def _install_args(install: dict, dropped: int, providers) -> tuple:
+    return (
+        install["install_id"],
+        install["received_at"],
+        install["level"],
+        install["version"],
+        install["branch"],
+        install["os"],
+        install["arch"],
+        install["python"],
+        install["in_docker"],
+        install["has_hb_api"],
+        install["has_gateway"],
+        install["has_web"],
+        install["user_count"],
+        install["server_count"],
+        install["agent_count"],
+        providers(install["llm_providers"]),
+        dropped,
+    )
+
+
+def _event_args(event: dict, ident, dump) -> tuple:
+    return (
+        ident(event["id"]),
+        ident(event["install_id"]),
+        event["ts"],
+        event["received_at"],
+        event["name"],
+        dump(event["props"]),
+    )
+
+
+async def open_store(dsn: str) -> Store:
+    """Build the backend the DSN asks for, migrated and ready.
+
+    Anything that is not a Postgres URL is a SQLite path, which is how the tests
+    and a single-box trial run get a collector without installing a daemon.
+    """
+    if dsn.startswith(("postgres://", "postgresql://")):
+        store: Store = PostgresStore(dsn)
+        await store.connect()
+    else:
+        store = SqliteStore(dsn.removeprefix("sqlite:///").removeprefix("sqlite://"))
+    await store.migrate()
+    return store

From b3550976d3eb96a7c1f10d9d828cbabe11fb26c9 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Wed, 12 Aug 2026 00:00:51 +0300
Subject: [PATCH 017/116] Answer the five questions from tables that outlive
 the raw events (FEAT-024)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Retention and DAU computed over raw events mean a full scan per dashboard panel,
and raw events expire at 90 days anyway. So every question is answered from
daily_metrics, which the rollup writes and which is never deleted. This is the
one piece of "premature" structure worth paying for from day one: backfilling a
rollup after dropping the raw data it came from is impossible.

The aggregation is split deliberately. SQL does the grouping — cheap, indexed,
and identical in both dialects. Python does the date arithmetic and the cohort
matching, which is exactly where Postgres and SQLite diverge most. The result is
one rollup that runs unchanged against either, so the numbers the tests check
are the numbers production computes rather than a parallel implementation.

Cohorts come from MIN(day) in install_days rather than installs.first_seen, so
retention keeps working for an install whose row was upserted long after its
first event.

dropped_total and dropped_rate are charted next to volume on purpose. The
client's emitter clips a crash loop to 60 events/min and confesses the count in
the envelope; without surfacing it, client-side rate limiting would masquerade
as "things got quieter" during precisely the incident we most want to see.

queries/ is the real deliverable — five plain-ANSI files, each runnable
standalone against Postgres or the SQLite the tests seed, each readable without
Grafana. Building a UI for five questions is a product; five panels over SQL is
an afternoon.

No query groups by user_hash. It is salted per install, so it counts distinct
users inside one install but is meaningless across them, and grouping by it
globally would invent the cross-install identity the client deliberately refused
to provide.

Partition maintenance runs a month ahead and drops what has aged out, which is
an instant DROP TABLE rather than a mass DELETE. It is the one Postgres-only
part; SQLite falls back to a DELETE, which is the right answer at the volume
SQLite is used for. The table names it builds come from dates it computed
itself — nothing from a payload reaches a formatted statement.
---
 telemetry_server/queries/adoption.sql        |  19 ++
 telemetry_server/queries/agent_economics.sql |  27 ++
 telemetry_server/queries/feature_usage.sql   |  25 ++
 telemetry_server/queries/reliability.sql     |  30 ++
 telemetry_server/queries/retention.sql       |  21 ++
 telemetry_server/rollup.py                   | 339 +++++++++++++++++++
 6 files changed, 461 insertions(+)
 create mode 100644 telemetry_server/queries/adoption.sql
 create mode 100644 telemetry_server/queries/agent_economics.sql
 create mode 100644 telemetry_server/queries/feature_usage.sql
 create mode 100644 telemetry_server/queries/reliability.sql
 create mode 100644 telemetry_server/queries/retention.sql
 create mode 100644 telemetry_server/rollup.py

diff --git a/telemetry_server/queries/adoption.sql b/telemetry_server/queries/adoption.sql
new file mode 100644
index 00000000..d1fa5227
--- /dev/null
+++ b/telemetry_server/queries/adoption.sql
@@ -0,0 +1,19 @@
+-- Q1: How many installs are alive, on what, and how fast do upgrades spread?
+--
+-- Reads `daily_metrics` only, so it stays correct after raw events expire and
+-- costs a few thousand rows rather than a full scan. Every query in this
+-- directory is plain ANSI: it runs against the collector's Postgres and against
+-- the SQLite the test suite seeds, and it is readable without Grafana.
+
+SELECT day, metric, dim, value
+FROM daily_metrics
+WHERE metric IN ('dau', 'wau', 'mau')
+ORDER BY day, metric;
+
+-- Version and OS mix, snapshotted once per rollup. The series of snapshots is
+-- what answers "how long does an upgrade take to propagate" — a version's share
+-- decaying across consecutive days is the propagation curve.
+SELECT day, metric, dim AS value_of, value
+FROM daily_metrics
+WHERE metric IN ('version_share', 'os_share', 'provider_share')
+ORDER BY day, metric, value DESC;
diff --git a/telemetry_server/queries/agent_economics.sql b/telemetry_server/queries/agent_economics.sql
new file mode 100644
index 00000000..dbea2432
--- /dev/null
+++ b/telemetry_server/queries/agent_economics.sql
@@ -0,0 +1,27 @@
+-- Q5: How are agents actually used, and what does a turn cost?
+
+SELECT day, metric, dim AS value_of, value
+FROM daily_metrics
+WHERE metric IN ('agent_provider', 'model_rank', 'agent_kind')
+ORDER BY metric, value DESC;
+
+-- Outcome mix. A rising `aborted` share is a usability signal; a rising `error`
+-- share is a reliability one.
+SELECT dim AS outcome, value AS turns
+FROM daily_metrics
+WHERE metric = 'agent_outcome'
+ORDER BY value DESC;
+
+-- What a turn costs, and what a routine costs.
+SELECT day, metric, value
+FROM daily_metrics
+WHERE metric IN ('agent_tool_calls_avg', 'agent_duration_ms_avg',
+                 'routine_duration_ms_avg')
+ORDER BY day, metric;
+
+-- Dry run versus live, and how often a confirmation is actually granted. A deny
+-- or timeout rate that climbs means the agent is asking for the wrong things.
+SELECT metric, dim AS value_of, value
+FROM daily_metrics
+WHERE metric IN ('strategy_mode', 'confirmation_decision')
+ORDER BY metric, value DESC;
diff --git a/telemetry_server/queries/feature_usage.sql b/telemetry_server/queries/feature_usage.sql
new file mode 100644
index 00000000..48b99c47
--- /dev/null
+++ b/telemetry_server/queries/feature_usage.sql
@@ -0,0 +1,25 @@
+-- Q3: What is actually used, and what are we maintaining for nobody?
+--
+-- Note what is absent: nothing groups by `user_hash`. It is salted per install
+-- (FEAT-023), so it can be counted inside one install but is meaningless
+-- across installs, and a query that grouped by it globally would be inventing
+-- a cross-install identity the client deliberately refused to provide.
+
+SELECT day, dim AS event_name, value AS events
+FROM daily_metrics
+WHERE metric = 'event_rank'
+ORDER BY day, value DESC;
+
+-- The key dimension behind each surface: which commands, which modules, which
+-- routines, which connectors.
+SELECT day, metric, dim AS name, value AS uses
+FROM daily_metrics
+WHERE metric IN ('command_rank', 'action_rank', 'routine_rank', 'trade_rank')
+ORDER BY metric, value DESC;
+
+-- The activation funnel. `feature_first_use` fires once per install, ever, so
+-- this counts installs that ever reached a feature, not how often they use it.
+SELECT dim AS feature, value AS installs_activated
+FROM daily_metrics
+WHERE metric = 'activation'
+ORDER BY value DESC;
diff --git a/telemetry_server/queries/reliability.sql b/telemetry_server/queries/reliability.sql
new file mode 100644
index 00000000..b263780d
--- /dev/null
+++ b/telemetry_server/queries/reliability.sql
@@ -0,0 +1,30 @@
+-- Q4: What is broken out there?
+--
+-- `error_rate` is errors per event per install-day, so a single install in a
+-- crash loop shows up as a bad day rather than drowning the fleet average.
+
+SELECT day, value AS errors_per_event
+FROM daily_metrics
+WHERE metric = 'error_rate'
+ORDER BY day;
+
+-- Failure groups, keyed by exception type and the hash of the message. The
+-- message itself is never transmitted (FEAT-023) — grouping works off the hash.
+SELECT dim AS exc_type_and_sig, value AS occurrences
+FROM daily_metrics
+WHERE metric = 'error_group'
+ORDER BY value DESC;
+
+-- Which upstream is failing: the Hummingbot API, Gateway, an LLM, or Telegram.
+SELECT dim AS service, value AS failures
+FROM daily_metrics
+WHERE metric = 'upstream_error_rank'
+ORDER BY value DESC;
+
+-- Client-side rate limiting must never look like a quiet week. `dropped` is the
+-- emitter's own confession, and charting it next to volume is what keeps a
+-- taxonomy change or an error flood visible instead of silent.
+SELECT day, metric, value
+FROM daily_metrics
+WHERE metric IN ('dropped_total', 'dropped_rate')
+ORDER BY day;
diff --git a/telemetry_server/queries/retention.sql b/telemetry_server/queries/retention.sql
new file mode 100644
index 00000000..f1dee5bb
--- /dev/null
+++ b/telemetry_server/queries/retention.sql
@@ -0,0 +1,21 @@
+-- Q2: Do people stay? D1 / D7 / D30 by first-seen cohort.
+--
+-- `day` here is the cohort's first-seen day, not the day the metric describes.
+-- Cohorts are derived from `install_days`, which is written on the ingest path
+-- and never expires, so retention survives the 90-day raw retention window.
+
+SELECT
+    cohort.day                                   AS cohort_day,
+    cohort.value                                 AS installs,
+    d1.value                                     AS retained_d1,
+    d7.value                                     AS retained_d7,
+    d30.value                                    AS retained_d30
+FROM daily_metrics AS cohort
+LEFT JOIN daily_metrics AS d1
+       ON d1.day = cohort.day AND d1.metric = 'retention_d1'
+LEFT JOIN daily_metrics AS d7
+       ON d7.day = cohort.day AND d7.metric = 'retention_d7'
+LEFT JOIN daily_metrics AS d30
+       ON d30.day = cohort.day AND d30.metric = 'retention_d30'
+WHERE cohort.metric = 'cohort_size'
+ORDER BY cohort.day;
diff --git a/telemetry_server/rollup.py b/telemetry_server/rollup.py
new file mode 100644
index 00000000..26dcb3f5
--- /dev/null
+++ b/telemetry_server/rollup.py
@@ -0,0 +1,339 @@
+"""The nightly job: small permanent tables, and partition housekeeping.
+
+Retention and DAU computed over raw events mean a full scan per dashboard
+panel, and raw events expire at :func:`telemetry_server.config.retention_days`
+anyway. So every question is answered from ``daily_metrics``, which this module
+writes and which is never deleted. Backfilling a rollup after dropping the raw
+data it came from is impossible, which is why this exists from day one rather
+than "later".
+
+The aggregation is deliberately split: SQL does the grouping (cheap, indexed,
+and identical in both dialects), Python does the date arithmetic and the
+cohort matching. Date arithmetic is where the two dialects diverge most, and at
+a few hundred installs the rows involved fit in a dict comfortably. The result
+is one rollup that runs unchanged against Postgres and SQLite, so the numbers
+the tests check are the numbers production computes.
+
+Partition maintenance is the one Postgres-only part, and it is a no-op
+elsewhere. The table names it builds come from dates this module computed; no
+payload value ever reaches a formatted statement.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from collections import defaultdict
+from datetime import date, datetime, timedelta, timezone
+
+from telemetry_server import config
+from telemetry_server.store import PostgresStore, Store
+
+log = logging.getLogger(__name__)
+
+TOP_N = 25
+
+
+def _as_date(value: object) -> date | None:
+    if isinstance(value, datetime):
+        return value.date()
+    if isinstance(value, date):
+        return value
+    if isinstance(value, str):
+        try:
+            return date.fromisoformat(value[:10])
+        except ValueError:
+            return None
+    return None
+
+
+async def run(store: Store, today: date | None = None) -> int:
+    """Recompute every metric. Returns how many rows were written."""
+    today = today or datetime.now(timezone.utc).date()
+    written = 0
+    written += await _activity(store)
+    written += await _retention(store)
+    written += await _shares(store, today)
+    written += await _ranks(store)
+    written += await _reliability(store, today)
+    written += await _agents(store, today)
+    await maintain_partitions(store, today)
+    return written
+
+
+async def _activity(store: Store) -> int:
+    """DAU from ``install_days``; WAU and MAU by rolling the same rows."""
+    rows = await store.fetch("SELECT install_id, day FROM install_days")
+    seen: dict[date, set] = defaultdict(set)
+    for install_id, day in rows:
+        parsed = _as_date(day)
+        if parsed is not None:
+            seen[parsed].add(install_id)
+    if not seen:
+        return 0
+
+    written = 0
+    for day in sorted(seen):
+        for metric, window in (("dau", 1), ("wau", 7), ("mau", 30)):
+            active: set = set()
+            for offset in range(window):
+                active |= seen.get(day - timedelta(days=offset), set())
+            await store.put_metric(day, metric, "", len(active))
+            written += 1
+    return written
+
+
+async def _retention(store: Store) -> int:
+    """D1 / D7 / D30 from first-seen cohorts.
+
+    The cohort day is ``MIN(day)`` in ``install_days`` rather than
+    ``installs.first_seen``, so retention keeps working for an install whose
+    row was upserted long after its first event.
+    """
+    rows = await store.fetch("SELECT install_id, day FROM install_days")
+    days: dict[object, set] = defaultdict(set)
+    for install_id, day in rows:
+        parsed = _as_date(day)
+        if parsed is not None:
+            days[install_id].add(parsed)
+    if not days:
+        return 0
+
+    cohorts: dict[date, list] = defaultdict(list)
+    for install_id, active in days.items():
+        cohorts[min(active)].append(install_id)
+
+    written = 0
+    for cohort_day, members in sorted(cohorts.items()):
+        await store.put_metric(cohort_day, "cohort_size", "", len(members))
+        written += 1
+        for horizon in (1, 7, 30):
+            target = cohort_day + timedelta(days=horizon)
+            retained = sum(1 for m in members if target in days[m])
+            await store.put_metric(cohort_day, f"retention_d{horizon}", "", retained)
+            written += 1
+    return written
+
+
+async def _shares(store: Store, today: date) -> int:
+    """Version, OS and LLM-provider mix, as of the run.
+
+    These describe the fleet now rather than a past day, so they are stamped
+    with the run date: a series of daily snapshots is exactly how "how long does
+    an upgrade take to propagate" gets answered.
+    """
+    written = 0
+    for metric, column in (("version_share", "version"), ("os_share", "os")):
+        rows = await store.fetch(
+            f"SELECT {column}, COUNT(*) FROM installs GROUP BY {column}"
+        )
+        for value, count in rows:
+            await store.put_metric(today, metric, str(value or "unknown"), count)
+            written += 1
+
+    counts: dict[str, int] = defaultdict(int)
+    for (raw,) in await store.fetch("SELECT llm_providers FROM installs"):
+        for provider in _providers(raw):
+            counts[provider] += 1
+    for provider, count in counts.items():
+        await store.put_metric(today, "provider_share", provider, count)
+        written += 1
+    return written
+
+
+def _providers(raw: object) -> list[str]:
+    """One column, two shapes: a Postgres ``text[]`` or a SQLite JSON string."""
+    if isinstance(raw, (list, tuple)):
+        return [str(p) for p in raw]
+    if isinstance(raw, str):
+        try:
+            parsed = json.loads(raw)
+        except ValueError:
+            return []
+        return [str(p) for p in parsed] if isinstance(parsed, list) else []
+    return []
+
+
+#: The one property of each event that carries the signal worth ranking.
+RANK_DIMS = {
+    "command": ("command_rank", "name"),
+    "action": ("action_rank", "module"),
+    "routine_run": ("routine_rank", "routine"),
+    "agent_turn": ("model_rank", "model"),
+    "feature_first_use": ("activation", "feature"),
+    "trade": ("trade_rank", "connector"),
+}
+
+
+async def _ranks(store: Store) -> int:
+    """What is actually used: event volume per day, then the key dimensions."""
+    written = 0
+    rows = await store.fetch(
+        f"SELECT {store.DAY} AS d, name, COUNT(*) FROM events GROUP BY d, name"
+    )
+    for day, name, count in rows:
+        parsed = _as_date(day)
+        if parsed is not None:
+            await store.put_metric(parsed, "event_rank", str(name), count)
+            written += 1
+
+    for event_name, (metric, prop) in RANK_DIMS.items():
+        dim = store.json_get("props", prop)
+        rows = await store.fetch(
+            f"SELECT {dim} AS v, COUNT(*) AS n FROM events WHERE name = $1 "
+            f"GROUP BY v ORDER BY n DESC",
+            event_name,
+        )
+        today = datetime.now(timezone.utc).date()
+        for value, count in rows[:TOP_N]:
+            if value is None:
+                continue
+            await store.put_metric(today, metric, str(value), count)
+            written += 1
+    return written
+
+
+async def _reliability(store: Store, today: date) -> int:
+    """Error rate per install-day, the top failure groups, and honest drops."""
+    written = 0
+    rows = await store.fetch(
+        "SELECT day, SUM(events), SUM(errors) FROM install_days GROUP BY day"
+    )
+    for day, events, errors in rows:
+        parsed = _as_date(day)
+        if parsed is None or not events:
+            continue
+        await store.put_metric(parsed, "error_rate", "", (errors or 0) / events)
+        written += 1
+
+    exc = store.json_get("props", "exc_type")
+    sig = store.json_get("props", "sig")
+    groups = await store.fetch(
+        f"SELECT {exc} AS e, {sig} AS s, COUNT(*) AS n FROM events "
+        f"WHERE name = $1 GROUP BY e, s ORDER BY n DESC",
+        "error",
+    )
+    for exc_type, signature, count in groups[:TOP_N]:
+        await store.put_metric(
+            today,
+            "error_group",
+            f"{exc_type or 'unknown'}:{signature or 'unknown'}",
+            count,
+        )
+        written += 1
+
+    service = store.json_get("props", "service")
+    upstream = await store.fetch(
+        f"SELECT {service} AS s, COUNT(*) AS n FROM events WHERE name = $1 GROUP BY s",
+        "upstream_error",
+    )
+    for name, count in upstream:
+        await store.put_metric(
+            today, "upstream_error_rank", str(name or "other"), count
+        )
+        written += 1
+
+    # Client-side rate limiting must never masquerade as "things got quieter",
+    # so the confession the envelope carries is charted next to the volume.
+    (dropped,) = (await store.fetch("SELECT SUM(dropped_total) FROM installs"))[0]
+    (total,) = (await store.fetch("SELECT COUNT(*) FROM events"))[0]
+    await store.put_metric(today, "dropped_total", "", dropped or 0)
+    await store.put_metric(
+        today,
+        "dropped_rate",
+        "",
+        (dropped or 0) / (total + (dropped or 0)) if total else 0,
+    )
+    return written + 2
+
+
+#: ``(event name, property, metric)`` triples whose distribution answers "how
+#: are agents used" — provider and model mix, dry-run versus live, and how
+#: often a confirmation is actually granted.
+AGENT_DIMS = (
+    ("agent_turn", "provider", "agent_provider"),
+    ("agent_turn", "outcome", "agent_outcome"),
+    ("agent_turn", "kind", "agent_kind"),
+    ("strategy_run", "mode", "strategy_mode"),
+    ("confirmation", "decision", "confirmation_decision"),
+)
+
+#: Averages worth a number rather than a distribution.
+AGENT_AVERAGES = (
+    ("agent_turn", "tool_calls", "agent_tool_calls_avg"),
+    ("agent_turn", "duration_ms", "agent_duration_ms_avg"),
+    ("routine_run", "duration_ms", "routine_duration_ms_avg"),
+)
+
+
+async def _agents(store: Store, today: date) -> int:
+    """Agent economics: the mix, the cost per turn, and the trust decisions."""
+    written = 0
+    for event_name, prop, metric in AGENT_DIMS:
+        dim = store.json_get("props", prop)
+        rows = await store.fetch(
+            f"SELECT {dim} AS v, COUNT(*) FROM events WHERE name = $1 GROUP BY v",
+            event_name,
+        )
+        for value, count in rows:
+            await store.put_metric(today, metric, str(value or "unknown"), count)
+            written += 1
+
+    for event_name, prop, metric in AGENT_AVERAGES:
+        column = store.json_num("props", prop)
+        rows = await store.fetch(
+            f"SELECT AVG({column}) FROM events WHERE name = $1", event_name
+        )
+        average = rows[0][0] if rows else None
+        if average is not None:
+            await store.put_metric(today, metric, "", float(average))
+            written += 1
+    return written
+
+
+def _month_start(day: date) -> date:
+    return day.replace(day=1)
+
+
+def _next_month(day: date) -> date:
+    return (day.replace(day=28) + timedelta(days=4)).replace(day=1)
+
+
+async def maintain_partitions(store: Store, today: date) -> list[str]:
+    """Create next month's partition, drop what has aged out.
+
+    Returns the partition names it touched, which is what the tests assert on.
+    Postgres only: SQLite has no partitioning, and at the volume SQLite is used
+    for, ``DELETE`` is the right answer anyway.
+    """
+    if not isinstance(store, PostgresStore):
+        cutoff = today - timedelta(days=config.retention_days())
+        await store.execute("DELETE FROM events WHERE received_at < $1", cutoff)
+        return []
+
+    touched = []
+    current = _month_start(today)
+    for start in (current, _next_month(current)):
+        end = _next_month(start)
+        name = f"events_{start:%Y_%m}"
+        await store.execute(
+            f"CREATE TABLE IF NOT EXISTS {name} PARTITION OF events "
+            f"FOR VALUES FROM ('{start:%Y-%m-%d}') TO ('{end:%Y-%m-%d}')"
+        )
+        touched.append(name)
+
+    cutoff = _month_start(today - timedelta(days=config.retention_days()))
+    existing = await store.fetch(
+        "SELECT c.relname FROM pg_class c "
+        "JOIN pg_inherits i ON i.inhrelid = c.oid "
+        "JOIN pg_class p ON p.oid = i.inhparent WHERE p.relname = 'events'"
+    )
+    for (name,) in existing:
+        try:
+            start = datetime.strptime(name.removeprefix("events_"), "%Y_%m").date()
+        except ValueError:
+            continue
+        if start < cutoff:
+            await store.execute(f"DROP TABLE IF EXISTS {name}")
+            touched.append(f"-{name}")
+    return touched

From 6d47a1933ae09038c0ec377c44f4106afe76fdc2 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Wed, 12 Aug 2026 00:01:06 +0300
Subject: [PATCH 018/116] Make the collector deployable, and prove it holds
 under a hostile POST (FEAT-024)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

compose brings up collector + postgres + grafana. Only the collector is meant to
be reachable, and only through a reverse proxy that terminates TLS — the service
speaks plain HTTP inside the network, matching how the hummingbot/deploy stack is
already run. Postgres and Grafana bind to loopback: Grafana is the one component
here with a login and a session cookie, and it has no business sharing an
exposure with an endpoint whose whole design is that anyone may POST to it. The
passwords have no defaults; compose refuses to start without them. The collector
does not run as root.

Dashboards are not auto-provisioned, only the datasource. The queries are the
deliverable and a panel is a paste.

The tests are the other half of the feature. The first one is the load-bearing
one: it builds its envelope by running the real emitter from condor/telemetry/
and handing the result to context.envelope(), the same path a live install
takes. If FEAT-023 ever changes shape, this suite fails instead of the collector
silently dropping a field in production. That test is also what caught the four
places where the shipped client differs from this feature's written design —
event ids are uuid4().hex rather than dashed, config carries three capability
flags the design's installs table did not have, level is only ever ping|usage,
and mcp_tool exists. The wire contract now follows the client.

Most of the rest is negative, because that is what a public unauthenticated
endpoint needs asserted: an oversized body (with and without a truthful
Content-Length), a batch over the cap, a rate-limited caller and five shapes of
malformed envelope each have to be refused *without the database being reached
at all* — checked with a store that raises if it is touched. A refusal must not
echo a canary planted in the request. A SQL-injection-shaped version string must
land as inert text with the events table still standing. An absurd count must
clamp. The limiter's key space must stay bounded under 5,000 attacker-chosen
ids.

Idempotency gets its own tests from both directions: the same envelope twice
stores one copy and leaves install_days unmoved, and a duplicate id inside a
single envelope is counted once.

Everything runs against SQLite in a tmp_path inside `uv run pytest` — no daemon,
no port, no container, nothing left behind. 1646 pass, up from 1612.
---
 telemetry_server/.env.example           |   4 +
 telemetry_server/Dockerfile             |  42 ++
 telemetry_server/README.md              | 183 ++++++
 telemetry_server/docker-compose.yml     |  75 +++
 telemetry_server/grafana/datasource.yml |  27 +
 tests/test_telemetry_server.py          | 749 ++++++++++++++++++++++++
 6 files changed, 1080 insertions(+)
 create mode 100644 telemetry_server/.env.example
 create mode 100644 telemetry_server/Dockerfile
 create mode 100644 telemetry_server/README.md
 create mode 100644 telemetry_server/docker-compose.yml
 create mode 100644 telemetry_server/grafana/datasource.yml
 create mode 100644 tests/test_telemetry_server.py

diff --git a/telemetry_server/.env.example b/telemetry_server/.env.example
new file mode 100644
index 00000000..44d6900d
--- /dev/null
+++ b/telemetry_server/.env.example
@@ -0,0 +1,4 @@
+# Copy to .env beside docker-compose.yml. Both are required; compose refuses to
+# start without them rather than defaulting to something guessable.
+POSTGRES_PASSWORD=change-me
+GRAFANA_PASSWORD=change-me
diff --git a/telemetry_server/Dockerfile b/telemetry_server/Dockerfile
new file mode 100644
index 00000000..fa16ac1f
--- /dev/null
+++ b/telemetry_server/Dockerfile
@@ -0,0 +1,42 @@
+# The collector image.
+#
+# It builds from the Condor repository root rather than from this directory,
+# because ingest.py imports `condor.telemetry.schema` — the same taxonomy the
+# client sanitises with — and that import is the whole reason the collector
+# lives in this repo (FEAT-024). The cost is an image that carries Condor's
+# dependency set rather than four packages; the benefit is that the emitter and
+# the validator cannot drift apart. That trade was made deliberately.
+#
+# Build from the repo root:  docker build -f telemetry_server/Dockerfile .
+
+FROM python:3.12-slim
+
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    UV_COMPILE_BYTECODE=1 \
+    UV_LINK_MODE=copy
+
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+
+WORKDIR /app
+
+# Dependencies first so a code change does not re-resolve the world.
+COPY pyproject.toml uv.lock* README.md ./
+RUN uv sync --extra telemetry-server --no-dev --no-install-project
+
+COPY condor/ ./condor/
+COPY telemetry_server/ ./telemetry_server/
+COPY utils/ ./utils/
+COPY config_manager.py ./
+
+# Nothing here needs to be root, and an unauthenticated public endpoint is the
+# last process that should be.
+RUN useradd --system --uid 10001 collector && chown -R collector /app
+USER collector
+
+EXPOSE 8000
+
+# Plain HTTP on purpose: TLS terminates at the reverse proxy in front, matching
+# how the hummingbot/deploy stack is already run.
+CMD ["uv", "run", "--no-sync", "uvicorn", "telemetry_server.app:create_app", \
+     "--factory", "--host", "0.0.0.0", "--port", "8000"]
diff --git a/telemetry_server/README.md b/telemetry_server/README.md
new file mode 100644
index 00000000..e935687b
--- /dev/null
+++ b/telemetry_server/README.md
@@ -0,0 +1,183 @@
+# Condor telemetry collector
+
+The receiving end of [`condor/telemetry/`](../condor/telemetry/) (FEAT-023).
+Consenting installs POST batched, anonymous envelopes here; this service
+validates them against the client's own taxonomy, stores them idempotently,
+rolls them up nightly, and leaves five SQL files behind that answer the
+questions the exercise exists for.
+
+It is not installed by default and it is not running anywhere. Standing it up is
+a deliberate act.
+
+## Why it lives in this repository
+
+`ingest.py` imports `condor.telemetry.schema` — the *same module* the emitter
+sanitises with. A separate collector repo would be tidier operationally but
+would force the event taxonomy to exist in two places, and a taxonomy that
+drifts between emitter and validator is the classic failure of this kind of
+system: the client starts sending a property, the server silently drops it, and
+nobody notices for three months. Here, drift is not unlikely — it is impossible,
+and `tests/test_telemetry_server.py` asserts there is no second copy in the repo.
+
+The cost is a container image carrying Condor's dependency set rather than four
+packages. That trade was made knowingly.
+
+## Endpoints
+
+| Method | Path | Behaviour |
+|---|---|---|
+| `POST` | `/v1/events` | Ingest one envelope → `202 {"accepted": n, "rejected": m, "duplicates": d}` |
+| `GET`  | `/health`    | Liveness plus a real database round trip |
+
+There is no endpoint that reads data back to an install, and no API docs are
+served: a schema browser on an unauthenticated endpoint is surface with no
+reader.
+
+## Surviving the open internet
+
+Installs are anonymous by design, so there is no credential to issue without
+creating the identity we explicitly do not want. The endpoint is therefore
+public and unauthenticated, and the pipeline is ordered so that everything cheap
+happens before anything expensive:
+
+1. **Body cap — 1 MB.** Counted as the stream arrives. `Content-Length` is
+   checked first because it is free, but it is not trusted: a chunked request
+   can omit or understate it.
+2. **Rate limit by source IP** — token bucket, 60/h, *before* the JSON parser
+   runs. `X-Forwarded-For` is ignored unless `TELEMETRY_TRUSTED_PROXY` is set,
+   because otherwise the header is a one-line rate-limit bypass. The limiter's
+   key space is capped and evicts LRU, so an attacker-chosen `install_id` cannot
+   become a memory-exhaustion primitive.
+3. **Envelope validation** — unknown `schema` versions, unknown `level`s, a
+   malformed `install_id` and batches over 500 events are refused whole.
+4. **Event validation** against `condor.telemetry.schema`. An unknown event name
+   or an out-of-spec property is **dropped and counted**, and the rest of the
+   batch is still accepted — rejecting a whole envelope over one malformed event
+   would let a single client bug erase a day of otherwise good data. The
+   `rejected` counter is the early warning that a taxonomy change broke
+   something, so chart it.
+5. **Persist** in one transaction, `ON CONFLICT DO NOTHING`.
+
+Two invariants hold throughout. **No payload value is ever formatted into SQL** —
+`store.py` takes bound parameters only, and the only interpolation anywhere is
+partition names built from dates the rollup computed itself. **No error response
+echoes any part of the request** — every refusal is a fixed string, so this
+endpoint cannot be turned into a reflector or used as an oracle.
+
+Unknown fields inside `app` and `config` are not stored, not logged, and not
+reflected. They simply do not exist here.
+
+### What this does *not* defend against
+
+Anyone can POST fabricated envelopes with random `install_id`s and skew the
+adoption numbers. Rate limits raise the cost; the real defence is that the payoff
+is nil and the data steers internal direction, not anything with money attached.
+If it ever becomes a problem the fix is a signed `install_id` issued on first
+contact — deliberately not built now.
+
+## Storage
+
+`migrations/001_init.sql` (Postgres) and `001_init.sqlite.sql` (SQLite) define
+the same four tables:
+
+- **`installs`** — one upserted row per install: identity, platform, capability
+  flags, counts, and a running `dropped_total`.
+- **`events`** — append-only, partitioned by month in Postgres so the 90-day
+  retention is a `DROP TABLE` rather than a mass `DELETE`.
+- **`install_days`** — written on the **ingest path**, from newly inserted rows
+  only. This is what every retention question depends on and what survives raw
+  expiry, which is why it is not deferred to the rollup.
+- **`daily_metrics`** — the nightly rollup. Permanent.
+
+Both `ts` and `received_at` are kept. Client clocks on self-hosted boxes drift
+and occasionally lie, so ingest clamps `ts` to `received_at ± 48 h`; dashboards
+count volume by `received_at` and trust `ts` only for ordering inside one
+install's session.
+
+**SQLite is a real backend, not a mock.** The collector's tests run in Condor's
+own `uv run pytest` with no database daemon, against the same statements
+production executes. Postgres is what you deploy; SQLite is what keeps the tests
+honest and runnable.
+
+## Rollups
+
+`rollup.py` runs on an interval inside the collector process (a plain asyncio
+loop — the job is "every few hours, never concurrently with itself", and one
+service with no extra runtime is easier to reason about than one with a
+scheduler in it). SQL does the grouping; Python does the date arithmetic and
+cohort matching, which is what lets one rollup run unchanged against both
+backends.
+
+It writes `dau`/`wau`/`mau`, `cohort_size` + `retention_d1/d7/d30`,
+`version_share`/`os_share`/`provider_share`, event and command/action/routine
+ranks, `error_rate` and `error_group`, the agent mix and per-turn cost, and
+`dropped_total`/`dropped_rate` — so client-side rate limiting never masquerades
+as "things got quieter". It also creates next month's partition and drops what
+has aged past `TELEMETRY_RETENTION_DAYS`.
+
+Rollups exist from day one rather than "later" because backfilling one after
+dropping the raw data it came from is impossible.
+
+## The five questions
+
+One file each in `queries/`, each runnable standalone against Postgres *or* the
+SQLite the tests seed, and each readable without Grafana:
+
+| File | Question |
+|---|---|
+| `adoption.sql` | How many installs are alive, on what, and how fast do upgrades spread? |
+| `retention.sql` | Do people stay? D1 / D7 / D30 by cohort. |
+| `feature_usage.sql` | What is actually used, and what are we maintaining for nobody? |
+| `reliability.sql` | What is broken out there, and against which upstream? |
+| `agent_economics.sql` | Which providers and models, at what cost per turn, dry-run vs live? |
+
+No query groups by `user_hash`. It is salted per install, so it can be counted
+inside one install but is meaningless across them, and grouping by it globally
+would invent a cross-install identity the client deliberately refused to
+provide. A test asserts this.
+
+## Configuration
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `TELEMETRY_DSN` | `sqlite:///telemetry.db` | Postgres URL in production; anything else is a SQLite path. |
+| `TELEMETRY_TRUSTED_PROXY` | unset | Believe `X-Forwarded-For`. Only set this when a proxy really is in front. |
+| `TELEMETRY_RETENTION_DAYS` | `90` | How long raw events live. Rollups are permanent regardless. |
+| `TELEMETRY_ROLLUP_INTERVAL_S` | `21600` | How often the rollup runs. |
+
+## Running it
+
+```bash
+cp .env.example .env      # set POSTGRES_PASSWORD and GRAFANA_PASSWORD
+docker compose -f telemetry_server/docker-compose.yml up -d
+```
+
+Only `collector` should be reachable from the internet, and only through a
+reverse proxy that terminates TLS — the service speaks plain HTTP inside the
+compose network, matching how the `hummingbot/deploy` stack is already run.
+Postgres and Grafana bind to loopback. **Grafana is the weakest operational link
+here**: it is the only component with a login and a session cookie, so keep it
+behind the same proxy or VPN as the rest, never exposed alongside ingest.
+
+`grafana/datasource.yml` provisions the Postgres datasource. Dashboards are not
+auto-provisioned — the `queries/*.sql` files are the deliverable and a panel is
+a paste.
+
+Once it is up, point an install at it:
+
+```bash
+CONDOR_TELEMETRY_URL=https://telemetry.example.org/v1/events
+```
+
+## Tests
+
+```bash
+uv run pytest tests/test_telemetry_server.py
+```
+
+They run against SQLite in a `tmp_path` and never bind a port, start a
+container, or leave anything behind. The first test is the important one: it
+builds its envelope by running the **real emitter** from `condor/telemetry/` and
+handing the result to `context.envelope()`, so if FEAT-023 ever changes shape,
+this suite fails instead of the collector silently dropping a field in
+production.
diff --git a/telemetry_server/docker-compose.yml b/telemetry_server/docker-compose.yml
new file mode 100644
index 00000000..4f09a9a1
--- /dev/null
+++ b/telemetry_server/docker-compose.yml
@@ -0,0 +1,75 @@
+# The collector stack: ingest, its database, and the dashboards.
+#
+# Only `collector` is meant to be reachable from the internet, and only through
+# a reverse proxy that terminates TLS. Postgres and Grafana are bound to
+# loopback: Grafana is the one component here with a login and a session cookie,
+# and it has no business sharing an exposure with an endpoint whose whole design
+# is that anyone may POST to it.
+#
+#   docker compose -f telemetry_server/docker-compose.yml up -d
+#
+# Set POSTGRES_PASSWORD and GRAFANA_PASSWORD in an .env file beside this one.
+
+services:
+  postgres:
+    image: postgres:16-alpine
+    restart: unless-stopped
+    environment:
+      POSTGRES_DB: telemetry
+      POSTGRES_USER: telemetry
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}
+    volumes:
+      - telemetry-db:/var/lib/postgresql/data
+    ports:
+      - "127.0.0.1:5432:5432"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U telemetry -d telemetry"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  collector:
+    build:
+      context: ..
+      dockerfile: telemetry_server/Dockerfile
+    restart: unless-stopped
+    depends_on:
+      postgres:
+        condition: service_healthy
+    environment:
+      TELEMETRY_DSN: postgresql://telemetry:${POSTGRES_PASSWORD}@postgres:5432/telemetry
+      # X-Forwarded-For is only believed because there really is a proxy in
+      # front here. Leave this unset on a directly-exposed deployment.
+      TELEMETRY_TRUSTED_PROXY: "true"
+      TELEMETRY_RETENTION_DAYS: "90"
+    ports:
+      - "127.0.0.1:8000:8000"
+    healthcheck:
+      test: ["CMD-SHELL", "python -c \"import urllib.request; urllib.request.urlopen('http://localhost:8000/health')\""]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+
+  grafana:
+    image: grafana/grafana:11.3.0
+    restart: unless-stopped
+    depends_on:
+      postgres:
+        condition: service_healthy
+    environment:
+      GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_PASSWORD:?set GRAFANA_PASSWORD}
+      GF_USERS_ALLOW_SIGN_UP: "false"
+      GF_AUTH_ANONYMOUS_ENABLED: "false"
+      TELEMETRY_DB_PASSWORD: ${POSTGRES_PASSWORD}
+    volumes:
+      - grafana-data:/var/lib/grafana
+      - ./grafana:/etc/grafana/provisioning/datasources:ro
+      # The five queries, readable inside the container so a panel can be built
+      # by pasting one in. They are the deliverable; the panels are decoration.
+      - ./queries:/etc/telemetry-queries:ro
+    ports:
+      - "127.0.0.1:3000:3000"
+
+volumes:
+  telemetry-db:
+  grafana-data:
diff --git a/telemetry_server/grafana/datasource.yml b/telemetry_server/grafana/datasource.yml
new file mode 100644
index 00000000..abadd044
--- /dev/null
+++ b/telemetry_server/grafana/datasource.yml
@@ -0,0 +1,27 @@
+# Grafana reads the collector's Postgres directly. There is no API in between:
+# the queries in ../queries/ are plain SQL against the rollup tables, so a panel
+# is a paste rather than an integration.
+#
+# The account is read-only by intent. Grant it explicitly after first boot:
+#   CREATE USER grafana WITH PASSWORD '...';
+#   GRANT CONNECT ON DATABASE telemetry TO grafana;
+#   GRANT USAGE ON SCHEMA public TO grafana;
+#   GRANT SELECT ON ALL TABLES IN SCHEMA public TO grafana;
+
+apiVersion: 1
+
+datasources:
+  - name: Telemetry
+    type: postgres
+    uid: condor-telemetry
+    access: proxy
+    url: postgres:5432
+    database: telemetry
+    user: telemetry
+    secureJsonData:
+      password: ${TELEMETRY_DB_PASSWORD}
+    jsonData:
+      sslmode: disable
+      postgresVersion: 1600
+    isDefault: true
+    editable: false
diff --git a/tests/test_telemetry_server.py b/tests/test_telemetry_server.py
new file mode 100644
index 00000000..9031af93
--- /dev/null
+++ b/tests/test_telemetry_server.py
@@ -0,0 +1,749 @@
+"""The collector (FEAT-024) — the tests that make a public endpoint survivable.
+
+Three things are being proven here, in descending order of how much they matter.
+
+**The wire contract is the client's, not a hand-copy.** The first test builds
+its envelope by running the real emitter from ``condor/telemetry/`` and handing
+the result to ``context.envelope()`` — the same code path a live install uses.
+If FEAT-023 ever changes shape, this file fails rather than the collector
+silently dropping a field in production.
+
+**Untrusted input cannot do damage.** This endpoint is unauthenticated and
+public by design, so most of what follows is negative: an oversized body, an
+over-long batch, a rate-limited caller and a malformed envelope each have to be
+refused *without touching the database*, and no refusal may echo any part of
+the request back.
+
+**Idempotency is real.** The client retries after a timeout. If a retry could
+inflate a count, every adoption number the exercise exists to produce would be
+unreliable.
+
+The whole suite runs against SQLite in a ``tmp_path``. Nothing here binds a
+port, starts a container, or outlives the test.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import re
+import tomllib
+import uuid
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+import pytest
+from starlette.testclient import TestClient
+
+from telemetry_server import ingest, rollup
+from telemetry_server.app import create_app
+from telemetry_server.store import open_store
+
+REPO = Path(__file__).resolve().parent.parent
+QUERIES = REPO / "telemetry_server" / "queries"
+
+
+# ── Harness ──────────────────────────────────────────────────────────────
+
+
+@pytest.fixture(autouse=True)
+def fresh_limits():
+    """The limiters are process-wide; a leftover bucket would leak between tests."""
+    ingest.by_ip.reset()
+    ingest.by_install.reset()
+    yield
+    ingest.by_ip.reset()
+    ingest.by_install.reset()
+
+
+@pytest.fixture
+def store(tmp_path):
+    store = asyncio.run(open_store(str(tmp_path / "telemetry.db")))
+    yield store
+    asyncio.run(store.close())
+
+
+@pytest.fixture
+def client(store):
+    with TestClient(create_app(store)) as client:
+        yield client
+
+
+class Spy:
+    """A store that refuses to be used, so "no database contact" is checkable."""
+
+    def __init__(self):
+        self.calls = 0
+
+    async def record(self, *args, **kwargs):
+        self.calls += 1
+        raise AssertionError("the database was reached for a request we refuse")
+
+    async def ping(self):
+        return True
+
+    async def close(self):
+        return None
+
+
+@pytest.fixture
+def spy_client():
+    spy = Spy()
+    with TestClient(create_app(spy)) as client:
+        yield client, spy
+
+
+def _event(name="command", props=None, ts=None, event_id=None):
+    return {
+        "id": event_id or uuid.uuid4().hex,
+        "ts": ts or datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "name": name,
+        "props": (
+            {"name": "portfolio", "surface": "telegram"} if props is None else props
+        ),
+    }
+
+
+def _envelope(events=None, **overrides):
+    """The shape condor/telemetry/context.py actually puts on the wire."""
+    envelope = {
+        "schema": 1,
+        "install_id": uuid.uuid4().hex,
+        "level": "usage",
+        "sent_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "app": {
+            "version": "54ad4dc",
+            "branch": "main",
+            "python": "3.12",
+            "os": "linux",
+            "arch": "arm64",
+            "in_docker": True,
+        },
+        "config": {
+            "has_web": True,
+            "has_gateway": False,
+            "has_hb_api": True,
+            "llm_providers": ["openai", "openrouter"],
+            "user_count": 3,
+            "server_count": 2,
+            "agent_count": 4,
+        },
+        "dropped": 0,
+        "events": [_event()] if events is None else events,
+    }
+    envelope.update(overrides)
+    return envelope
+
+
+def _rows(store, sql, *args):
+    return asyncio.run(store.fetch(sql, *args))
+
+
+# ── The contract is the client's ─────────────────────────────────────────
+
+
+def test_an_envelope_built_by_the_real_client_is_accepted_whole(
+    client, store, tmp_path, monkeypatch
+):
+    """The acceptance criterion that matters: a genuine FEAT-023 envelope lands.
+
+    Nothing here hand-writes the wire format. The events come out of the real
+    emitter and the envelope out of ``context.envelope``, so this test is the
+    thing that fails if emitter and collector ever drift apart.
+    """
+    import config_manager as cm_module
+    from condor.telemetry import consent, context, emitter
+
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setattr("utils.config.CONDOR_TELEMETRY", None, raising=False)
+    monkeypatch.setattr("utils.config.CONDOR_TELEMETRY_URL", None, raising=False)
+    monkeypatch.setattr(
+        "condor.agents.agent._DATA_ROOT", str(tmp_path / "data"), raising=False
+    )
+    cm_module.ConfigManager.reset_instance()
+    emitter.discard_buffer()
+    emitter.set_hosted(True)
+    consent.refresh()
+    try:
+        cm_module.get_config_manager()
+        consent.grant("usage")
+
+        emitter.emit("install")
+        emitter.emit("command", name="portfolio", surface="telegram", authorized=True)
+        emitter.emit("action", module="bots", verb="deploy", surface="web")
+        emitter.emit("trade", venue="cex", connector="binance", side="buy")
+        emitter.emit(
+            "agent_turn", kind="chat", provider="openai", model="gpt-5", tool_calls=3
+        )
+        emitter.emit("error", where="handlers.bots", exc_type="ValueError", sig="ab12")
+
+        events, dropped = emitter.drain()
+        envelope = context.envelope(events, dropped, consent.level())
+    finally:
+        cm_module.ConfigManager.reset_instance()
+        emitter.discard_buffer()
+        consent.refresh()
+
+    response = client.post("/v1/events", json=envelope)
+
+    assert response.status_code == 202
+    assert response.json() == {
+        "accepted": len(events),
+        "rejected": 0,
+        "duplicates": 0,
+    }
+
+    stored = _rows(store, "SELECT name FROM events ORDER BY name")
+    assert sorted(n for (n,) in stored) == sorted(e["name"] for e in events)
+
+    # The install context lands as columns, including the capability flags the
+    # client sends but the original design's table did not have.
+    (row,) = _rows(
+        store,
+        "SELECT level, version, branch, os, in_docker, has_hb_api, has_web, "
+        "user_count, llm_providers FROM installs",
+    )
+    assert row[0] == "usage"
+    assert row[1] == envelope["app"]["version"]
+    assert json.loads(row[8]) == envelope["config"]["llm_providers"]
+
+
+def test_the_taxonomy_has_exactly_one_definition_in_the_repo():
+    """``ingest`` validates against the emitter's own module, not a copy."""
+    source = (REPO / "telemetry_server" / "ingest.py").read_text(encoding="utf-8")
+    assert "from condor.telemetry import schema" in source
+
+    definitions = []
+    for path in REPO.rglob("*.py"):
+        if any(part in {".venv", "node_modules", "__pycache__"} for part in path.parts):
+            continue
+        if re.search(
+            r"^EVENTS(\s*:\s*[^=]+)?\s*=", path.read_text(encoding="utf-8"), re.M
+        ):
+            definitions.append(path.relative_to(REPO).as_posix())
+
+    assert definitions == ["condor/telemetry/schema.py"]
+
+
+# ── Idempotency and partial acceptance ───────────────────────────────────
+
+
+def test_the_same_envelope_twice_stores_one_copy(client, store):
+    """The client retries after a timeout; a retry must not inflate a metric."""
+    envelope = _envelope([_event(), _event(), _event()])
+
+    first = client.post("/v1/events", json=envelope)
+    second = client.post("/v1/events", json=envelope)
+
+    assert first.json()["accepted"] == 3
+    assert second.json() == {"accepted": 0, "rejected": 0, "duplicates": 3}
+
+    assert _rows(store, "SELECT COUNT(*) FROM events")[0][0] == 3
+    # install_days is incremented from newly inserted rows only, so the rollup
+    # tables cannot be inflated by a retry either.
+    assert _rows(store, "SELECT SUM(events) FROM install_days")[0][0] == 3
+
+
+def test_one_unknown_name_and_one_stray_prop_cost_two_rejections(client, store):
+    """Partial acceptance: a single client bug must not erase a good batch."""
+    envelope = _envelope(
+        [
+            _event(),
+            _event(name="a_command_from_a_newer_client"),
+            _event(props={"name": "bots", "surface": "web", "wallet": "0xdeadbeef"}),
+        ]
+    )
+
+    response = client.post("/v1/events", json=envelope)
+
+    assert response.status_code == 202
+    assert response.json()["rejected"] == 2
+    assert response.json()["accepted"] == 2
+
+    (props,) = _rows(store, "SELECT props FROM events WHERE name = $1", "command")[1]
+    assert "wallet" not in props
+    assert "0xdeadbeef" not in props
+
+
+def test_a_duplicate_id_inside_one_envelope_is_counted_once(client, store):
+    shared = uuid.uuid4().hex
+    envelope = _envelope([_event(event_id=shared), _event(event_id=shared)])
+
+    assert client.post("/v1/events", json=envelope).json() == {
+        "accepted": 1,
+        "rejected": 1,
+        "duplicates": 0,
+    }
+    assert _rows(store, "SELECT COUNT(*) FROM events")[0][0] == 1
+
+
+def test_a_clock_from_next_year_is_clamped_not_stored(client, store):
+    """Self-hosted clocks drift and occasionally lie. Believe them within 48h."""
+    future = (datetime.now(timezone.utc) + timedelta(days=365)).strftime(
+        "%Y-%m-%dT%H:%M:%SZ"
+    )
+    past = (datetime.now(timezone.utc) - timedelta(days=400)).strftime(
+        "%Y-%m-%dT%H:%M:%SZ"
+    )
+    client.post("/v1/events", json=_envelope([_event(ts=future), _event(ts=past)]))
+
+    stored = [
+        datetime.fromisoformat(ts) for (ts,) in _rows(store, "SELECT ts FROM events")
+    ]
+    now = datetime.now(timezone.utc)
+    for ts in stored:
+        assert abs(ts - now) <= ingest.CLOCK_SLACK + timedelta(minutes=1)
+
+
+# ── Untrusted input ──────────────────────────────────────────────────────
+
+
+def test_an_oversized_body_is_refused_without_a_query(spy_client):
+    client, spy = spy_client
+    body = b'{"schema":1,"pad":"' + b"a" * (ingest.MAX_BODY_BYTES + 1024) + b'"}'
+
+    response = client.post(
+        "/v1/events", content=body, headers={"content-type": "application/json"}
+    )
+
+    assert response.status_code == 413
+    assert response.json() == {"error": "body_too_large"}
+    assert spy.calls == 0
+
+
+def test_an_oversized_body_is_refused_even_without_a_content_length():
+    """Content-Length is the caller's claim, so the stream is counted as it arrives."""
+
+    class Chunked:
+        headers: dict = {}
+        client = None
+
+        async def stream(self):
+            for _ in range(4):
+                yield b"a" * (ingest.MAX_BODY_BYTES // 3)
+
+    with pytest.raises(ingest.Refused) as refusal:
+        asyncio.run(ingest.read_body(Chunked()))
+    assert refusal.value.reason == "body_too_large"
+
+
+def test_a_ten_thousand_event_envelope_is_refused_without_a_query(spy_client):
+    """Two caps guard this, and the outer one bites first.
+
+    Ten thousand events cannot fit inside a 1 MB body, so such an envelope is
+    refused while it is still bytes on a socket — a stronger guarantee than the
+    event-count cap. The count cap is what catches the envelope that *does* fit,
+    which is asserted separately below.
+    """
+    client, spy = spy_client
+
+    response = client.post(
+        "/v1/events", json=_envelope([_event() for _ in range(10_000)])
+    )
+
+    assert response.status_code == 413
+    assert response.json()["error"] in ("body_too_large", "too_many_events")
+    assert spy.calls == 0
+
+
+def test_more_events_than_the_cap_are_refused_without_a_query(spy_client):
+    client, spy = spy_client
+    oversized = [_event() for _ in range(ingest.MAX_EVENTS + 1)]
+
+    response = client.post("/v1/events", json=_envelope(oversized))
+
+    assert response.status_code == 413
+    assert response.json() == {"error": "too_many_events"}
+    assert spy.calls == 0
+
+
+@pytest.mark.parametrize(
+    "envelope, reason",
+    [
+        (
+            {
+                "schema": 99,
+                "install_id": uuid.uuid4().hex,
+                "level": "usage",
+                "events": [],
+            },
+            "unknown_schema",
+        ),
+        (
+            {"schema": 1, "install_id": "not-a-uuid", "level": "usage", "events": []},
+            "invalid_envelope",
+        ),
+        (
+            {
+                "schema": 1,
+                "install_id": uuid.uuid4().hex,
+                "level": "root",
+                "events": [],
+            },
+            "invalid_envelope",
+        ),
+        (
+            {
+                "schema": 1,
+                "install_id": uuid.uuid4().hex,
+                "level": "usage",
+                "events": {},
+            },
+            "invalid_envelope",
+        ),
+        ([1, 2, 3], "invalid_envelope"),
+    ],
+)
+def test_a_malformed_envelope_is_refused_without_a_query(spy_client, envelope, reason):
+    client, spy = spy_client
+
+    response = client.post("/v1/events", json=envelope)
+
+    assert response.status_code == 400
+    assert response.json() == {"error": reason}
+    assert spy.calls == 0
+
+
+def test_a_refusal_never_echoes_the_request(spy_client):
+    """No reflector, and no oracle for what the server did with a probe."""
+    marker = "canary-9f13ab-do-not-reflect"
+    client, _ = spy_client
+
+    responses = [
+        client.post("/v1/events", content=marker.encode()),
+        client.post("/v1/events", json={"schema": 1, "install_id": marker}),
+        client.post("/v1/events", json=_envelope(install_id=marker)),
+    ]
+
+    for response in responses:
+        assert response.status_code in (400, 413)
+        assert marker not in response.text
+        assert set(response.json()) == {"error"}
+
+
+def test_body_that_is_not_json_is_refused(spy_client):
+    client, spy = spy_client
+    response = client.post("/v1/events", content=b"{not json at all")
+    assert response.status_code == 400
+    assert response.json() == {"error": "invalid_json"}
+    assert spy.calls == 0
+
+
+def test_exceeding_the_ip_rate_limit_returns_429_without_a_query(spy_client):
+    """The limiter runs before the JSON parser, so a flood costs us nothing."""
+    client, spy = spy_client
+    for _ in range(ingest.RATE_PER_HOUR):
+        ingest.by_ip.allow("testclient")
+
+    response = client.post("/v1/events", json=_envelope())
+
+    assert response.status_code == 429
+    assert response.json() == {"error": "rate_limited"}
+    assert spy.calls == 0
+
+
+def test_a_flood_from_one_install_is_limited_even_across_addresses(spy_client):
+    """The per-install bucket is the one an attacker cannot rotate away from."""
+    client, spy = spy_client
+    install_id = str(uuid.uuid4())
+    for _ in range(ingest.RATE_PER_HOUR):
+        ingest.by_install.allow(install_id)
+
+    response = client.post("/v1/events", json=_envelope(install_id=install_id))
+
+    assert response.status_code == 429
+    assert spy.calls == 0
+
+
+def test_the_limiter_key_space_is_bounded(spy_client):
+    """An attacker-chosen key must not be a memory exhaustion primitive."""
+    limiter = ingest.RateLimiter(per_hour=60, max_keys=32)
+    for index in range(5_000):
+        limiter.allow(f"install-{index}")
+    assert len(limiter._buckets) <= 32
+
+
+def test_a_forwarded_header_is_ignored_unless_a_proxy_is_trusted(monkeypatch):
+    """Honouring X-Forwarded-For by default would be a one-header limit bypass."""
+
+    class Request:
+        headers = {"x-forwarded-for": "1.2.3.4"}
+
+        class client:
+            host = "10.0.0.1"
+
+    monkeypatch.delenv("TELEMETRY_TRUSTED_PROXY", raising=False)
+    assert ingest.client_ip(Request()) == "10.0.0.1"
+
+    monkeypatch.setenv("TELEMETRY_TRUSTED_PROXY", "true")
+    assert ingest.client_ip(Request()) == "1.2.3.4"
+
+
+def test_a_payload_cannot_reach_the_sql(client, store):
+    """Every value is a bound parameter; nothing is formatted into a statement."""
+    injection = "1'); DROP TABLE events; --"
+    envelope = _envelope()
+    envelope["app"]["version"] = injection
+    envelope["config"]["llm_providers"] = [injection]
+
+    assert client.post("/v1/events", json=envelope).status_code == 202
+
+    assert _rows(store, "SELECT COUNT(*) FROM events")[0][0] == 1
+    (version,) = _rows(store, "SELECT version FROM installs")[0]
+    assert "DROP TABLE" not in version
+
+
+def test_unknown_envelope_fields_are_dropped_not_stored(client, store):
+    envelope = _envelope()
+    envelope["app"]["hostname"] = "trading-box.local"
+    envelope["config"]["api_key"] = "sk-live-secret"
+    envelope["surprise"] = {"nested": "value"}
+
+    assert client.post("/v1/events", json=envelope).status_code == 202
+
+    dump = json.dumps(_rows(store, "SELECT * FROM installs"))
+    assert "trading-box" not in dump
+    assert "sk-live-secret" not in dump
+
+
+def test_absurd_counts_are_clamped(client, store):
+    envelope = _envelope()
+    envelope["config"]["user_count"] = 10**18
+    envelope["dropped"] = 10**18
+
+    client.post("/v1/events", json=envelope)
+
+    (users, dropped) = _rows(store, "SELECT user_count, dropped_total FROM installs")[0]
+    assert users == ingest.MAX_COUNT
+    assert dropped == ingest.MAX_DROPPED
+
+
+# ── Health ───────────────────────────────────────────────────────────────
+
+
+def test_health_reports_the_database(client):
+    assert client.get("/health").json() == {"status": "ok"}
+
+
+def test_health_degrades_when_the_database_is_gone():
+    class Broken:
+        async def ping(self):
+            raise RuntimeError("connection refused")
+
+        async def close(self):
+            return None
+
+    with TestClient(create_app(Broken())) as client:
+        response = client.get("/health")
+    assert response.status_code == 503
+    assert response.json() == {"status": "degraded"}
+
+
+# ── Rollups and queries ──────────────────────────────────────────────────
+
+
+def _seed_cohorts(store):
+    """Three installs with hand-checkable retention, written straight to the
+    rollup table so the arithmetic under test is the rollup's, not ingest's."""
+    base = datetime(2026, 7, 1, tzinfo=timezone.utc).date()
+    plan = {
+        "aaaaaaaa-0000-4000-8000-000000000001": [0, 1, 7],  # retained at D1 and D7
+        "aaaaaaaa-0000-4000-8000-000000000002": [0, 1],  # D1 only
+        "aaaaaaaa-0000-4000-8000-000000000003": [0],  # never came back
+    }
+    for install_id, offsets in plan.items():
+        for offset in offsets:
+            asyncio.run(
+                store.execute(
+                    "INSERT INTO install_days (install_id, day, events, errors, version)"
+                    " VALUES ($1, $2, $3, $4, $5)",
+                    install_id,
+                    base + timedelta(days=offset),
+                    10,
+                    2 if offset == 0 else 0,
+                    "54ad4dc",
+                )
+            )
+    return base
+
+
+def test_retention_is_computed_from_the_permanent_table(store):
+    base = _seed_cohorts(store)
+    asyncio.run(rollup.run(store, today=base + timedelta(days=40)))
+
+    def metric(name):
+        rows = _rows(
+            store,
+            "SELECT value FROM daily_metrics WHERE day = $1 AND metric = $2",
+            base.isoformat(),
+            name,
+        )
+        return rows[0][0] if rows else None
+
+    assert metric("cohort_size") == 3
+    assert metric("retention_d1") == 2
+    assert metric("retention_d7") == 1
+    assert metric("retention_d30") == 0
+    assert metric("dau") == 3
+    assert metric("error_rate") == pytest.approx(6 / 30)
+
+
+def test_retention_survives_the_loss_of_the_raw_events(store):
+    """install_days is written on the ingest path precisely so this holds."""
+    base = _seed_cohorts(store)
+    asyncio.run(rollup.run(store, today=base + timedelta(days=40)))
+    before = _rows(store, "SELECT COUNT(*) FROM daily_metrics")[0][0]
+
+    asyncio.run(store.execute("DELETE FROM events"))
+    asyncio.run(rollup.run(store, today=base + timedelta(days=40)))
+
+    assert _rows(store, "SELECT COUNT(*) FROM daily_metrics")[0][0] >= before - 5
+    assert (
+        _rows(
+            store,
+            "SELECT value FROM daily_metrics WHERE metric = $1 AND day = $2",
+            "retention_d7",
+            base.isoformat(),
+        )[0][0]
+        == 1
+    )
+
+
+def test_the_rollup_summarises_a_real_ingest(client, store):
+    client.post(
+        "/v1/events",
+        json=_envelope(
+            [
+                _event(),
+                _event(props={"name": "bots", "surface": "telegram"}),
+                _event(
+                    name="agent_turn",
+                    props={
+                        "kind": "chat",
+                        "provider": "openai",
+                        "model": "gpt-5",
+                        "tool_calls": 4,
+                        "outcome": "done",
+                    },
+                ),
+                _event(
+                    name="error",
+                    props={
+                        "where": "handlers.bots",
+                        "exc_type": "ValueError",
+                        "sig": "ab12",
+                    },
+                ),
+                _event(
+                    name="confirmation", props={"tool": "execute", "decision": "allow"}
+                ),
+            ]
+        ),
+    )
+    asyncio.run(rollup.run(store))
+
+    metrics = {
+        (metric, dim): value
+        for metric, dim, value in _rows(
+            store, "SELECT metric, dim, value FROM daily_metrics"
+        )
+    }
+    assert metrics[("event_rank", "command")] == 2
+    assert metrics[("command_rank", "bots")] == 1
+    assert metrics[("agent_provider", "openai")] == 1
+    assert metrics[("agent_tool_calls_avg", "")] == 4
+    assert metrics[("confirmation_decision", "allow")] == 1
+    assert metrics[("error_group", "ValueError:ab12")] == 1
+    assert metrics[("version_share", "54ad4dc")] == 1
+
+
+def _statements(path):
+    """Split a query file into runnable statements.
+
+    Comments come out first: they are prose, and prose contains semicolons.
+    """
+    body = "\n".join(
+        line
+        for line in path.read_text(encoding="utf-8").splitlines()
+        if not line.strip().startswith("--")
+    )
+    return [s.strip() for s in body.split(";") if s.strip()]
+
+
+def test_every_query_runs_and_answers_its_question(client, store):
+    base = _seed_cohorts(store)
+    client.post("/v1/events", json=_envelope())
+    asyncio.run(rollup.run(store, today=base + timedelta(days=40)))
+
+    results = {}
+    for path in sorted(QUERIES.glob("*.sql")):
+        results[path.name] = [_rows(store, sql) for sql in _statements(path)]
+
+    assert set(results) == {
+        "adoption.sql",
+        "agent_economics.sql",
+        "feature_usage.sql",
+        "reliability.sql",
+        "retention.sql",
+    }
+    # Each one has to return numbers, not merely parse.
+    assert any(row[1] == "dau" for row in results["adoption.sql"][0])
+    assert (base.isoformat(), 3, 2, 1, 0) in [
+        tuple(row) for row in results["retention.sql"][0]
+    ]
+    assert any(row[1] == "command" for row in results["feature_usage.sql"][0])
+    assert results["reliability.sql"][0]
+    assert results["agent_economics.sql"]
+
+
+def test_no_query_can_correlate_installs_through_user_hash():
+    """`user_hash` is salted per install, so a global GROUP BY on it would be
+    inventing a cross-install identity the client deliberately refused to give."""
+    for path in QUERIES.glob("*.sql"):
+        for sql in _statements(path):
+            assert "user_hash" not in sql
+
+
+def test_sqlite_retention_deletes_what_postgres_would_drop(store, monkeypatch):
+    monkeypatch.setenv("TELEMETRY_RETENTION_DAYS", "30")
+    old = datetime.now(timezone.utc) - timedelta(days=200)
+    asyncio.run(
+        store.execute(
+            "INSERT INTO events (id, install_id, ts, received_at, name, props)"
+            " VALUES ($1, $2, $3, $4, $5, $6)",
+            uuid.uuid4().hex,
+            uuid.uuid4().hex,
+            old,
+            old,
+            "heartbeat",
+            "{}",
+        )
+    )
+
+    assert (
+        asyncio.run(
+            rollup.maintain_partitions(store, datetime.now(timezone.utc).date())
+        )
+        == []
+    )
+    assert _rows(store, "SELECT COUNT(*) FROM events")[0][0] == 0
+
+
+def test_partition_names_run_a_month_ahead():
+    """The Postgres path builds names from dates it computed, never from input."""
+    assert rollup._next_month(rollup._month_start(datetime(2026, 12, 31).date())) == (
+        datetime(2027, 1, 1).date()
+    )
+
+
+# ── Packaging ────────────────────────────────────────────────────────────
+
+
+def test_asyncpg_is_an_extra_and_never_a_runtime_dependency():
+    """`uv sync` without the extra must not pull a database driver into a bot."""
+    manifest = tomllib.loads((REPO / "pyproject.toml").read_text(encoding="utf-8"))
+    project = manifest["project"]
+
+    assert not any("asyncpg" in dep for dep in project["dependencies"])
+    extras = project["optional-dependencies"]
+    assert any("asyncpg" in dep for dep in extras["telemetry-server"])

From 34e4ad5a94e2e862156324541f7b003e11cb5ff7 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Wed, 12 Aug 2026 00:31:56 +0300
Subject: [PATCH 019/116] Move the telemetry collector to its own repo
 (condor-telemetry-server)

The collector only ever imported the client's wire contract
(condor/telemetry/schema.py); nothing in Condor imported the collector.
It now lives in its own project with a vendored copy of that schema, so a
bot install no longer carries a database driver or the server code. A guard
test keeps asyncpg out of every dependency group and blocks any Condor
module from importing telemetry_server again.
---
 pyproject.toml                                |   3 -
 telemetry_server/.env.example                 |   4 -
 telemetry_server/Dockerfile                   |  42 -
 telemetry_server/README.md                    | 183 -----
 telemetry_server/__init__.py                  |  22 -
 telemetry_server/app.py                       |  90 ---
 telemetry_server/config.py                    |  49 --
 telemetry_server/docker-compose.yml           |  75 --
 telemetry_server/grafana/datasource.yml       |  27 -
 telemetry_server/ingest.py                    | 349 --------
 telemetry_server/migrations/001_init.sql      |  85 --
 .../migrations/001_init.sqlite.sql            |  59 --
 telemetry_server/queries/adoption.sql         |  19 -
 telemetry_server/queries/agent_economics.sql  |  27 -
 telemetry_server/queries/feature_usage.sql    |  25 -
 telemetry_server/queries/reliability.sql      |  30 -
 telemetry_server/queries/retention.sql        |  21 -
 telemetry_server/rollup.py                    | 339 --------
 telemetry_server/store.py                     | 379 ---------
 tests/test_collector_is_extracted.py          |  36 +
 tests/test_telemetry_server.py                | 749 ------------------
 21 files changed, 36 insertions(+), 2577 deletions(-)
 delete mode 100644 telemetry_server/.env.example
 delete mode 100644 telemetry_server/Dockerfile
 delete mode 100644 telemetry_server/README.md
 delete mode 100644 telemetry_server/__init__.py
 delete mode 100644 telemetry_server/app.py
 delete mode 100644 telemetry_server/config.py
 delete mode 100644 telemetry_server/docker-compose.yml
 delete mode 100644 telemetry_server/grafana/datasource.yml
 delete mode 100644 telemetry_server/ingest.py
 delete mode 100644 telemetry_server/migrations/001_init.sql
 delete mode 100644 telemetry_server/migrations/001_init.sqlite.sql
 delete mode 100644 telemetry_server/queries/adoption.sql
 delete mode 100644 telemetry_server/queries/agent_economics.sql
 delete mode 100644 telemetry_server/queries/feature_usage.sql
 delete mode 100644 telemetry_server/queries/reliability.sql
 delete mode 100644 telemetry_server/queries/retention.sql
 delete mode 100644 telemetry_server/rollup.py
 delete mode 100644 telemetry_server/store.py
 create mode 100644 tests/test_collector_is_extracted.py
 delete mode 100644 tests/test_telemetry_server.py

diff --git a/pyproject.toml b/pyproject.toml
index 5c90f957..70d7398c 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -29,9 +29,6 @@ dependencies = [
 
 [project.optional-dependencies]
 dev = ["pytest", "pytest-asyncio", "black", "isort", "pre-commit"]
-# The telemetry collector (FEAT-024, telemetry_server/). Kept out of a normal
-# install: a bot that only *emits* telemetry has no use for a database driver.
-telemetry-server = ["asyncpg"]
 
 [tool.isort]
 profile = "black"
diff --git a/telemetry_server/.env.example b/telemetry_server/.env.example
deleted file mode 100644
index 44d6900d..00000000
--- a/telemetry_server/.env.example
+++ /dev/null
@@ -1,4 +0,0 @@
-# Copy to .env beside docker-compose.yml. Both are required; compose refuses to
-# start without them rather than defaulting to something guessable.
-POSTGRES_PASSWORD=change-me
-GRAFANA_PASSWORD=change-me
diff --git a/telemetry_server/Dockerfile b/telemetry_server/Dockerfile
deleted file mode 100644
index fa16ac1f..00000000
--- a/telemetry_server/Dockerfile
+++ /dev/null
@@ -1,42 +0,0 @@
-# The collector image.
-#
-# It builds from the Condor repository root rather than from this directory,
-# because ingest.py imports `condor.telemetry.schema` — the same taxonomy the
-# client sanitises with — and that import is the whole reason the collector
-# lives in this repo (FEAT-024). The cost is an image that carries Condor's
-# dependency set rather than four packages; the benefit is that the emitter and
-# the validator cannot drift apart. That trade was made deliberately.
-#
-# Build from the repo root:  docker build -f telemetry_server/Dockerfile .
-
-FROM python:3.12-slim
-
-ENV PYTHONUNBUFFERED=1 \
-    PYTHONDONTWRITEBYTECODE=1 \
-    UV_COMPILE_BYTECODE=1 \
-    UV_LINK_MODE=copy
-
-COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
-
-WORKDIR /app
-
-# Dependencies first so a code change does not re-resolve the world.
-COPY pyproject.toml uv.lock* README.md ./
-RUN uv sync --extra telemetry-server --no-dev --no-install-project
-
-COPY condor/ ./condor/
-COPY telemetry_server/ ./telemetry_server/
-COPY utils/ ./utils/
-COPY config_manager.py ./
-
-# Nothing here needs to be root, and an unauthenticated public endpoint is the
-# last process that should be.
-RUN useradd --system --uid 10001 collector && chown -R collector /app
-USER collector
-
-EXPOSE 8000
-
-# Plain HTTP on purpose: TLS terminates at the reverse proxy in front, matching
-# how the hummingbot/deploy stack is already run.
-CMD ["uv", "run", "--no-sync", "uvicorn", "telemetry_server.app:create_app", \
-     "--factory", "--host", "0.0.0.0", "--port", "8000"]
diff --git a/telemetry_server/README.md b/telemetry_server/README.md
deleted file mode 100644
index e935687b..00000000
--- a/telemetry_server/README.md
+++ /dev/null
@@ -1,183 +0,0 @@
-# Condor telemetry collector
-
-The receiving end of [`condor/telemetry/`](../condor/telemetry/) (FEAT-023).
-Consenting installs POST batched, anonymous envelopes here; this service
-validates them against the client's own taxonomy, stores them idempotently,
-rolls them up nightly, and leaves five SQL files behind that answer the
-questions the exercise exists for.
-
-It is not installed by default and it is not running anywhere. Standing it up is
-a deliberate act.
-
-## Why it lives in this repository
-
-`ingest.py` imports `condor.telemetry.schema` — the *same module* the emitter
-sanitises with. A separate collector repo would be tidier operationally but
-would force the event taxonomy to exist in two places, and a taxonomy that
-drifts between emitter and validator is the classic failure of this kind of
-system: the client starts sending a property, the server silently drops it, and
-nobody notices for three months. Here, drift is not unlikely — it is impossible,
-and `tests/test_telemetry_server.py` asserts there is no second copy in the repo.
-
-The cost is a container image carrying Condor's dependency set rather than four
-packages. That trade was made knowingly.
-
-## Endpoints
-
-| Method | Path | Behaviour |
-|---|---|---|
-| `POST` | `/v1/events` | Ingest one envelope → `202 {"accepted": n, "rejected": m, "duplicates": d}` |
-| `GET`  | `/health`    | Liveness plus a real database round trip |
-
-There is no endpoint that reads data back to an install, and no API docs are
-served: a schema browser on an unauthenticated endpoint is surface with no
-reader.
-
-## Surviving the open internet
-
-Installs are anonymous by design, so there is no credential to issue without
-creating the identity we explicitly do not want. The endpoint is therefore
-public and unauthenticated, and the pipeline is ordered so that everything cheap
-happens before anything expensive:
-
-1. **Body cap — 1 MB.** Counted as the stream arrives. `Content-Length` is
-   checked first because it is free, but it is not trusted: a chunked request
-   can omit or understate it.
-2. **Rate limit by source IP** — token bucket, 60/h, *before* the JSON parser
-   runs. `X-Forwarded-For` is ignored unless `TELEMETRY_TRUSTED_PROXY` is set,
-   because otherwise the header is a one-line rate-limit bypass. The limiter's
-   key space is capped and evicts LRU, so an attacker-chosen `install_id` cannot
-   become a memory-exhaustion primitive.
-3. **Envelope validation** — unknown `schema` versions, unknown `level`s, a
-   malformed `install_id` and batches over 500 events are refused whole.
-4. **Event validation** against `condor.telemetry.schema`. An unknown event name
-   or an out-of-spec property is **dropped and counted**, and the rest of the
-   batch is still accepted — rejecting a whole envelope over one malformed event
-   would let a single client bug erase a day of otherwise good data. The
-   `rejected` counter is the early warning that a taxonomy change broke
-   something, so chart it.
-5. **Persist** in one transaction, `ON CONFLICT DO NOTHING`.
-
-Two invariants hold throughout. **No payload value is ever formatted into SQL** —
-`store.py` takes bound parameters only, and the only interpolation anywhere is
-partition names built from dates the rollup computed itself. **No error response
-echoes any part of the request** — every refusal is a fixed string, so this
-endpoint cannot be turned into a reflector or used as an oracle.
-
-Unknown fields inside `app` and `config` are not stored, not logged, and not
-reflected. They simply do not exist here.
-
-### What this does *not* defend against
-
-Anyone can POST fabricated envelopes with random `install_id`s and skew the
-adoption numbers. Rate limits raise the cost; the real defence is that the payoff
-is nil and the data steers internal direction, not anything with money attached.
-If it ever becomes a problem the fix is a signed `install_id` issued on first
-contact — deliberately not built now.
-
-## Storage
-
-`migrations/001_init.sql` (Postgres) and `001_init.sqlite.sql` (SQLite) define
-the same four tables:
-
-- **`installs`** — one upserted row per install: identity, platform, capability
-  flags, counts, and a running `dropped_total`.
-- **`events`** — append-only, partitioned by month in Postgres so the 90-day
-  retention is a `DROP TABLE` rather than a mass `DELETE`.
-- **`install_days`** — written on the **ingest path**, from newly inserted rows
-  only. This is what every retention question depends on and what survives raw
-  expiry, which is why it is not deferred to the rollup.
-- **`daily_metrics`** — the nightly rollup. Permanent.
-
-Both `ts` and `received_at` are kept. Client clocks on self-hosted boxes drift
-and occasionally lie, so ingest clamps `ts` to `received_at ± 48 h`; dashboards
-count volume by `received_at` and trust `ts` only for ordering inside one
-install's session.
-
-**SQLite is a real backend, not a mock.** The collector's tests run in Condor's
-own `uv run pytest` with no database daemon, against the same statements
-production executes. Postgres is what you deploy; SQLite is what keeps the tests
-honest and runnable.
-
-## Rollups
-
-`rollup.py` runs on an interval inside the collector process (a plain asyncio
-loop — the job is "every few hours, never concurrently with itself", and one
-service with no extra runtime is easier to reason about than one with a
-scheduler in it). SQL does the grouping; Python does the date arithmetic and
-cohort matching, which is what lets one rollup run unchanged against both
-backends.
-
-It writes `dau`/`wau`/`mau`, `cohort_size` + `retention_d1/d7/d30`,
-`version_share`/`os_share`/`provider_share`, event and command/action/routine
-ranks, `error_rate` and `error_group`, the agent mix and per-turn cost, and
-`dropped_total`/`dropped_rate` — so client-side rate limiting never masquerades
-as "things got quieter". It also creates next month's partition and drops what
-has aged past `TELEMETRY_RETENTION_DAYS`.
-
-Rollups exist from day one rather than "later" because backfilling one after
-dropping the raw data it came from is impossible.
-
-## The five questions
-
-One file each in `queries/`, each runnable standalone against Postgres *or* the
-SQLite the tests seed, and each readable without Grafana:
-
-| File | Question |
-|---|---|
-| `adoption.sql` | How many installs are alive, on what, and how fast do upgrades spread? |
-| `retention.sql` | Do people stay? D1 / D7 / D30 by cohort. |
-| `feature_usage.sql` | What is actually used, and what are we maintaining for nobody? |
-| `reliability.sql` | What is broken out there, and against which upstream? |
-| `agent_economics.sql` | Which providers and models, at what cost per turn, dry-run vs live? |
-
-No query groups by `user_hash`. It is salted per install, so it can be counted
-inside one install but is meaningless across them, and grouping by it globally
-would invent a cross-install identity the client deliberately refused to
-provide. A test asserts this.
-
-## Configuration
-
-| Variable | Default | Meaning |
-|---|---|---|
-| `TELEMETRY_DSN` | `sqlite:///telemetry.db` | Postgres URL in production; anything else is a SQLite path. |
-| `TELEMETRY_TRUSTED_PROXY` | unset | Believe `X-Forwarded-For`. Only set this when a proxy really is in front. |
-| `TELEMETRY_RETENTION_DAYS` | `90` | How long raw events live. Rollups are permanent regardless. |
-| `TELEMETRY_ROLLUP_INTERVAL_S` | `21600` | How often the rollup runs. |
-
-## Running it
-
-```bash
-cp .env.example .env      # set POSTGRES_PASSWORD and GRAFANA_PASSWORD
-docker compose -f telemetry_server/docker-compose.yml up -d
-```
-
-Only `collector` should be reachable from the internet, and only through a
-reverse proxy that terminates TLS — the service speaks plain HTTP inside the
-compose network, matching how the `hummingbot/deploy` stack is already run.
-Postgres and Grafana bind to loopback. **Grafana is the weakest operational link
-here**: it is the only component with a login and a session cookie, so keep it
-behind the same proxy or VPN as the rest, never exposed alongside ingest.
-
-`grafana/datasource.yml` provisions the Postgres datasource. Dashboards are not
-auto-provisioned — the `queries/*.sql` files are the deliverable and a panel is
-a paste.
-
-Once it is up, point an install at it:
-
-```bash
-CONDOR_TELEMETRY_URL=https://telemetry.example.org/v1/events
-```
-
-## Tests
-
-```bash
-uv run pytest tests/test_telemetry_server.py
-```
-
-They run against SQLite in a `tmp_path` and never bind a port, start a
-container, or leave anything behind. The first test is the important one: it
-builds its envelope by running the **real emitter** from `condor/telemetry/` and
-handing the result to `context.envelope()`, so if FEAT-023 ever changes shape,
-this suite fails instead of the collector silently dropping a field in
-production.
diff --git a/telemetry_server/__init__.py b/telemetry_server/__init__.py
deleted file mode 100644
index 0d8e4ace..00000000
--- a/telemetry_server/__init__.py
+++ /dev/null
@@ -1,22 +0,0 @@
-"""The receiving end of Condor's usage telemetry (FEAT-024).
-
-``condor/telemetry/`` (FEAT-023) makes every consenting install emit a batched,
-anonymous event stream. This package is what it reports to: a small FastAPI
-service that accepts those envelopes, stores them idempotently, rolls them up,
-and leaves five SQL files behind that answer the questions the exercise exists
-for.
-
-It lives in this repository on purpose. The alternative — a separate collector
-repo — forces the event taxonomy to exist in two places, and a taxonomy that
-drifts between emitter and validator is the classic failure of this kind of
-system: the client starts sending a property, the server silently drops it, and
-nobody notices for three months. :mod:`telemetry_server.ingest` imports
-:mod:`condor.telemetry.schema` **directly**, so drift is not unlikely, it is
-impossible.
-
-Nothing here is installed by default. ``asyncpg`` sits behind the
-``telemetry-server`` extra in ``pyproject.toml`` and is imported lazily, so a
-normal Condor install carries this directory as dead weight and nothing else.
-"""
-
-__all__ = ["__doc__"]
diff --git a/telemetry_server/app.py b/telemetry_server/app.py
deleted file mode 100644
index 39fa2a0b..00000000
--- a/telemetry_server/app.py
+++ /dev/null
@@ -1,90 +0,0 @@
-"""The collector service: two endpoints and a background rollup.
-
-``create_app()`` mirrors ``condor/web/app.py`` — a factory returning a
-configured :class:`~fastapi.FastAPI`, so the test suite builds an app against a
-throwaway database instead of importing a module-level singleton that has
-already opened a connection to whatever the environment pointed at.
-
-There is deliberately no read endpoint. Nothing here serves data back to an
-install, so the only thing this process will do for an anonymous caller is
-accept an envelope and say how much of it it kept.
-"""
-
-from __future__ import annotations
-
-import asyncio
-import contextlib
-import logging
-from contextlib import asynccontextmanager
-
-from fastapi import FastAPI
-from fastapi.responses import JSONResponse
-
-from telemetry_server import config, ingest, rollup
-from telemetry_server.store import Store, open_store
-
-log = logging.getLogger(__name__)
-
-
-async def _rollup_loop(app: FastAPI) -> None:
-    """Recompute the permanent tables on a fixed interval.
-
-    A plain asyncio task rather than a scheduler dependency: the job is "run
-    this every few hours, never concurrently with itself", which is a loop, and
-    one service with no extra runtime is easier to reason about than one with a
-    scheduler in it.
-    """
-    interval = config.rollup_interval_s()
-    while True:
-        try:
-            await asyncio.sleep(interval)
-            await rollup.run(app.state.store)
-        except asyncio.CancelledError:
-            raise
-        except Exception:
-            log.exception("Telemetry rollup failed; will retry next interval")
-
-
-@asynccontextmanager
-async def lifespan(app: FastAPI):
-    if getattr(app.state, "store", None) is None:
-        app.state.store = await open_store(config.dsn())
-        app.state.owns_store = True
-    task = asyncio.create_task(_rollup_loop(app))
-    try:
-        yield
-    finally:
-        task.cancel()
-        with contextlib.suppress(asyncio.CancelledError):
-            await task
-        if getattr(app.state, "owns_store", False):
-            await app.state.store.close()
-
-
-def create_app(store: Store | None = None) -> FastAPI:
-    """Build the collector. Pass a ``store`` to drive it against a temp database."""
-    app = FastAPI(
-        title="Condor Telemetry Collector",
-        version="1.0.0",
-        lifespan=lifespan,
-        # The ingest contract is documented in this repository; a public schema
-        # browser on an unauthenticated endpoint is surface with no reader.
-        docs_url=None,
-        redoc_url=None,
-        openapi_url=None,
-    )
-    app.state.store = store
-    app.state.owns_store = False
-    app.include_router(ingest.router)
-
-    @app.get("/health")
-    async def health() -> JSONResponse:
-        """Liveness plus a real database round trip."""
-        try:
-            await app.state.store.ping()
-        except Exception:
-            log.exception("Telemetry collector health check failed")
-            return JSONResponse(status_code=503, content={"status": "degraded"})
-        return JSONResponse(status_code=200, content={"status": "ok"})
-
-    return app
diff --git a/telemetry_server/config.py b/telemetry_server/config.py
deleted file mode 100644
index baa8c212..00000000
--- a/telemetry_server/config.py
+++ /dev/null
@@ -1,49 +0,0 @@
-"""Every knob the collector reads from its environment, in one place.
-
-The house pattern (``utils/config.py``) is a module of module-level reads rather
-than env lookups scattered through the code, so that what a deployment can
-change is one file long. These are read per call rather than at import, because
-the test suite sets them with ``monkeypatch.setenv``.
-"""
-
-from __future__ import annotations
-
-import os
-
-DEFAULT_DSN = "sqlite:///telemetry.db"
-DEFAULT_RETENTION_DAYS = 90
-DEFAULT_ROLLUP_INTERVAL_S = 6 * 3600
-
-
-def dsn() -> str:
-    """Where events go. A Postgres URL in production, a SQLite path otherwise."""
-    return os.environ.get("TELEMETRY_DSN", "").strip() or DEFAULT_DSN
-
-
-def trust_proxy() -> bool:
-    """Whether ``X-Forwarded-For`` may be believed.
-
-    Off unless an operator says otherwise, because the header is written by the
-    caller: trusting it on a directly-exposed service hands every client a
-    one-header rate-limit bypass.
-    """
-    return os.environ.get("TELEMETRY_TRUSTED_PROXY", "").strip().lower() in (
-        "1",
-        "true",
-        "yes",
-    )
-
-
-def retention_days() -> int:
-    """How long raw events live. Rollups are permanent regardless."""
-    try:
-        return max(1, int(os.environ.get("TELEMETRY_RETENTION_DAYS", "").strip()))
-    except ValueError:
-        return DEFAULT_RETENTION_DAYS
-
-
-def rollup_interval_s() -> int:
-    try:
-        return max(60, int(os.environ.get("TELEMETRY_ROLLUP_INTERVAL_S", "").strip()))
-    except ValueError:
-        return DEFAULT_ROLLUP_INTERVAL_S
diff --git a/telemetry_server/docker-compose.yml b/telemetry_server/docker-compose.yml
deleted file mode 100644
index 4f09a9a1..00000000
--- a/telemetry_server/docker-compose.yml
+++ /dev/null
@@ -1,75 +0,0 @@
-# The collector stack: ingest, its database, and the dashboards.
-#
-# Only `collector` is meant to be reachable from the internet, and only through
-# a reverse proxy that terminates TLS. Postgres and Grafana are bound to
-# loopback: Grafana is the one component here with a login and a session cookie,
-# and it has no business sharing an exposure with an endpoint whose whole design
-# is that anyone may POST to it.
-#
-#   docker compose -f telemetry_server/docker-compose.yml up -d
-#
-# Set POSTGRES_PASSWORD and GRAFANA_PASSWORD in an .env file beside this one.
-
-services:
-  postgres:
-    image: postgres:16-alpine
-    restart: unless-stopped
-    environment:
-      POSTGRES_DB: telemetry
-      POSTGRES_USER: telemetry
-      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}
-    volumes:
-      - telemetry-db:/var/lib/postgresql/data
-    ports:
-      - "127.0.0.1:5432:5432"
-    healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U telemetry -d telemetry"]
-      interval: 10s
-      timeout: 5s
-      retries: 5
-
-  collector:
-    build:
-      context: ..
-      dockerfile: telemetry_server/Dockerfile
-    restart: unless-stopped
-    depends_on:
-      postgres:
-        condition: service_healthy
-    environment:
-      TELEMETRY_DSN: postgresql://telemetry:${POSTGRES_PASSWORD}@postgres:5432/telemetry
-      # X-Forwarded-For is only believed because there really is a proxy in
-      # front here. Leave this unset on a directly-exposed deployment.
-      TELEMETRY_TRUSTED_PROXY: "true"
-      TELEMETRY_RETENTION_DAYS: "90"
-    ports:
-      - "127.0.0.1:8000:8000"
-    healthcheck:
-      test: ["CMD-SHELL", "python -c \"import urllib.request; urllib.request.urlopen('http://localhost:8000/health')\""]
-      interval: 30s
-      timeout: 5s
-      retries: 3
-
-  grafana:
-    image: grafana/grafana:11.3.0
-    restart: unless-stopped
-    depends_on:
-      postgres:
-        condition: service_healthy
-    environment:
-      GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_PASSWORD:?set GRAFANA_PASSWORD}
-      GF_USERS_ALLOW_SIGN_UP: "false"
-      GF_AUTH_ANONYMOUS_ENABLED: "false"
-      TELEMETRY_DB_PASSWORD: ${POSTGRES_PASSWORD}
-    volumes:
-      - grafana-data:/var/lib/grafana
-      - ./grafana:/etc/grafana/provisioning/datasources:ro
-      # The five queries, readable inside the container so a panel can be built
-      # by pasting one in. They are the deliverable; the panels are decoration.
-      - ./queries:/etc/telemetry-queries:ro
-    ports:
-      - "127.0.0.1:3000:3000"
-
-volumes:
-  telemetry-db:
-  grafana-data:
diff --git a/telemetry_server/grafana/datasource.yml b/telemetry_server/grafana/datasource.yml
deleted file mode 100644
index abadd044..00000000
--- a/telemetry_server/grafana/datasource.yml
+++ /dev/null
@@ -1,27 +0,0 @@
-# Grafana reads the collector's Postgres directly. There is no API in between:
-# the queries in ../queries/ are plain SQL against the rollup tables, so a panel
-# is a paste rather than an integration.
-#
-# The account is read-only by intent. Grant it explicitly after first boot:
-#   CREATE USER grafana WITH PASSWORD '...';
-#   GRANT CONNECT ON DATABASE telemetry TO grafana;
-#   GRANT USAGE ON SCHEMA public TO grafana;
-#   GRANT SELECT ON ALL TABLES IN SCHEMA public TO grafana;
-
-apiVersion: 1
-
-datasources:
-  - name: Telemetry
-    type: postgres
-    uid: condor-telemetry
-    access: proxy
-    url: postgres:5432
-    database: telemetry
-    user: telemetry
-    secureJsonData:
-      password: ${TELEMETRY_DB_PASSWORD}
-    jsonData:
-      sslmode: disable
-      postgresVersion: 1600
-    isDefault: true
-    editable: false
diff --git a/telemetry_server/ingest.py b/telemetry_server/ingest.py
deleted file mode 100644
index 46937865..00000000
--- a/telemetry_server/ingest.py
+++ /dev/null
@@ -1,349 +0,0 @@
-"""``POST /v1/events`` — the one public, unauthenticated door.
-
-Installs are anonymous by design, so there is no credential to check: anything
-on the internet can POST here. The pipeline below is ordered so that everything
-cheap happens before anything expensive, and so that a hostile body is refused
-before it can cost a parse, a memory allocation, or a database round trip.
-
-1. **Body cap.** 1 MB, enforced while streaming. An oversized body is dropped
-   without ever being fully buffered or parsed.
-2. **Rate limit by source IP.** Token bucket, before the JSON parser runs.
-3. **Parse and validate the envelope.** Unknown ``schema`` versions and more
-   than :data:`MAX_EVENTS` events are refused whole.
-4. **Rate limit by ``install_id``**, now that we know it — still before any
-   database contact.
-5. **Validate each event** against :mod:`condor.telemetry.schema`, the same
-   module the client sanitises with. Offenders are dropped and counted; the
-   rest of the batch is still accepted, because rejecting a whole envelope over
-   one malformed event would let a single client bug erase a day of otherwise
-   good data.
-6. **Persist** in one transaction, with ``ON CONFLICT DO NOTHING``.
-
-Two rules hold everywhere in this module. Nothing from a payload is ever
-formatted into SQL — :mod:`telemetry_server.store` takes parameters only. And
-no error response ever echoes any part of the request: the replies are fixed
-strings, so this endpoint cannot be turned into a reflector or used to confirm
-what the server did with a probe.
-"""
-
-from __future__ import annotations
-
-import json
-import logging
-import time
-import uuid
-from collections import OrderedDict
-from datetime import datetime, timedelta, timezone
-
-from fastapi import APIRouter, Request
-from fastapi.responses import JSONResponse
-
-from condor.telemetry import schema
-
-log = logging.getLogger(__name__)
-
-router = APIRouter()
-
-KNOWN_SCHEMAS = frozenset({1})
-LEVELS = frozenset({"ping", "usage"})
-
-MAX_BODY_BYTES = 1024 * 1024
-MAX_EVENTS = 500
-MAX_PROPS = 64
-MAX_PROVIDERS = 10
-MAX_COUNT = 1_000_000
-MAX_DROPPED = 10_000_000
-# Client clocks on self-hosted boxes drift and occasionally lie. Anything
-# further out than this is the clock, not the event.
-CLOCK_SLACK = timedelta(hours=48)
-
-RATE_PER_HOUR = 60
-
-
-class RateLimiter:
-    """Token bucket per key, with a bounded key space.
-
-    The bound matters as much as the rate. ``install_id`` is attacker-chosen, so
-    a limiter that kept one bucket per id it has ever seen would be a memory
-    exhaustion primitive wearing a safety hat. Keys are held in an LRU capped at
-    :data:`max_keys`; evicting the least recently used one costs an attacker a
-    fresh bucket, which is exactly what they would have had anyway.
-    """
-
-    def __init__(self, per_hour: int = RATE_PER_HOUR, max_keys: int = 20_000) -> None:
-        self.per_hour = float(per_hour)
-        self.max_keys = max_keys
-        self._buckets: OrderedDict[str, tuple[float, float]] = OrderedDict()
-
-    def allow(self, key: str) -> bool:
-        now = time.monotonic()
-        tokens, last = self._buckets.pop(key, (self.per_hour, now))
-        tokens = min(self.per_hour, tokens + (now - last) * self.per_hour / 3600.0)
-        allowed = tokens >= 1.0
-        self._buckets[key] = (tokens - 1.0 if allowed else tokens, now)
-        while len(self._buckets) > self.max_keys:
-            self._buckets.popitem(last=False)
-        return allowed
-
-    def reset(self) -> None:
-        self._buckets.clear()
-
-
-by_ip = RateLimiter()
-by_install = RateLimiter()
-
-
-class Refused(Exception):
-    """A whole envelope is unusable. Carries a fixed, contentless reason."""
-
-    def __init__(self, status: int, reason: str) -> None:
-        super().__init__(reason)
-        self.status = status
-        self.reason = reason
-
-
-def _refuse(status: int, reason: str) -> JSONResponse:
-    """Every failure reply is a constant. No request data crosses back out."""
-    return JSONResponse(status_code=status, content={"error": reason})
-
-
-async def read_body(request: Request) -> bytes:
-    """Read at most :data:`MAX_BODY_BYTES`, refusing anything larger.
-
-    The declared ``Content-Length`` is checked first because it is free, but it
-    is not trusted: a chunked request can omit or understate it, so the stream
-    is counted as it arrives and abandoned the moment it crosses the cap.
-    """
-    declared = request.headers.get("content-length")
-    if declared is not None:
-        try:
-            if int(declared) > MAX_BODY_BYTES:
-                raise Refused(413, "body_too_large")
-        except ValueError:
-            raise Refused(400, "bad_request") from None
-
-    chunks: list[bytes] = []
-    size = 0
-    async for chunk in request.stream():
-        size += len(chunk)
-        if size > MAX_BODY_BYTES:
-            raise Refused(413, "body_too_large")
-        chunks.append(chunk)
-    return b"".join(chunks)
-
-
-def client_ip(request: Request) -> str:
-    """The peer address, or the forwarded one only where a proxy is trusted.
-
-    ``X-Forwarded-For`` is a client-supplied header. Honouring it by default
-    would hand every caller a free rate-limit bypass, so it is read only when
-    the operator has said there is a proxy in front (``TELEMETRY_TRUSTED_PROXY``).
-    """
-    from telemetry_server.config import trust_proxy
-
-    if trust_proxy():
-        forwarded = request.headers.get("x-forwarded-for", "")
-        first = forwarded.split(",")[0].strip()
-        if first:
-            return first[:64]
-    return request.client.host if request.client else "unknown"
-
-
-def _uuid_or_none(value: object) -> str | None:
-    if not isinstance(value, str) or len(value) > 45:
-        return None
-    try:
-        return str(uuid.UUID(value))
-    except ValueError:
-        return None
-
-
-def _ts_or_none(value: object) -> datetime | None:
-    if not isinstance(value, str) or len(value) > 40:
-        return None
-    try:
-        parsed = datetime.fromisoformat(value.strip().replace("Z", "+00:00"))
-    except ValueError:
-        return None
-    if parsed.tzinfo is None:
-        parsed = parsed.replace(tzinfo=timezone.utc)
-    return parsed.astimezone(timezone.utc)
-
-
-def clamp_ts(ts: datetime, received_at: datetime) -> datetime:
-    """Pull a lying clock back inside the window we are willing to believe."""
-    return max(received_at - CLOCK_SLACK, min(ts, received_at + CLOCK_SLACK))
-
-
-def _flag(value: object) -> bool | None:
-    return value if isinstance(value, bool) else None
-
-
-def _count(value: object) -> int | None:
-    if isinstance(value, bool) or not isinstance(value, int):
-        return None
-    return max(0, min(MAX_COUNT, value))
-
-
-def _install_row(envelope: dict, install_id: str, received_at: datetime) -> dict:
-    """Flatten ``app`` and ``config`` into the columns we keep.
-
-    Only declared keys are read. An unknown field in either sub-object is not
-    stored, not logged, and not reflected — it simply does not exist here.
-    """
-    app = envelope.get("app")
-    app = app if isinstance(app, dict) else {}
-    config = envelope.get("config")
-    config = config if isinstance(config, dict) else {}
-
-    providers = config.get("llm_providers")
-    if isinstance(providers, (list, tuple)):
-        clean = [schema.clean_str(p) for p in list(providers)[:MAX_PROVIDERS]]
-        providers = [p for p in clean if p]
-    else:
-        providers = []
-
-    return {
-        "install_id": install_id,
-        "received_at": received_at,
-        "level": envelope["level"],
-        "version": schema.clean_str(app.get("version")),
-        "branch": schema.clean_str(app.get("branch")),
-        "os": schema.clean_str(app.get("os")),
-        "arch": schema.clean_str(app.get("arch")),
-        "python": schema.clean_str(app.get("python")),
-        "in_docker": _flag(app.get("in_docker")),
-        "has_hb_api": _flag(config.get("has_hb_api")),
-        "has_gateway": _flag(config.get("has_gateway")),
-        "has_web": _flag(config.get("has_web")),
-        "user_count": _count(config.get("user_count")),
-        "server_count": _count(config.get("server_count")),
-        "agent_count": _count(config.get("agent_count")),
-        "llm_providers": providers,
-    }
-
-
-def validate(envelope: object, received_at: datetime) -> tuple[dict, list[dict], int]:
-    """Turn an untrusted body into rows, or raise :class:`Refused`.
-
-    Returns ``(install, events, rejected)``. ``rejected`` counts every offender
-    dropped — a whole event whose name we do not know, and each individual
-    property that fell outside its declared spec. Both are the early warning
-    that a taxonomy change broke something, so they are counted together and
-    reported back rather than swallowed.
-    """
-    if not isinstance(envelope, dict):
-        raise Refused(400, "invalid_envelope")
-    if envelope.get("schema") not in KNOWN_SCHEMAS:
-        raise Refused(400, "unknown_schema")
-
-    install_id = _uuid_or_none(envelope.get("install_id"))
-    if install_id is None:
-        raise Refused(400, "invalid_envelope")
-    if envelope.get("level") not in LEVELS:
-        raise Refused(400, "invalid_envelope")
-
-    raw_events = envelope.get("events")
-    if not isinstance(raw_events, list):
-        raise Refused(400, "invalid_envelope")
-    if len(raw_events) > MAX_EVENTS:
-        raise Refused(413, "too_many_events")
-
-    install = _install_row(envelope, install_id, received_at)
-
-    events: list[dict] = []
-    rejected = 0
-    seen: set[str] = set()
-    for raw in raw_events:
-        if not isinstance(raw, dict):
-            rejected += 1
-            continue
-        event_id = _uuid_or_none(raw.get("id"))
-        ts = _ts_or_none(raw.get("ts"))
-        name = raw.get("name")
-        props = raw.get("props")
-        if props is None:
-            props = {}
-        if (
-            event_id is None
-            or ts is None
-            or not isinstance(name, str)
-            or not schema.is_known(name)
-            or not isinstance(props, dict)
-            or len(props) > MAX_PROPS
-        ):
-            rejected += 1
-            continue
-        if event_id in seen:
-            # A duplicate inside one envelope: the database would swallow it,
-            # but counting it here keeps `accepted` equal to rows written.
-            rejected += 1
-            continue
-        seen.add(event_id)
-
-        clean = schema.sanitize(name, props)
-        if clean is None:
-            rejected += 1
-            continue
-        rejected += len(props) - len(clean)
-
-        events.append(
-            {
-                "id": event_id,
-                "install_id": install_id,
-                "ts": clamp_ts(ts, received_at),
-                "received_at": received_at,
-                "name": name,
-                "props": clean,
-            }
-        )
-
-    return install, events, rejected
-
-
-def _dropped(envelope: dict) -> int:
-    value = envelope.get("dropped")
-    if isinstance(value, bool) or not isinstance(value, int):
-        return 0
-    return max(0, min(MAX_DROPPED, value))
-
-
-@router.post("/v1/events")
-async def ingest(request: Request) -> JSONResponse:
-    try:
-        body = await read_body(request)
-    except Refused as refusal:
-        return _refuse(refusal.status, refusal.reason)
-
-    if not by_ip.allow(client_ip(request)):
-        return _refuse(429, "rate_limited")
-
-    try:
-        envelope = json.loads(body)
-    except ValueError:
-        return _refuse(400, "invalid_json")
-
-    try:
-        install, events, rejected = validate(envelope, _now())
-    except Refused as refusal:
-        return _refuse(refusal.status, refusal.reason)
-
-    if not by_install.allow(install["install_id"]):
-        return _refuse(429, "rate_limited")
-
-    store = request.app.state.store
-    try:
-        stored, duplicates = await store.record(install, events, _dropped(envelope))
-    except Exception:
-        # The reason a write failed is ours to read, never the caller's.
-        log.exception("Telemetry ingest could not persist an envelope")
-        return _refuse(503, "unavailable")
-
-    return JSONResponse(
-        status_code=202,
-        content={"accepted": stored, "rejected": rejected, "duplicates": duplicates},
-    )
-
-
-def _now() -> datetime:
-    return datetime.now(timezone.utc)
diff --git a/telemetry_server/migrations/001_init.sql b/telemetry_server/migrations/001_init.sql
deleted file mode 100644
index 6a00d091..00000000
--- a/telemetry_server/migrations/001_init.sql
+++ /dev/null
@@ -1,85 +0,0 @@
--- Collector schema (FEAT-024), Postgres flavour. Idempotent: safe to re-run on
--- every boot, which is how telemetry_server.app applies it.
---
--- `installs` is upserted on every envelope; `events` is append-only and
--- partitioned by month so the 90-day retention is a DROP TABLE rather than a
--- mass DELETE; `install_days` is written on the ingest path because it is what
--- survives raw expiry and every retention question depends on it;
--- `daily_metrics` is the nightly rollup and is permanent.
-
-CREATE TABLE IF NOT EXISTS installs (
-    install_id     uuid PRIMARY KEY,
-    first_seen     timestamptz NOT NULL,
-    last_seen      timestamptz NOT NULL,
-    level          text        NOT NULL,
-    version        text,
-    branch         text,
-    os             text,
-    arch           text,
-    python         text,
-    in_docker      boolean,
-    -- Capability flags the client actually sends (condor/telemetry/context.py
-    -- `config_shape`). The original design omitted them; the wire has them.
-    has_hb_api     boolean,
-    has_gateway    boolean,
-    has_web        boolean,
-    user_count     integer,
-    server_count   integer,
-    agent_count    integer,
-    llm_providers  text[],
-    dropped_total  bigint NOT NULL DEFAULT 0
-);
-
-CREATE TABLE IF NOT EXISTS events (
-    id          uuid        NOT NULL,
-    install_id  uuid        NOT NULL,
-    -- Both timestamps are kept on purpose. Client clocks on self-hosted boxes
-    -- drift and occasionally lie; ingest clamps `ts` to received_at +/- 48h,
-    -- dashboards count volume by `received_at`, and `ts` is only trusted for
-    -- ordering inside one install's session.
-    ts          timestamptz NOT NULL,
-    received_at timestamptz NOT NULL DEFAULT now(),
-    name        text        NOT NULL,
-    props       jsonb       NOT NULL DEFAULT '{}',
-    PRIMARY KEY (id, ts)
-) PARTITION BY RANGE (ts);
-
-CREATE INDEX IF NOT EXISTS events_name_ts ON events (name, ts);
-CREATE INDEX IF NOT EXISTS events_install_ts ON events (install_id, ts);
-
-CREATE TABLE IF NOT EXISTS install_days (
-    install_id uuid   NOT NULL,
-    day        date   NOT NULL,
-    events     bigint NOT NULL DEFAULT 0,
-    errors     bigint NOT NULL DEFAULT 0,
-    version    text,
-    PRIMARY KEY (install_id, day)
-);
-
-CREATE TABLE IF NOT EXISTS daily_metrics (
-    day    date    NOT NULL,
-    metric text    NOT NULL,
-    dim    text    NOT NULL DEFAULT '',
-    value  numeric NOT NULL,
-    PRIMARY KEY (day, metric, dim)
-);
-
--- A partitioned table with no partition rejects every insert, so seed this
--- month and next. telemetry_server.rollup keeps running a month ahead and drops
--- what has aged out.
-DO $$
-DECLARE
-    start_month date := date_trunc('month', now())::date;
-    bound       date;
-BEGIN
-    FOR i IN 0..1 LOOP
-        bound := (start_month + (i || ' month')::interval)::date;
-        EXECUTE format(
-            'CREATE TABLE IF NOT EXISTS %I PARTITION OF events '
-            'FOR VALUES FROM (%L) TO (%L)',
-            'events_' || to_char(bound, 'YYYY_MM'),
-            bound,
-            (bound + interval '1 month')::date
-        );
-    END LOOP;
-END $$;
diff --git a/telemetry_server/migrations/001_init.sqlite.sql b/telemetry_server/migrations/001_init.sqlite.sql
deleted file mode 100644
index 39d72e42..00000000
--- a/telemetry_server/migrations/001_init.sqlite.sql
+++ /dev/null
@@ -1,59 +0,0 @@
--- The same schema in SQLite, for the test suite and a single-box trial.
---
--- Three differences, all forced by the engine and none of them semantic:
--- there is no partitioning (retention is a DELETE, which is fine at test
--- volume), no array type (`llm_providers` is a JSON array in TEXT), and no
--- native date/timestamp type (everything is ISO-8601 UTC text, which sorts and
--- compares correctly). Column names, keys and conflict targets are identical to
--- 001_init.sql so telemetry_server.store can share one set of statements.
-
-CREATE TABLE IF NOT EXISTS installs (
-    install_id     TEXT PRIMARY KEY,
-    first_seen     TEXT    NOT NULL,
-    last_seen      TEXT    NOT NULL,
-    level          TEXT    NOT NULL,
-    version        TEXT,
-    branch         TEXT,
-    os             TEXT,
-    arch           TEXT,
-    python         TEXT,
-    in_docker      INTEGER,
-    has_hb_api     INTEGER,
-    has_gateway    INTEGER,
-    has_web        INTEGER,
-    user_count     INTEGER,
-    server_count   INTEGER,
-    agent_count    INTEGER,
-    llm_providers  TEXT,
-    dropped_total  INTEGER NOT NULL DEFAULT 0
-);
-
-CREATE TABLE IF NOT EXISTS events (
-    id          TEXT NOT NULL,
-    install_id  TEXT NOT NULL,
-    ts          TEXT NOT NULL,
-    received_at TEXT NOT NULL,
-    name        TEXT NOT NULL,
-    props       TEXT NOT NULL DEFAULT '{}',
-    PRIMARY KEY (id, ts)
-);
-
-CREATE INDEX IF NOT EXISTS events_name_ts ON events (name, ts);
-CREATE INDEX IF NOT EXISTS events_install_ts ON events (install_id, ts);
-
-CREATE TABLE IF NOT EXISTS install_days (
-    install_id TEXT    NOT NULL,
-    day        TEXT    NOT NULL,
-    events     INTEGER NOT NULL DEFAULT 0,
-    errors     INTEGER NOT NULL DEFAULT 0,
-    version    TEXT,
-    PRIMARY KEY (install_id, day)
-);
-
-CREATE TABLE IF NOT EXISTS daily_metrics (
-    day    TEXT NOT NULL,
-    metric TEXT NOT NULL,
-    dim    TEXT NOT NULL DEFAULT '',
-    value  REAL NOT NULL,
-    PRIMARY KEY (day, metric, dim)
-);
diff --git a/telemetry_server/queries/adoption.sql b/telemetry_server/queries/adoption.sql
deleted file mode 100644
index d1fa5227..00000000
--- a/telemetry_server/queries/adoption.sql
+++ /dev/null
@@ -1,19 +0,0 @@
--- Q1: How many installs are alive, on what, and how fast do upgrades spread?
---
--- Reads `daily_metrics` only, so it stays correct after raw events expire and
--- costs a few thousand rows rather than a full scan. Every query in this
--- directory is plain ANSI: it runs against the collector's Postgres and against
--- the SQLite the test suite seeds, and it is readable without Grafana.
-
-SELECT day, metric, dim, value
-FROM daily_metrics
-WHERE metric IN ('dau', 'wau', 'mau')
-ORDER BY day, metric;
-
--- Version and OS mix, snapshotted once per rollup. The series of snapshots is
--- what answers "how long does an upgrade take to propagate" — a version's share
--- decaying across consecutive days is the propagation curve.
-SELECT day, metric, dim AS value_of, value
-FROM daily_metrics
-WHERE metric IN ('version_share', 'os_share', 'provider_share')
-ORDER BY day, metric, value DESC;
diff --git a/telemetry_server/queries/agent_economics.sql b/telemetry_server/queries/agent_economics.sql
deleted file mode 100644
index dbea2432..00000000
--- a/telemetry_server/queries/agent_economics.sql
+++ /dev/null
@@ -1,27 +0,0 @@
--- Q5: How are agents actually used, and what does a turn cost?
-
-SELECT day, metric, dim AS value_of, value
-FROM daily_metrics
-WHERE metric IN ('agent_provider', 'model_rank', 'agent_kind')
-ORDER BY metric, value DESC;
-
--- Outcome mix. A rising `aborted` share is a usability signal; a rising `error`
--- share is a reliability one.
-SELECT dim AS outcome, value AS turns
-FROM daily_metrics
-WHERE metric = 'agent_outcome'
-ORDER BY value DESC;
-
--- What a turn costs, and what a routine costs.
-SELECT day, metric, value
-FROM daily_metrics
-WHERE metric IN ('agent_tool_calls_avg', 'agent_duration_ms_avg',
-                 'routine_duration_ms_avg')
-ORDER BY day, metric;
-
--- Dry run versus live, and how often a confirmation is actually granted. A deny
--- or timeout rate that climbs means the agent is asking for the wrong things.
-SELECT metric, dim AS value_of, value
-FROM daily_metrics
-WHERE metric IN ('strategy_mode', 'confirmation_decision')
-ORDER BY metric, value DESC;
diff --git a/telemetry_server/queries/feature_usage.sql b/telemetry_server/queries/feature_usage.sql
deleted file mode 100644
index 48b99c47..00000000
--- a/telemetry_server/queries/feature_usage.sql
+++ /dev/null
@@ -1,25 +0,0 @@
--- Q3: What is actually used, and what are we maintaining for nobody?
---
--- Note what is absent: nothing groups by `user_hash`. It is salted per install
--- (FEAT-023), so it can be counted inside one install but is meaningless
--- across installs, and a query that grouped by it globally would be inventing
--- a cross-install identity the client deliberately refused to provide.
-
-SELECT day, dim AS event_name, value AS events
-FROM daily_metrics
-WHERE metric = 'event_rank'
-ORDER BY day, value DESC;
-
--- The key dimension behind each surface: which commands, which modules, which
--- routines, which connectors.
-SELECT day, metric, dim AS name, value AS uses
-FROM daily_metrics
-WHERE metric IN ('command_rank', 'action_rank', 'routine_rank', 'trade_rank')
-ORDER BY metric, value DESC;
-
--- The activation funnel. `feature_first_use` fires once per install, ever, so
--- this counts installs that ever reached a feature, not how often they use it.
-SELECT dim AS feature, value AS installs_activated
-FROM daily_metrics
-WHERE metric = 'activation'
-ORDER BY value DESC;
diff --git a/telemetry_server/queries/reliability.sql b/telemetry_server/queries/reliability.sql
deleted file mode 100644
index b263780d..00000000
--- a/telemetry_server/queries/reliability.sql
+++ /dev/null
@@ -1,30 +0,0 @@
--- Q4: What is broken out there?
---
--- `error_rate` is errors per event per install-day, so a single install in a
--- crash loop shows up as a bad day rather than drowning the fleet average.
-
-SELECT day, value AS errors_per_event
-FROM daily_metrics
-WHERE metric = 'error_rate'
-ORDER BY day;
-
--- Failure groups, keyed by exception type and the hash of the message. The
--- message itself is never transmitted (FEAT-023) — grouping works off the hash.
-SELECT dim AS exc_type_and_sig, value AS occurrences
-FROM daily_metrics
-WHERE metric = 'error_group'
-ORDER BY value DESC;
-
--- Which upstream is failing: the Hummingbot API, Gateway, an LLM, or Telegram.
-SELECT dim AS service, value AS failures
-FROM daily_metrics
-WHERE metric = 'upstream_error_rank'
-ORDER BY value DESC;
-
--- Client-side rate limiting must never look like a quiet week. `dropped` is the
--- emitter's own confession, and charting it next to volume is what keeps a
--- taxonomy change or an error flood visible instead of silent.
-SELECT day, metric, value
-FROM daily_metrics
-WHERE metric IN ('dropped_total', 'dropped_rate')
-ORDER BY day;
diff --git a/telemetry_server/queries/retention.sql b/telemetry_server/queries/retention.sql
deleted file mode 100644
index f1dee5bb..00000000
--- a/telemetry_server/queries/retention.sql
+++ /dev/null
@@ -1,21 +0,0 @@
--- Q2: Do people stay? D1 / D7 / D30 by first-seen cohort.
---
--- `day` here is the cohort's first-seen day, not the day the metric describes.
--- Cohorts are derived from `install_days`, which is written on the ingest path
--- and never expires, so retention survives the 90-day raw retention window.
-
-SELECT
-    cohort.day                                   AS cohort_day,
-    cohort.value                                 AS installs,
-    d1.value                                     AS retained_d1,
-    d7.value                                     AS retained_d7,
-    d30.value                                    AS retained_d30
-FROM daily_metrics AS cohort
-LEFT JOIN daily_metrics AS d1
-       ON d1.day = cohort.day AND d1.metric = 'retention_d1'
-LEFT JOIN daily_metrics AS d7
-       ON d7.day = cohort.day AND d7.metric = 'retention_d7'
-LEFT JOIN daily_metrics AS d30
-       ON d30.day = cohort.day AND d30.metric = 'retention_d30'
-WHERE cohort.metric = 'cohort_size'
-ORDER BY cohort.day;
diff --git a/telemetry_server/rollup.py b/telemetry_server/rollup.py
deleted file mode 100644
index 26dcb3f5..00000000
--- a/telemetry_server/rollup.py
+++ /dev/null
@@ -1,339 +0,0 @@
-"""The nightly job: small permanent tables, and partition housekeeping.
-
-Retention and DAU computed over raw events mean a full scan per dashboard
-panel, and raw events expire at :func:`telemetry_server.config.retention_days`
-anyway. So every question is answered from ``daily_metrics``, which this module
-writes and which is never deleted. Backfilling a rollup after dropping the raw
-data it came from is impossible, which is why this exists from day one rather
-than "later".
-
-The aggregation is deliberately split: SQL does the grouping (cheap, indexed,
-and identical in both dialects), Python does the date arithmetic and the
-cohort matching. Date arithmetic is where the two dialects diverge most, and at
-a few hundred installs the rows involved fit in a dict comfortably. The result
-is one rollup that runs unchanged against Postgres and SQLite, so the numbers
-the tests check are the numbers production computes.
-
-Partition maintenance is the one Postgres-only part, and it is a no-op
-elsewhere. The table names it builds come from dates this module computed; no
-payload value ever reaches a formatted statement.
-"""
-
-from __future__ import annotations
-
-import json
-import logging
-from collections import defaultdict
-from datetime import date, datetime, timedelta, timezone
-
-from telemetry_server import config
-from telemetry_server.store import PostgresStore, Store
-
-log = logging.getLogger(__name__)
-
-TOP_N = 25
-
-
-def _as_date(value: object) -> date | None:
-    if isinstance(value, datetime):
-        return value.date()
-    if isinstance(value, date):
-        return value
-    if isinstance(value, str):
-        try:
-            return date.fromisoformat(value[:10])
-        except ValueError:
-            return None
-    return None
-
-
-async def run(store: Store, today: date | None = None) -> int:
-    """Recompute every metric. Returns how many rows were written."""
-    today = today or datetime.now(timezone.utc).date()
-    written = 0
-    written += await _activity(store)
-    written += await _retention(store)
-    written += await _shares(store, today)
-    written += await _ranks(store)
-    written += await _reliability(store, today)
-    written += await _agents(store, today)
-    await maintain_partitions(store, today)
-    return written
-
-
-async def _activity(store: Store) -> int:
-    """DAU from ``install_days``; WAU and MAU by rolling the same rows."""
-    rows = await store.fetch("SELECT install_id, day FROM install_days")
-    seen: dict[date, set] = defaultdict(set)
-    for install_id, day in rows:
-        parsed = _as_date(day)
-        if parsed is not None:
-            seen[parsed].add(install_id)
-    if not seen:
-        return 0
-
-    written = 0
-    for day in sorted(seen):
-        for metric, window in (("dau", 1), ("wau", 7), ("mau", 30)):
-            active: set = set()
-            for offset in range(window):
-                active |= seen.get(day - timedelta(days=offset), set())
-            await store.put_metric(day, metric, "", len(active))
-            written += 1
-    return written
-
-
-async def _retention(store: Store) -> int:
-    """D1 / D7 / D30 from first-seen cohorts.
-
-    The cohort day is ``MIN(day)`` in ``install_days`` rather than
-    ``installs.first_seen``, so retention keeps working for an install whose
-    row was upserted long after its first event.
-    """
-    rows = await store.fetch("SELECT install_id, day FROM install_days")
-    days: dict[object, set] = defaultdict(set)
-    for install_id, day in rows:
-        parsed = _as_date(day)
-        if parsed is not None:
-            days[install_id].add(parsed)
-    if not days:
-        return 0
-
-    cohorts: dict[date, list] = defaultdict(list)
-    for install_id, active in days.items():
-        cohorts[min(active)].append(install_id)
-
-    written = 0
-    for cohort_day, members in sorted(cohorts.items()):
-        await store.put_metric(cohort_day, "cohort_size", "", len(members))
-        written += 1
-        for horizon in (1, 7, 30):
-            target = cohort_day + timedelta(days=horizon)
-            retained = sum(1 for m in members if target in days[m])
-            await store.put_metric(cohort_day, f"retention_d{horizon}", "", retained)
-            written += 1
-    return written
-
-
-async def _shares(store: Store, today: date) -> int:
-    """Version, OS and LLM-provider mix, as of the run.
-
-    These describe the fleet now rather than a past day, so they are stamped
-    with the run date: a series of daily snapshots is exactly how "how long does
-    an upgrade take to propagate" gets answered.
-    """
-    written = 0
-    for metric, column in (("version_share", "version"), ("os_share", "os")):
-        rows = await store.fetch(
-            f"SELECT {column}, COUNT(*) FROM installs GROUP BY {column}"
-        )
-        for value, count in rows:
-            await store.put_metric(today, metric, str(value or "unknown"), count)
-            written += 1
-
-    counts: dict[str, int] = defaultdict(int)
-    for (raw,) in await store.fetch("SELECT llm_providers FROM installs"):
-        for provider in _providers(raw):
-            counts[provider] += 1
-    for provider, count in counts.items():
-        await store.put_metric(today, "provider_share", provider, count)
-        written += 1
-    return written
-
-
-def _providers(raw: object) -> list[str]:
-    """One column, two shapes: a Postgres ``text[]`` or a SQLite JSON string."""
-    if isinstance(raw, (list, tuple)):
-        return [str(p) for p in raw]
-    if isinstance(raw, str):
-        try:
-            parsed = json.loads(raw)
-        except ValueError:
-            return []
-        return [str(p) for p in parsed] if isinstance(parsed, list) else []
-    return []
-
-
-#: The one property of each event that carries the signal worth ranking.
-RANK_DIMS = {
-    "command": ("command_rank", "name"),
-    "action": ("action_rank", "module"),
-    "routine_run": ("routine_rank", "routine"),
-    "agent_turn": ("model_rank", "model"),
-    "feature_first_use": ("activation", "feature"),
-    "trade": ("trade_rank", "connector"),
-}
-
-
-async def _ranks(store: Store) -> int:
-    """What is actually used: event volume per day, then the key dimensions."""
-    written = 0
-    rows = await store.fetch(
-        f"SELECT {store.DAY} AS d, name, COUNT(*) FROM events GROUP BY d, name"
-    )
-    for day, name, count in rows:
-        parsed = _as_date(day)
-        if parsed is not None:
-            await store.put_metric(parsed, "event_rank", str(name), count)
-            written += 1
-
-    for event_name, (metric, prop) in RANK_DIMS.items():
-        dim = store.json_get("props", prop)
-        rows = await store.fetch(
-            f"SELECT {dim} AS v, COUNT(*) AS n FROM events WHERE name = $1 "
-            f"GROUP BY v ORDER BY n DESC",
-            event_name,
-        )
-        today = datetime.now(timezone.utc).date()
-        for value, count in rows[:TOP_N]:
-            if value is None:
-                continue
-            await store.put_metric(today, metric, str(value), count)
-            written += 1
-    return written
-
-
-async def _reliability(store: Store, today: date) -> int:
-    """Error rate per install-day, the top failure groups, and honest drops."""
-    written = 0
-    rows = await store.fetch(
-        "SELECT day, SUM(events), SUM(errors) FROM install_days GROUP BY day"
-    )
-    for day, events, errors in rows:
-        parsed = _as_date(day)
-        if parsed is None or not events:
-            continue
-        await store.put_metric(parsed, "error_rate", "", (errors or 0) / events)
-        written += 1
-
-    exc = store.json_get("props", "exc_type")
-    sig = store.json_get("props", "sig")
-    groups = await store.fetch(
-        f"SELECT {exc} AS e, {sig} AS s, COUNT(*) AS n FROM events "
-        f"WHERE name = $1 GROUP BY e, s ORDER BY n DESC",
-        "error",
-    )
-    for exc_type, signature, count in groups[:TOP_N]:
-        await store.put_metric(
-            today,
-            "error_group",
-            f"{exc_type or 'unknown'}:{signature or 'unknown'}",
-            count,
-        )
-        written += 1
-
-    service = store.json_get("props", "service")
-    upstream = await store.fetch(
-        f"SELECT {service} AS s, COUNT(*) AS n FROM events WHERE name = $1 GROUP BY s",
-        "upstream_error",
-    )
-    for name, count in upstream:
-        await store.put_metric(
-            today, "upstream_error_rank", str(name or "other"), count
-        )
-        written += 1
-
-    # Client-side rate limiting must never masquerade as "things got quieter",
-    # so the confession the envelope carries is charted next to the volume.
-    (dropped,) = (await store.fetch("SELECT SUM(dropped_total) FROM installs"))[0]
-    (total,) = (await store.fetch("SELECT COUNT(*) FROM events"))[0]
-    await store.put_metric(today, "dropped_total", "", dropped or 0)
-    await store.put_metric(
-        today,
-        "dropped_rate",
-        "",
-        (dropped or 0) / (total + (dropped or 0)) if total else 0,
-    )
-    return written + 2
-
-
-#: ``(event name, property, metric)`` triples whose distribution answers "how
-#: are agents used" — provider and model mix, dry-run versus live, and how
-#: often a confirmation is actually granted.
-AGENT_DIMS = (
-    ("agent_turn", "provider", "agent_provider"),
-    ("agent_turn", "outcome", "agent_outcome"),
-    ("agent_turn", "kind", "agent_kind"),
-    ("strategy_run", "mode", "strategy_mode"),
-    ("confirmation", "decision", "confirmation_decision"),
-)
-
-#: Averages worth a number rather than a distribution.
-AGENT_AVERAGES = (
-    ("agent_turn", "tool_calls", "agent_tool_calls_avg"),
-    ("agent_turn", "duration_ms", "agent_duration_ms_avg"),
-    ("routine_run", "duration_ms", "routine_duration_ms_avg"),
-)
-
-
-async def _agents(store: Store, today: date) -> int:
-    """Agent economics: the mix, the cost per turn, and the trust decisions."""
-    written = 0
-    for event_name, prop, metric in AGENT_DIMS:
-        dim = store.json_get("props", prop)
-        rows = await store.fetch(
-            f"SELECT {dim} AS v, COUNT(*) FROM events WHERE name = $1 GROUP BY v",
-            event_name,
-        )
-        for value, count in rows:
-            await store.put_metric(today, metric, str(value or "unknown"), count)
-            written += 1
-
-    for event_name, prop, metric in AGENT_AVERAGES:
-        column = store.json_num("props", prop)
-        rows = await store.fetch(
-            f"SELECT AVG({column}) FROM events WHERE name = $1", event_name
-        )
-        average = rows[0][0] if rows else None
-        if average is not None:
-            await store.put_metric(today, metric, "", float(average))
-            written += 1
-    return written
-
-
-def _month_start(day: date) -> date:
-    return day.replace(day=1)
-
-
-def _next_month(day: date) -> date:
-    return (day.replace(day=28) + timedelta(days=4)).replace(day=1)
-
-
-async def maintain_partitions(store: Store, today: date) -> list[str]:
-    """Create next month's partition, drop what has aged out.
-
-    Returns the partition names it touched, which is what the tests assert on.
-    Postgres only: SQLite has no partitioning, and at the volume SQLite is used
-    for, ``DELETE`` is the right answer anyway.
-    """
-    if not isinstance(store, PostgresStore):
-        cutoff = today - timedelta(days=config.retention_days())
-        await store.execute("DELETE FROM events WHERE received_at < $1", cutoff)
-        return []
-
-    touched = []
-    current = _month_start(today)
-    for start in (current, _next_month(current)):
-        end = _next_month(start)
-        name = f"events_{start:%Y_%m}"
-        await store.execute(
-            f"CREATE TABLE IF NOT EXISTS {name} PARTITION OF events "
-            f"FOR VALUES FROM ('{start:%Y-%m-%d}') TO ('{end:%Y-%m-%d}')"
-        )
-        touched.append(name)
-
-    cutoff = _month_start(today - timedelta(days=config.retention_days()))
-    existing = await store.fetch(
-        "SELECT c.relname FROM pg_class c "
-        "JOIN pg_inherits i ON i.inhrelid = c.oid "
-        "JOIN pg_class p ON p.oid = i.inhparent WHERE p.relname = 'events'"
-    )
-    for (name,) in existing:
-        try:
-            start = datetime.strptime(name.removeprefix("events_"), "%Y_%m").date()
-        except ValueError:
-            continue
-        if start < cutoff:
-            await store.execute(f"DROP TABLE IF EXISTS {name}")
-            touched.append(f"-{name}")
-    return touched
diff --git a/telemetry_server/store.py b/telemetry_server/store.py
deleted file mode 100644
index 5efd8b2c..00000000
--- a/telemetry_server/store.py
+++ /dev/null
@@ -1,379 +0,0 @@
-"""Persistence for the collector — one interface, two backends.
-
-Production is Postgres (FEAT-024 chose it: known stack, ``ON CONFLICT`` gives
-idempotency in one line, monthly partitions make retention a ``DROP TABLE``).
-But a collector whose tests need a database daemon is a collector whose tests do
-not run, so the same interface also speaks SQLite, which is what the suite in
-``tests/test_telemetry_server.py`` drives. The two backends share their SQL:
-every statement is written once with ``$n`` placeholders and a ``{jsonb}`` cast
-hole, and each backend adapts only those two things. Sharing the statements is
-the point — a second copy would drift exactly the way a second copy of the event
-taxonomy would.
-
-Everything an envelope contributes is parameterised. No value from a payload is
-ever formatted into a statement; the only string interpolation in this file is
-the partition maintenance in :mod:`telemetry_server.rollup`, which builds names
-from dates it computed itself.
-"""
-
-from __future__ import annotations
-
-import json
-import re
-import sqlite3
-import threading
-from datetime import date, datetime, timezone
-from pathlib import Path
-
-MIGRATIONS = Path(__file__).parent / "migrations"
-
-_PLACEHOLDER = re.compile(r"\$(\d+)")
-
-
-# ── The shared statements ────────────────────────────────────────────────
-# `$2` appears twice in the install upsert (first_seen and last_seen start
-# equal); the SQLite adapter re-orders arguments by order of appearance, so a
-# repeated placeholder is safe in both dialects.
-
-UPSERT_INSTALL = """
-INSERT INTO installs (
-    install_id, first_seen, last_seen, level, version, branch,
-    os, arch, python, in_docker, has_hb_api, has_gateway, has_web,
-    user_count, server_count, agent_count, llm_providers, dropped_total)
-VALUES ($1, $2, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12,
-        $13, $14, $15, $16, $17)
-ON CONFLICT (install_id) DO UPDATE SET
-    last_seen     = excluded.last_seen,
-    level         = excluded.level,
-    version       = excluded.version,
-    branch        = excluded.branch,
-    os            = excluded.os,
-    arch          = excluded.arch,
-    python        = excluded.python,
-    in_docker     = excluded.in_docker,
-    has_hb_api    = excluded.has_hb_api,
-    has_gateway   = excluded.has_gateway,
-    has_web       = excluded.has_web,
-    user_count    = excluded.user_count,
-    server_count  = excluded.server_count,
-    agent_count   = excluded.agent_count,
-    llm_providers = excluded.llm_providers,
-    dropped_total = installs.dropped_total + excluded.dropped_total
-"""
-# `first_seen` is deliberately absent from the DO UPDATE list: first contact is
-# a fact about the past and a later envelope has no business moving it.
-
-INSERT_EVENT = """
-INSERT INTO events (id, install_id, ts, received_at, name, props)
-VALUES ($1, $2, $3, $4, $5, $6{jsonb})
-ON CONFLICT DO NOTHING
-"""
-
-UPSERT_INSTALL_DAY = """
-INSERT INTO install_days (install_id, day, events, errors, version)
-VALUES ($1, $2, $3, $4, $5)
-ON CONFLICT (install_id, day) DO UPDATE SET
-    events  = install_days.events + excluded.events,
-    errors  = install_days.errors + excluded.errors,
-    version = excluded.version
-"""
-
-UPSERT_METRIC = """
-INSERT INTO daily_metrics (day, metric, dim, value)
-VALUES ($1, $2, $3, $4)
-ON CONFLICT (day, metric, dim) DO UPDATE SET value = excluded.value
-"""
-
-
-def _to_qmark(sql: str, args: tuple) -> tuple[str, list]:
-    """Rewrite ``$n`` placeholders as ``?`` and re-order args to match.
-
-    Re-ordering by order of appearance is what makes a repeated ``$n`` legal in
-    the shared statements above.
-    """
-    ordered: list = []
-
-    def swap(match: re.Match) -> str:
-        ordered.append(args[int(match.group(1)) - 1])
-        return "?"
-
-    return _PLACEHOLDER.sub(swap, sql), ordered
-
-
-class Store:
-    """What ingest and rollup are allowed to ask of a database.
-
-    Two SQL fragments differ between the dialects and cannot be parameterised —
-    casting a timestamp to a day, and reading one key out of a JSON column.
-    Subclasses expose them as :attr:`DAY` / :meth:`json_get` and
-    :mod:`telemetry_server.rollup` formats them into its aggregates. Every value
-    that reaches those aggregates is still a bound parameter; what is
-    interpolated is a constant chosen in this file and a key name chosen in
-    ``rollup.py``, never anything an envelope carried.
-    """
-
-    #: SQL expression turning ``events.received_at`` into a day.
-    DAY = "received_at::date"
-
-    def json_get(self, column: str, key: str) -> str:
-        """SQL reading one top-level key of a JSON column as text."""
-        return f"{column}->>'{key}'"
-
-    def json_num(self, column: str, key: str) -> str:
-        """SQL reading one top-level key of a JSON column as a number."""
-        return f"({column}->>'{key}')::numeric"
-
-    async def migrate(self) -> None:
-        raise NotImplementedError
-
-    async def ping(self) -> bool:
-        raise NotImplementedError
-
-    async def close(self) -> None:
-        raise NotImplementedError
-
-    async def record(
-        self, install: dict, events: list[dict], dropped: int
-    ) -> tuple[int, int]:
-        """Persist one validated envelope in a single transaction.
-
-        Returns ``(stored, duplicates)``. ``install_days`` is incremented from
-        *newly inserted* rows only, so the client's retry-after-timeout path
-        cannot inflate a metric even though it legitimately re-sends the batch.
-        """
-        raise NotImplementedError
-
-    async def fetch(self, sql: str, *args) -> list[tuple]:
-        raise NotImplementedError
-
-    async def execute(self, sql: str, *args) -> None:
-        raise NotImplementedError
-
-    async def put_metric(self, day: date, metric: str, dim: str, value: float) -> None:
-        await self.execute(UPSERT_METRIC, day, metric, dim, float(value))
-
-
-def _day_buckets(events: list[dict]) -> dict:
-    """Group inserted events into ``(day) -> (count, errors)``."""
-    buckets: dict[date, list[int]] = {}
-    for event in events:
-        day = event["ts"].astimezone(timezone.utc).date()
-        slot = buckets.setdefault(day, [0, 0])
-        slot[0] += 1
-        if event["name"] in ("error", "upstream_error"):
-            slot[1] += 1
-    return buckets
-
-
-class SqliteStore(Store):
-    """The test and small-deployment backend.
-
-    ``sqlite3`` is synchronous, so every call holds a :class:`threading.Lock`
-    for the microseconds it takes — a thread lock rather than an asyncio one
-    precisely because there is no ``await`` inside the critical section, and
-    because an :class:`asyncio.Lock` binds itself to the first event loop that
-    touches it, which a store built in one loop and served from another would
-    trip over immediately.
-    """
-
-    DAY = "substr(received_at, 1, 10)"
-
-    def json_get(self, column: str, key: str) -> str:
-        return f"json_extract({column}, '$.{key}')"
-
-    def json_num(self, column: str, key: str) -> str:
-        # json_extract already yields SQLite's own numeric affinity for a JSON
-        # number, so unlike Postgres there is nothing to cast.
-        return f"json_extract({column}, '$.{key}')"
-
-    def __init__(self, path: str) -> None:
-        self._path = path
-        self._lock = threading.Lock()
-        self._conn = sqlite3.connect(path, check_same_thread=False)
-        self._conn.execute("PRAGMA journal_mode=WAL")
-        self._conn.execute("PRAGMA foreign_keys=ON")
-
-    def _run(self, sql: str, args: tuple) -> sqlite3.Cursor:
-        # Only the shared INSERT carries the cast hole; leave every other
-        # statement's text alone so a stray brace in a rollup aggregate can
-        # never be mistaken for a format field.
-        if "{jsonb}" in sql:
-            sql = sql.format(jsonb="")
-        statement, ordered = _to_qmark(sql, _as_text_dates(args))
-        return self._conn.execute(statement, ordered)
-
-    async def migrate(self) -> None:
-        with self._lock:
-            self._conn.executescript(
-                (MIGRATIONS / "001_init.sqlite.sql").read_text(encoding="utf-8")
-            )
-            self._conn.commit()
-
-    async def ping(self) -> bool:
-        with self._lock:
-            self._conn.execute("SELECT 1").fetchone()
-        return True
-
-    async def close(self) -> None:
-        with self._lock:
-            self._conn.close()
-
-    async def record(
-        self, install: dict, events: list[dict], dropped: int
-    ) -> tuple[int, int]:
-        with self._lock:
-            try:
-                self._run(UPSERT_INSTALL, _install_args(install, dropped, json.dumps))
-                inserted: list[dict] = []
-                for event in events:
-                    cursor = self._run(
-                        INSERT_EVENT, _event_args(event, str, json.dumps)
-                    )
-                    if cursor.rowcount:
-                        inserted.append(event)
-                for day, (count, errors) in _day_buckets(inserted).items():
-                    self._run(
-                        UPSERT_INSTALL_DAY,
-                        (
-                            install["install_id"],
-                            day.isoformat(),
-                            count,
-                            errors,
-                            install["version"],
-                        ),
-                    )
-                self._conn.commit()
-            except Exception:
-                self._conn.rollback()
-                raise
-        return len(inserted), len(events) - len(inserted)
-
-    async def fetch(self, sql: str, *args) -> list[tuple]:
-        with self._lock:
-            return list(self._run(sql, args).fetchall())
-
-    async def execute(self, sql: str, *args) -> None:
-        with self._lock:
-            self._run(sql, args)
-            self._conn.commit()
-
-
-def _as_text_dates(args: tuple) -> tuple:
-    """SQLite has no date or timestamp type, and its implicit datetime adapter is
-    deprecated. Dates and timestamps go in as ISO-8601 text, matching the DDL and
-    sorting correctly."""
-    return tuple(a.isoformat() if isinstance(a, (date, datetime)) else a for a in args)
-
-
-class PostgresStore(Store):
-    """The production backend. ``asyncpg`` is imported here and nowhere else."""
-
-    def __init__(self, dsn: str) -> None:
-        self._dsn = dsn
-        self._pool = None
-
-    async def connect(self) -> None:
-        import asyncpg  # noqa: PLC0415 - behind the telemetry-server extra
-
-        self._pool = await asyncpg.create_pool(self._dsn, min_size=1, max_size=8)
-
-    async def migrate(self) -> None:
-        sql = (MIGRATIONS / "001_init.sql").read_text(encoding="utf-8")
-        async with self._pool.acquire() as conn:
-            await conn.execute(sql)
-
-    async def ping(self) -> bool:
-        async with self._pool.acquire() as conn:
-            await conn.fetchval("SELECT 1")
-        return True
-
-    async def close(self) -> None:
-        if self._pool is not None:
-            await self._pool.close()
-
-    async def record(
-        self, install: dict, events: list[dict], dropped: int
-    ) -> tuple[int, int]:
-        import uuid as _uuid
-
-        statement = INSERT_EVENT.format(jsonb="::jsonb")
-        async with self._pool.acquire() as conn:
-            async with conn.transaction():
-                await conn.execute(
-                    UPSERT_INSTALL, *_install_args(install, dropped, list)
-                )
-                inserted = []
-                for event in events:
-                    status = await conn.execute(
-                        statement, *_event_args(event, _uuid.UUID, json.dumps)
-                    )
-                    # asyncpg returns "INSERT 0 1", or "INSERT 0 0" when the
-                    # ON CONFLICT swallowed a retry.
-                    if status.rsplit(" ", 1)[-1] != "0":
-                        inserted.append(event)
-                for day, (count, errors) in _day_buckets(inserted).items():
-                    await conn.execute(
-                        UPSERT_INSTALL_DAY,
-                        _uuid.UUID(install["install_id"]),
-                        day,
-                        count,
-                        errors,
-                        install["version"],
-                    )
-        return len(inserted), len(events) - len(inserted)
-
-    async def fetch(self, sql: str, *args) -> list[tuple]:
-        async with self._pool.acquire() as conn:
-            return [tuple(r) for r in await conn.fetch(sql, *args)]
-
-    async def execute(self, sql: str, *args) -> None:
-        async with self._pool.acquire() as conn:
-            await conn.execute(sql, *args)
-
-
-def _install_args(install: dict, dropped: int, providers) -> tuple:
-    return (
-        install["install_id"],
-        install["received_at"],
-        install["level"],
-        install["version"],
-        install["branch"],
-        install["os"],
-        install["arch"],
-        install["python"],
-        install["in_docker"],
-        install["has_hb_api"],
-        install["has_gateway"],
-        install["has_web"],
-        install["user_count"],
-        install["server_count"],
-        install["agent_count"],
-        providers(install["llm_providers"]),
-        dropped,
-    )
-
-
-def _event_args(event: dict, ident, dump) -> tuple:
-    return (
-        ident(event["id"]),
-        ident(event["install_id"]),
-        event["ts"],
-        event["received_at"],
-        event["name"],
-        dump(event["props"]),
-    )
-
-
-async def open_store(dsn: str) -> Store:
-    """Build the backend the DSN asks for, migrated and ready.
-
-    Anything that is not a Postgres URL is a SQLite path, which is how the tests
-    and a single-box trial run get a collector without installing a daemon.
-    """
-    if dsn.startswith(("postgres://", "postgresql://")):
-        store: Store = PostgresStore(dsn)
-        await store.connect()
-    else:
-        store = SqliteStore(dsn.removeprefix("sqlite:///").removeprefix("sqlite://"))
-    await store.migrate()
-    return store
diff --git a/tests/test_collector_is_extracted.py b/tests/test_collector_is_extracted.py
new file mode 100644
index 00000000..c4cb9b32
--- /dev/null
+++ b/tests/test_collector_is_extracted.py
@@ -0,0 +1,36 @@
+"""The telemetry collector lives in its own repo (``condor-telemetry-server``).
+
+Condor only *emits* telemetry; it must never pull the collector's database
+driver into a bot install, and no Condor module may import the collector. These
+guard the FEAT-024 extraction so the coupling cannot silently creep back and
+Condor keeps running with the collector entirely absent.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parent.parent
+
+
+def test_asyncpg_is_never_a_condor_dependency():
+    """A bot that only emits telemetry has no use for a database driver."""
+    project = tomllib.loads((REPO / "pyproject.toml").read_text(encoding="utf-8"))[
+        "project"
+    ]
+    assert not any("asyncpg" in dep for dep in project.get("dependencies", []))
+    for group, deps in project.get("optional-dependencies", {}).items():
+        assert not any(
+            "asyncpg" in dep for dep in deps
+        ), f"asyncpg leaked into the {group!r} extra"
+
+
+def test_no_condor_module_imports_the_collector():
+    """The collector was extracted; nothing in the client tree may reach for it."""
+    offenders = [
+        path.relative_to(REPO).as_posix()
+        for path in (REPO / "condor").rglob("*.py")
+        if "telemetry_server" in path.read_text(encoding="utf-8")
+    ]
+    assert offenders == [], f"collector coupling crept back into: {offenders}"
diff --git a/tests/test_telemetry_server.py b/tests/test_telemetry_server.py
deleted file mode 100644
index 9031af93..00000000
--- a/tests/test_telemetry_server.py
+++ /dev/null
@@ -1,749 +0,0 @@
-"""The collector (FEAT-024) — the tests that make a public endpoint survivable.
-
-Three things are being proven here, in descending order of how much they matter.
-
-**The wire contract is the client's, not a hand-copy.** The first test builds
-its envelope by running the real emitter from ``condor/telemetry/`` and handing
-the result to ``context.envelope()`` — the same code path a live install uses.
-If FEAT-023 ever changes shape, this file fails rather than the collector
-silently dropping a field in production.
-
-**Untrusted input cannot do damage.** This endpoint is unauthenticated and
-public by design, so most of what follows is negative: an oversized body, an
-over-long batch, a rate-limited caller and a malformed envelope each have to be
-refused *without touching the database*, and no refusal may echo any part of
-the request back.
-
-**Idempotency is real.** The client retries after a timeout. If a retry could
-inflate a count, every adoption number the exercise exists to produce would be
-unreliable.
-
-The whole suite runs against SQLite in a ``tmp_path``. Nothing here binds a
-port, starts a container, or outlives the test.
-"""
-
-from __future__ import annotations
-
-import asyncio
-import json
-import re
-import tomllib
-import uuid
-from datetime import datetime, timedelta, timezone
-from pathlib import Path
-
-import pytest
-from starlette.testclient import TestClient
-
-from telemetry_server import ingest, rollup
-from telemetry_server.app import create_app
-from telemetry_server.store import open_store
-
-REPO = Path(__file__).resolve().parent.parent
-QUERIES = REPO / "telemetry_server" / "queries"
-
-
-# ── Harness ──────────────────────────────────────────────────────────────
-
-
-@pytest.fixture(autouse=True)
-def fresh_limits():
-    """The limiters are process-wide; a leftover bucket would leak between tests."""
-    ingest.by_ip.reset()
-    ingest.by_install.reset()
-    yield
-    ingest.by_ip.reset()
-    ingest.by_install.reset()
-
-
-@pytest.fixture
-def store(tmp_path):
-    store = asyncio.run(open_store(str(tmp_path / "telemetry.db")))
-    yield store
-    asyncio.run(store.close())
-
-
-@pytest.fixture
-def client(store):
-    with TestClient(create_app(store)) as client:
-        yield client
-
-
-class Spy:
-    """A store that refuses to be used, so "no database contact" is checkable."""
-
-    def __init__(self):
-        self.calls = 0
-
-    async def record(self, *args, **kwargs):
-        self.calls += 1
-        raise AssertionError("the database was reached for a request we refuse")
-
-    async def ping(self):
-        return True
-
-    async def close(self):
-        return None
-
-
-@pytest.fixture
-def spy_client():
-    spy = Spy()
-    with TestClient(create_app(spy)) as client:
-        yield client, spy
-
-
-def _event(name="command", props=None, ts=None, event_id=None):
-    return {
-        "id": event_id or uuid.uuid4().hex,
-        "ts": ts or datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
-        "name": name,
-        "props": (
-            {"name": "portfolio", "surface": "telegram"} if props is None else props
-        ),
-    }
-
-
-def _envelope(events=None, **overrides):
-    """The shape condor/telemetry/context.py actually puts on the wire."""
-    envelope = {
-        "schema": 1,
-        "install_id": uuid.uuid4().hex,
-        "level": "usage",
-        "sent_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
-        "app": {
-            "version": "54ad4dc",
-            "branch": "main",
-            "python": "3.12",
-            "os": "linux",
-            "arch": "arm64",
-            "in_docker": True,
-        },
-        "config": {
-            "has_web": True,
-            "has_gateway": False,
-            "has_hb_api": True,
-            "llm_providers": ["openai", "openrouter"],
-            "user_count": 3,
-            "server_count": 2,
-            "agent_count": 4,
-        },
-        "dropped": 0,
-        "events": [_event()] if events is None else events,
-    }
-    envelope.update(overrides)
-    return envelope
-
-
-def _rows(store, sql, *args):
-    return asyncio.run(store.fetch(sql, *args))
-
-
-# ── The contract is the client's ─────────────────────────────────────────
-
-
-def test_an_envelope_built_by_the_real_client_is_accepted_whole(
-    client, store, tmp_path, monkeypatch
-):
-    """The acceptance criterion that matters: a genuine FEAT-023 envelope lands.
-
-    Nothing here hand-writes the wire format. The events come out of the real
-    emitter and the envelope out of ``context.envelope``, so this test is the
-    thing that fails if emitter and collector ever drift apart.
-    """
-    import config_manager as cm_module
-    from condor.telemetry import consent, context, emitter
-
-    monkeypatch.chdir(tmp_path)
-    monkeypatch.setattr("utils.config.CONDOR_TELEMETRY", None, raising=False)
-    monkeypatch.setattr("utils.config.CONDOR_TELEMETRY_URL", None, raising=False)
-    monkeypatch.setattr(
-        "condor.agents.agent._DATA_ROOT", str(tmp_path / "data"), raising=False
-    )
-    cm_module.ConfigManager.reset_instance()
-    emitter.discard_buffer()
-    emitter.set_hosted(True)
-    consent.refresh()
-    try:
-        cm_module.get_config_manager()
-        consent.grant("usage")
-
-        emitter.emit("install")
-        emitter.emit("command", name="portfolio", surface="telegram", authorized=True)
-        emitter.emit("action", module="bots", verb="deploy", surface="web")
-        emitter.emit("trade", venue="cex", connector="binance", side="buy")
-        emitter.emit(
-            "agent_turn", kind="chat", provider="openai", model="gpt-5", tool_calls=3
-        )
-        emitter.emit("error", where="handlers.bots", exc_type="ValueError", sig="ab12")
-
-        events, dropped = emitter.drain()
-        envelope = context.envelope(events, dropped, consent.level())
-    finally:
-        cm_module.ConfigManager.reset_instance()
-        emitter.discard_buffer()
-        consent.refresh()
-
-    response = client.post("/v1/events", json=envelope)
-
-    assert response.status_code == 202
-    assert response.json() == {
-        "accepted": len(events),
-        "rejected": 0,
-        "duplicates": 0,
-    }
-
-    stored = _rows(store, "SELECT name FROM events ORDER BY name")
-    assert sorted(n for (n,) in stored) == sorted(e["name"] for e in events)
-
-    # The install context lands as columns, including the capability flags the
-    # client sends but the original design's table did not have.
-    (row,) = _rows(
-        store,
-        "SELECT level, version, branch, os, in_docker, has_hb_api, has_web, "
-        "user_count, llm_providers FROM installs",
-    )
-    assert row[0] == "usage"
-    assert row[1] == envelope["app"]["version"]
-    assert json.loads(row[8]) == envelope["config"]["llm_providers"]
-
-
-def test_the_taxonomy_has_exactly_one_definition_in_the_repo():
-    """``ingest`` validates against the emitter's own module, not a copy."""
-    source = (REPO / "telemetry_server" / "ingest.py").read_text(encoding="utf-8")
-    assert "from condor.telemetry import schema" in source
-
-    definitions = []
-    for path in REPO.rglob("*.py"):
-        if any(part in {".venv", "node_modules", "__pycache__"} for part in path.parts):
-            continue
-        if re.search(
-            r"^EVENTS(\s*:\s*[^=]+)?\s*=", path.read_text(encoding="utf-8"), re.M
-        ):
-            definitions.append(path.relative_to(REPO).as_posix())
-
-    assert definitions == ["condor/telemetry/schema.py"]
-
-
-# ── Idempotency and partial acceptance ───────────────────────────────────
-
-
-def test_the_same_envelope_twice_stores_one_copy(client, store):
-    """The client retries after a timeout; a retry must not inflate a metric."""
-    envelope = _envelope([_event(), _event(), _event()])
-
-    first = client.post("/v1/events", json=envelope)
-    second = client.post("/v1/events", json=envelope)
-
-    assert first.json()["accepted"] == 3
-    assert second.json() == {"accepted": 0, "rejected": 0, "duplicates": 3}
-
-    assert _rows(store, "SELECT COUNT(*) FROM events")[0][0] == 3
-    # install_days is incremented from newly inserted rows only, so the rollup
-    # tables cannot be inflated by a retry either.
-    assert _rows(store, "SELECT SUM(events) FROM install_days")[0][0] == 3
-
-
-def test_one_unknown_name_and_one_stray_prop_cost_two_rejections(client, store):
-    """Partial acceptance: a single client bug must not erase a good batch."""
-    envelope = _envelope(
-        [
-            _event(),
-            _event(name="a_command_from_a_newer_client"),
-            _event(props={"name": "bots", "surface": "web", "wallet": "0xdeadbeef"}),
-        ]
-    )
-
-    response = client.post("/v1/events", json=envelope)
-
-    assert response.status_code == 202
-    assert response.json()["rejected"] == 2
-    assert response.json()["accepted"] == 2
-
-    (props,) = _rows(store, "SELECT props FROM events WHERE name = $1", "command")[1]
-    assert "wallet" not in props
-    assert "0xdeadbeef" not in props
-
-
-def test_a_duplicate_id_inside_one_envelope_is_counted_once(client, store):
-    shared = uuid.uuid4().hex
-    envelope = _envelope([_event(event_id=shared), _event(event_id=shared)])
-
-    assert client.post("/v1/events", json=envelope).json() == {
-        "accepted": 1,
-        "rejected": 1,
-        "duplicates": 0,
-    }
-    assert _rows(store, "SELECT COUNT(*) FROM events")[0][0] == 1
-
-
-def test_a_clock_from_next_year_is_clamped_not_stored(client, store):
-    """Self-hosted clocks drift and occasionally lie. Believe them within 48h."""
-    future = (datetime.now(timezone.utc) + timedelta(days=365)).strftime(
-        "%Y-%m-%dT%H:%M:%SZ"
-    )
-    past = (datetime.now(timezone.utc) - timedelta(days=400)).strftime(
-        "%Y-%m-%dT%H:%M:%SZ"
-    )
-    client.post("/v1/events", json=_envelope([_event(ts=future), _event(ts=past)]))
-
-    stored = [
-        datetime.fromisoformat(ts) for (ts,) in _rows(store, "SELECT ts FROM events")
-    ]
-    now = datetime.now(timezone.utc)
-    for ts in stored:
-        assert abs(ts - now) <= ingest.CLOCK_SLACK + timedelta(minutes=1)
-
-
-# ── Untrusted input ──────────────────────────────────────────────────────
-
-
-def test_an_oversized_body_is_refused_without_a_query(spy_client):
-    client, spy = spy_client
-    body = b'{"schema":1,"pad":"' + b"a" * (ingest.MAX_BODY_BYTES + 1024) + b'"}'
-
-    response = client.post(
-        "/v1/events", content=body, headers={"content-type": "application/json"}
-    )
-
-    assert response.status_code == 413
-    assert response.json() == {"error": "body_too_large"}
-    assert spy.calls == 0
-
-
-def test_an_oversized_body_is_refused_even_without_a_content_length():
-    """Content-Length is the caller's claim, so the stream is counted as it arrives."""
-
-    class Chunked:
-        headers: dict = {}
-        client = None
-
-        async def stream(self):
-            for _ in range(4):
-                yield b"a" * (ingest.MAX_BODY_BYTES // 3)
-
-    with pytest.raises(ingest.Refused) as refusal:
-        asyncio.run(ingest.read_body(Chunked()))
-    assert refusal.value.reason == "body_too_large"
-
-
-def test_a_ten_thousand_event_envelope_is_refused_without_a_query(spy_client):
-    """Two caps guard this, and the outer one bites first.
-
-    Ten thousand events cannot fit inside a 1 MB body, so such an envelope is
-    refused while it is still bytes on a socket — a stronger guarantee than the
-    event-count cap. The count cap is what catches the envelope that *does* fit,
-    which is asserted separately below.
-    """
-    client, spy = spy_client
-
-    response = client.post(
-        "/v1/events", json=_envelope([_event() for _ in range(10_000)])
-    )
-
-    assert response.status_code == 413
-    assert response.json()["error"] in ("body_too_large", "too_many_events")
-    assert spy.calls == 0
-
-
-def test_more_events_than_the_cap_are_refused_without_a_query(spy_client):
-    client, spy = spy_client
-    oversized = [_event() for _ in range(ingest.MAX_EVENTS + 1)]
-
-    response = client.post("/v1/events", json=_envelope(oversized))
-
-    assert response.status_code == 413
-    assert response.json() == {"error": "too_many_events"}
-    assert spy.calls == 0
-
-
-@pytest.mark.parametrize(
-    "envelope, reason",
-    [
-        (
-            {
-                "schema": 99,
-                "install_id": uuid.uuid4().hex,
-                "level": "usage",
-                "events": [],
-            },
-            "unknown_schema",
-        ),
-        (
-            {"schema": 1, "install_id": "not-a-uuid", "level": "usage", "events": []},
-            "invalid_envelope",
-        ),
-        (
-            {
-                "schema": 1,
-                "install_id": uuid.uuid4().hex,
-                "level": "root",
-                "events": [],
-            },
-            "invalid_envelope",
-        ),
-        (
-            {
-                "schema": 1,
-                "install_id": uuid.uuid4().hex,
-                "level": "usage",
-                "events": {},
-            },
-            "invalid_envelope",
-        ),
-        ([1, 2, 3], "invalid_envelope"),
-    ],
-)
-def test_a_malformed_envelope_is_refused_without_a_query(spy_client, envelope, reason):
-    client, spy = spy_client
-
-    response = client.post("/v1/events", json=envelope)
-
-    assert response.status_code == 400
-    assert response.json() == {"error": reason}
-    assert spy.calls == 0
-
-
-def test_a_refusal_never_echoes_the_request(spy_client):
-    """No reflector, and no oracle for what the server did with a probe."""
-    marker = "canary-9f13ab-do-not-reflect"
-    client, _ = spy_client
-
-    responses = [
-        client.post("/v1/events", content=marker.encode()),
-        client.post("/v1/events", json={"schema": 1, "install_id": marker}),
-        client.post("/v1/events", json=_envelope(install_id=marker)),
-    ]
-
-    for response in responses:
-        assert response.status_code in (400, 413)
-        assert marker not in response.text
-        assert set(response.json()) == {"error"}
-
-
-def test_body_that_is_not_json_is_refused(spy_client):
-    client, spy = spy_client
-    response = client.post("/v1/events", content=b"{not json at all")
-    assert response.status_code == 400
-    assert response.json() == {"error": "invalid_json"}
-    assert spy.calls == 0
-
-
-def test_exceeding_the_ip_rate_limit_returns_429_without_a_query(spy_client):
-    """The limiter runs before the JSON parser, so a flood costs us nothing."""
-    client, spy = spy_client
-    for _ in range(ingest.RATE_PER_HOUR):
-        ingest.by_ip.allow("testclient")
-
-    response = client.post("/v1/events", json=_envelope())
-
-    assert response.status_code == 429
-    assert response.json() == {"error": "rate_limited"}
-    assert spy.calls == 0
-
-
-def test_a_flood_from_one_install_is_limited_even_across_addresses(spy_client):
-    """The per-install bucket is the one an attacker cannot rotate away from."""
-    client, spy = spy_client
-    install_id = str(uuid.uuid4())
-    for _ in range(ingest.RATE_PER_HOUR):
-        ingest.by_install.allow(install_id)
-
-    response = client.post("/v1/events", json=_envelope(install_id=install_id))
-
-    assert response.status_code == 429
-    assert spy.calls == 0
-
-
-def test_the_limiter_key_space_is_bounded(spy_client):
-    """An attacker-chosen key must not be a memory exhaustion primitive."""
-    limiter = ingest.RateLimiter(per_hour=60, max_keys=32)
-    for index in range(5_000):
-        limiter.allow(f"install-{index}")
-    assert len(limiter._buckets) <= 32
-
-
-def test_a_forwarded_header_is_ignored_unless_a_proxy_is_trusted(monkeypatch):
-    """Honouring X-Forwarded-For by default would be a one-header limit bypass."""
-
-    class Request:
-        headers = {"x-forwarded-for": "1.2.3.4"}
-
-        class client:
-            host = "10.0.0.1"
-
-    monkeypatch.delenv("TELEMETRY_TRUSTED_PROXY", raising=False)
-    assert ingest.client_ip(Request()) == "10.0.0.1"
-
-    monkeypatch.setenv("TELEMETRY_TRUSTED_PROXY", "true")
-    assert ingest.client_ip(Request()) == "1.2.3.4"
-
-
-def test_a_payload_cannot_reach_the_sql(client, store):
-    """Every value is a bound parameter; nothing is formatted into a statement."""
-    injection = "1'); DROP TABLE events; --"
-    envelope = _envelope()
-    envelope["app"]["version"] = injection
-    envelope["config"]["llm_providers"] = [injection]
-
-    assert client.post("/v1/events", json=envelope).status_code == 202
-
-    assert _rows(store, "SELECT COUNT(*) FROM events")[0][0] == 1
-    (version,) = _rows(store, "SELECT version FROM installs")[0]
-    assert "DROP TABLE" not in version
-
-
-def test_unknown_envelope_fields_are_dropped_not_stored(client, store):
-    envelope = _envelope()
-    envelope["app"]["hostname"] = "trading-box.local"
-    envelope["config"]["api_key"] = "sk-live-secret"
-    envelope["surprise"] = {"nested": "value"}
-
-    assert client.post("/v1/events", json=envelope).status_code == 202
-
-    dump = json.dumps(_rows(store, "SELECT * FROM installs"))
-    assert "trading-box" not in dump
-    assert "sk-live-secret" not in dump
-
-
-def test_absurd_counts_are_clamped(client, store):
-    envelope = _envelope()
-    envelope["config"]["user_count"] = 10**18
-    envelope["dropped"] = 10**18
-
-    client.post("/v1/events", json=envelope)
-
-    (users, dropped) = _rows(store, "SELECT user_count, dropped_total FROM installs")[0]
-    assert users == ingest.MAX_COUNT
-    assert dropped == ingest.MAX_DROPPED
-
-
-# ── Health ───────────────────────────────────────────────────────────────
-
-
-def test_health_reports_the_database(client):
-    assert client.get("/health").json() == {"status": "ok"}
-
-
-def test_health_degrades_when_the_database_is_gone():
-    class Broken:
-        async def ping(self):
-            raise RuntimeError("connection refused")
-
-        async def close(self):
-            return None
-
-    with TestClient(create_app(Broken())) as client:
-        response = client.get("/health")
-    assert response.status_code == 503
-    assert response.json() == {"status": "degraded"}
-
-
-# ── Rollups and queries ──────────────────────────────────────────────────
-
-
-def _seed_cohorts(store):
-    """Three installs with hand-checkable retention, written straight to the
-    rollup table so the arithmetic under test is the rollup's, not ingest's."""
-    base = datetime(2026, 7, 1, tzinfo=timezone.utc).date()
-    plan = {
-        "aaaaaaaa-0000-4000-8000-000000000001": [0, 1, 7],  # retained at D1 and D7
-        "aaaaaaaa-0000-4000-8000-000000000002": [0, 1],  # D1 only
-        "aaaaaaaa-0000-4000-8000-000000000003": [0],  # never came back
-    }
-    for install_id, offsets in plan.items():
-        for offset in offsets:
-            asyncio.run(
-                store.execute(
-                    "INSERT INTO install_days (install_id, day, events, errors, version)"
-                    " VALUES ($1, $2, $3, $4, $5)",
-                    install_id,
-                    base + timedelta(days=offset),
-                    10,
-                    2 if offset == 0 else 0,
-                    "54ad4dc",
-                )
-            )
-    return base
-
-
-def test_retention_is_computed_from_the_permanent_table(store):
-    base = _seed_cohorts(store)
-    asyncio.run(rollup.run(store, today=base + timedelta(days=40)))
-
-    def metric(name):
-        rows = _rows(
-            store,
-            "SELECT value FROM daily_metrics WHERE day = $1 AND metric = $2",
-            base.isoformat(),
-            name,
-        )
-        return rows[0][0] if rows else None
-
-    assert metric("cohort_size") == 3
-    assert metric("retention_d1") == 2
-    assert metric("retention_d7") == 1
-    assert metric("retention_d30") == 0
-    assert metric("dau") == 3
-    assert metric("error_rate") == pytest.approx(6 / 30)
-
-
-def test_retention_survives_the_loss_of_the_raw_events(store):
-    """install_days is written on the ingest path precisely so this holds."""
-    base = _seed_cohorts(store)
-    asyncio.run(rollup.run(store, today=base + timedelta(days=40)))
-    before = _rows(store, "SELECT COUNT(*) FROM daily_metrics")[0][0]
-
-    asyncio.run(store.execute("DELETE FROM events"))
-    asyncio.run(rollup.run(store, today=base + timedelta(days=40)))
-
-    assert _rows(store, "SELECT COUNT(*) FROM daily_metrics")[0][0] >= before - 5
-    assert (
-        _rows(
-            store,
-            "SELECT value FROM daily_metrics WHERE metric = $1 AND day = $2",
-            "retention_d7",
-            base.isoformat(),
-        )[0][0]
-        == 1
-    )
-
-
-def test_the_rollup_summarises_a_real_ingest(client, store):
-    client.post(
-        "/v1/events",
-        json=_envelope(
-            [
-                _event(),
-                _event(props={"name": "bots", "surface": "telegram"}),
-                _event(
-                    name="agent_turn",
-                    props={
-                        "kind": "chat",
-                        "provider": "openai",
-                        "model": "gpt-5",
-                        "tool_calls": 4,
-                        "outcome": "done",
-                    },
-                ),
-                _event(
-                    name="error",
-                    props={
-                        "where": "handlers.bots",
-                        "exc_type": "ValueError",
-                        "sig": "ab12",
-                    },
-                ),
-                _event(
-                    name="confirmation", props={"tool": "execute", "decision": "allow"}
-                ),
-            ]
-        ),
-    )
-    asyncio.run(rollup.run(store))
-
-    metrics = {
-        (metric, dim): value
-        for metric, dim, value in _rows(
-            store, "SELECT metric, dim, value FROM daily_metrics"
-        )
-    }
-    assert metrics[("event_rank", "command")] == 2
-    assert metrics[("command_rank", "bots")] == 1
-    assert metrics[("agent_provider", "openai")] == 1
-    assert metrics[("agent_tool_calls_avg", "")] == 4
-    assert metrics[("confirmation_decision", "allow")] == 1
-    assert metrics[("error_group", "ValueError:ab12")] == 1
-    assert metrics[("version_share", "54ad4dc")] == 1
-
-
-def _statements(path):
-    """Split a query file into runnable statements.
-
-    Comments come out first: they are prose, and prose contains semicolons.
-    """
-    body = "\n".join(
-        line
-        for line in path.read_text(encoding="utf-8").splitlines()
-        if not line.strip().startswith("--")
-    )
-    return [s.strip() for s in body.split(";") if s.strip()]
-
-
-def test_every_query_runs_and_answers_its_question(client, store):
-    base = _seed_cohorts(store)
-    client.post("/v1/events", json=_envelope())
-    asyncio.run(rollup.run(store, today=base + timedelta(days=40)))
-
-    results = {}
-    for path in sorted(QUERIES.glob("*.sql")):
-        results[path.name] = [_rows(store, sql) for sql in _statements(path)]
-
-    assert set(results) == {
-        "adoption.sql",
-        "agent_economics.sql",
-        "feature_usage.sql",
-        "reliability.sql",
-        "retention.sql",
-    }
-    # Each one has to return numbers, not merely parse.
-    assert any(row[1] == "dau" for row in results["adoption.sql"][0])
-    assert (base.isoformat(), 3, 2, 1, 0) in [
-        tuple(row) for row in results["retention.sql"][0]
-    ]
-    assert any(row[1] == "command" for row in results["feature_usage.sql"][0])
-    assert results["reliability.sql"][0]
-    assert results["agent_economics.sql"]
-
-
-def test_no_query_can_correlate_installs_through_user_hash():
-    """`user_hash` is salted per install, so a global GROUP BY on it would be
-    inventing a cross-install identity the client deliberately refused to give."""
-    for path in QUERIES.glob("*.sql"):
-        for sql in _statements(path):
-            assert "user_hash" not in sql
-
-
-def test_sqlite_retention_deletes_what_postgres_would_drop(store, monkeypatch):
-    monkeypatch.setenv("TELEMETRY_RETENTION_DAYS", "30")
-    old = datetime.now(timezone.utc) - timedelta(days=200)
-    asyncio.run(
-        store.execute(
-            "INSERT INTO events (id, install_id, ts, received_at, name, props)"
-            " VALUES ($1, $2, $3, $4, $5, $6)",
-            uuid.uuid4().hex,
-            uuid.uuid4().hex,
-            old,
-            old,
-            "heartbeat",
-            "{}",
-        )
-    )
-
-    assert (
-        asyncio.run(
-            rollup.maintain_partitions(store, datetime.now(timezone.utc).date())
-        )
-        == []
-    )
-    assert _rows(store, "SELECT COUNT(*) FROM events")[0][0] == 0
-
-
-def test_partition_names_run_a_month_ahead():
-    """The Postgres path builds names from dates it computed, never from input."""
-    assert rollup._next_month(rollup._month_start(datetime(2026, 12, 31).date())) == (
-        datetime(2027, 1, 1).date()
-    )
-
-
-# ── Packaging ────────────────────────────────────────────────────────────
-
-
-def test_asyncpg_is_an_extra_and_never_a_runtime_dependency():
-    """`uv sync` without the extra must not pull a database driver into a bot."""
-    manifest = tomllib.loads((REPO / "pyproject.toml").read_text(encoding="utf-8"))
-    project = manifest["project"]
-
-    assert not any("asyncpg" in dep for dep in project["dependencies"])
-    extras = project["optional-dependencies"]
-    assert any("asyncpg" in dep for dep in extras["telemetry-server"])

From 4f455e30ba0d4084b5ab1512fa646252a4ad5246 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Wed, 12 Aug 2026 01:11:10 +0300
Subject: [PATCH 020/116] (feat) add tools to create strataegies at agent level

---
 agents/condor/skills/agent_builder/SKILL.md   | 67 +++++--------------
 agents/delta_neutral_funding_agent/AGENT.md   |  2 +
 .../strategies/ema_trend_loop/strategy.md     | 11 +++
 agents/market_making_expert/AGENT.md          |  3 +
 agents/solana_dex_lp_expert/AGENT.md          |  3 +
 agents/xrpl_market_maker/AGENT.md             |  2 +
 6 files changed, 38 insertions(+), 50 deletions(-)

diff --git a/agents/condor/skills/agent_builder/SKILL.md b/agents/condor/skills/agent_builder/SKILL.md
index 7215d500..41800695 100644
--- a/agents/condor/skills/agent_builder/SKILL.md
+++ b/agents/condor/skills/agent_builder/SKILL.md
@@ -164,56 +164,23 @@ Only if the user wants the agent to act autonomously. The agent can already loop
 this step — `start_agent(strategy_id="<agent_slug>")` ticks a default playbook driven by
 its AGENT.md — but that default is deliberately generic. A **strategy** is the specific
 tick playbook the engine runs in a **session**, and it is what you want for anything that
-trades. Make clear the loop does NOT have to trade — define the tick task however the
-user wants:
-
-- read routine X's output and **decide whether to trade** (create/stop executors),
-- or just **send a report / notification**,
-- or watch a condition and act only when it's met,
-
-…running at a **frequency the user sets** (`frequency_sec`).
-
-If the loop creates executors, BEFORE writing the strategy fetch the schema for every
-executor type it will use — `manage_executors(executor_type="grid_strike")`, etc. — and
-embed the required fields/types directly into the instructions; the tick LLM has no other
-way to learn them. Same for any controller config it manages (`manage_controllers`).
-
-```
-manage_trading_agent(
-    action="create_strategy",
-    agent_slug="<agent_slug>",             # the agent must already exist
-    name="BRL MM",
-    description="…",
-    instructions="<tick system prompt>",
-    # agent_key omitted → inherits the owning agent's model; overridable at launch
-    config={"connector_name": "binance", "frequency_sec": 60,
-            "total_amount_quote": 100, "execution_mode": "loop"}
-)
-```
-
-Strategy instructions (the tick system prompt) MUST include: **Objective**; **Analysis**
-(which routine to call by name and how to read it); **Decision logic** (act / report /
-hold); and — only if it trades — an **Executor config** with the FULL schema (every
-required field, type, range, ordering rule), **Parameter inference** (how to derive
-prices/side/TP from routine output + market data), **Risk rules** (max position, position
-limits, stop behaviour), and **Error recovery** (on a failed create, re-fetch the schema,
-fix, retry once, journal it).
-
-**Dry run before live** (if it trades):
-```
-manage_trading_agent(action="start_agent", strategy_id="<agent_slug.strategy_slug>",
-    config={"execution_mode": "dry_run", "agent_key": "ollama:llama3.1",
-            "trading_context": "Trade BTC-USDT on binance_perpetual",
-            "frequency_sec": 60, "total_amount_quote": 100,
-            "risk_limits": {"max_position_size_quote": 200, "max_open_executors": 3}})
-```
-Review with `trading_agent_journal_read(agent_id=…, section="run:1")`: routines called
-right, decision logic sound, conditional language ("would place…"), no real create/stop
-calls, risk rules respected. Don't go live until the user is satisfied.
-
-**Go live:** offer `run_once` (single live tick), `loop` (continuous), or `loop` +
-`max_ticks`. Confirm the live model, start, confirm it's running, give monitoring
-commands. Always include risk limits when a loop agent can trade.
+trades.
+
+**How a strategy is authored, dry-run and launched lives in the shared `strategy_builder`
+playbook — read it (`manage_skill(action="read", name="strategy_builder")`) and follow it,
+passing `agent_slug="<agent_slug>"`.** It is the single source of truth, and it is shared
+precisely so an agent can give *itself* a loop without coming back through you. Don't
+restate its mechanics here; your job at this step is only to:
+
+- decide **with the user** whether a dedicated strategy is warranted at all,
+- make clear the loop does NOT have to trade — it can read routine X's output and decide
+  to trade, send a report, or watch a condition — at a **frequency the user sets**
+  (`frequency_sec`),
+- then run `strategy_builder` for the agent you just created.
+
+If the agent is capable enough to author its own loop, prefer handing it the job:
+`consult(agent="<agent_slug>", task="give yourself a loop that …")`. It reads the same
+shared playbook and knows its own domain better than you do.
 
 ## Monitoring existing agents
 1. `manage_trading_agent(action="list_agent_definitions")` — all agents, with their
diff --git a/agents/delta_neutral_funding_agent/AGENT.md b/agents/delta_neutral_funding_agent/AGENT.md
index e1b79387..07cd0bc0 100644
--- a/agents/delta_neutral_funding_agent/AGENT.md
+++ b/agents/delta_neutral_funding_agent/AGENT.md
@@ -11,6 +11,8 @@ tools:
 - manage_bots
 - manage_routines
 - search_history
+- manage_trading_agent
+- trading_agent_journal_read
 - manage_memory
 - manage_skill
 when_to_consult: When the user asks about delta-neutral funding strategies on HIP-3
diff --git a/agents/directional_trader/strategies/ema_trend_loop/strategy.md b/agents/directional_trader/strategies/ema_trend_loop/strategy.md
index 02199e63..188ca56b 100644
--- a/agents/directional_trader/strategies/ema_trend_loop/strategy.md
+++ b/agents/directional_trader/strategies/ema_trend_loop/strategy.md
@@ -119,6 +119,17 @@ Write a state entry:
 
 If you observed anything useful this tick (e.g. a config underperforming vs its backtest, a pair in a choppy regime, a config that caught a clean trend), write a learning entry. These learnings will inform Steps 1–3 on future ticks.
 
+### Step 8 — Notify user
+Call `send_notification` with a brief tick summary. Keep it short (4–6 lines):
+```
+🤖 EMA Trend Loop — Tick <N>
+Bot: <running|stopped>
+Controllers: <name> <state> <unrealized_pnl> | ...
+Session PnL: <total realized + unrealized>
+Action: <what you did this tick, or "monitoring">
+```
+Always send this even if nothing changed — the user needs to know the agent is alive.
+
 ## Risk rules
 - Max global drawdown: 15% of total_amount_quote
 - Max per-position loss before stopping controller: 10%
diff --git a/agents/market_making_expert/AGENT.md b/agents/market_making_expert/AGENT.md
index b8efc86b..0f821f84 100644
--- a/agents/market_making_expert/AGENT.md
+++ b/agents/market_making_expert/AGENT.md
@@ -10,6 +10,9 @@ tools:
 - manage_controllers
 - manage_bots
 - search_history
+- manage_routines
+- manage_trading_agent
+- trading_agent_journal_read
 - manage_memory
 - manage_skill
 when_to_consult: When the user asks about market regime, whether spreads are appropriate,
diff --git a/agents/solana_dex_lp_expert/AGENT.md b/agents/solana_dex_lp_expert/AGENT.md
index d55aec02..1f7a2d85 100644
--- a/agents/solana_dex_lp_expert/AGENT.md
+++ b/agents/solana_dex_lp_expert/AGENT.md
@@ -11,6 +11,9 @@ tools:
 - get_portfolio_overview
 - get_market_data
 - search_history
+- manage_routines
+- manage_trading_agent
+- trading_agent_journal_read
 - manage_memory
 - manage_skill
 when_to_consult: When the user asks which Solana memecoin pools to LP now, how to rank
diff --git a/agents/xrpl_market_maker/AGENT.md b/agents/xrpl_market_maker/AGENT.md
index 2a365400..8e51c5c9 100644
--- a/agents/xrpl_market_maker/AGENT.md
+++ b/agents/xrpl_market_maker/AGENT.md
@@ -11,6 +11,8 @@ tools:
 - manage_controllers
 - manage_bots
 - manage_routines
+- manage_trading_agent
+- trading_agent_journal_read
 - manage_skill
 - send_notification
 when_to_consult: When the user asks about quoting on the XRP Ledger DEX — whether a

From be0613b802349228e243f0b8ab5025d95419fe1a Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Wed, 12 Aug 2026 01:11:16 +0300
Subject: [PATCH 021/116] (feat) add tools to create strataegies at agent level

---
 agents/meteora_launch_lp/AGENT.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/agents/meteora_launch_lp/AGENT.md b/agents/meteora_launch_lp/AGENT.md
index 3ddc68d6..6bcfc2c4 100644
--- a/agents/meteora_launch_lp/AGENT.md
+++ b/agents/meteora_launch_lp/AGENT.md
@@ -11,6 +11,9 @@ tools:
 - get_portfolio_overview
 - get_market_data
 - send_notification
+- manage_routines
+- manage_trading_agent
+- trading_agent_journal_read
 - manage_memory
 - manage_skill
 when_to_consult: When the user asks whether a freshly-graduated Meteora DAMM v2 pool

From e62cd46d997af47ae2a1a50f54abbad1ff6f50f8 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Wed, 12 Aug 2026 01:11:23 +0300
Subject: [PATCH 022/116] (feat) add github issue template

---
 .github/ISSUE_TEMPLATE/bug_report.yml      | 106 +++++++++++++--------
 .github/ISSUE_TEMPLATE/feature_request.yml |  89 ++++++++++-------
 2 files changed, 124 insertions(+), 71 deletions(-)

diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
index 7ebbf5cb..6362e061 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.yml
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -1,40 +1,70 @@
 name: Bug Report
-description: Create a bug report to help us improve
-title: "Bug Report"
-labels: bug
+description: Something in Condor does not work the way it should
+title: "[Bug] "
+labels: [bug]
 body:
- - type: markdown
-   attributes:
-     value: |
-       ## **Before Submitting:**
-       
-       * Please edit the "Bug Report" to the title of the bug or issue
-       * Please make sure to look on our GitHub issues to avoid duplicate tickets
-       * You can add additional `Labels` to support this ticket (connectors, strategies, etc)
-       * If this is something to do with installation and how to's we would recommend to visit our [Hummingbot docs](https://hummingbot.org/docs/) and [Discord server](https://discord.gg/hummingbot)
- - type: textarea
-   id: what-happened
-   attributes:
-     label: Describe the bug
-     description: A clear and concise description of the bug or issue. Please make sure to add screenshots and error message to help us investigate
-     placeholder: Tell us what happened?
-   validations:
-     required: true
- - type: textarea
-   id: reproduce
-   attributes:
-     label: Steps to reproduce
-     description: A concise description of the steps to reproduce the buggy behavior
-     value: |
-       1. 
-       2. 
-       3. 
-   validations:
-     required: true
- - type: textarea
-   id: attachment
-   attributes:
-     label: Attach required files
-     description: Please attach your config file and log file located on the "../gateway/logs/" folder. It would be really helpful to triage the issue. 
-   validations:
-     required: false
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report this.
+
+        **Before you file:** search the [open issues](https://github.com/hummingbot/condor/issues?q=is%3Aissue) first — a duplicate splits the discussion in two.
+
+        **Never paste secrets.** API keys, wallet private keys, seed phrases, your `.env` or an unredacted `config.yml` do not belong in a public issue. If the dashboard filled in the "Environment" box below, read it before you submit.
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      description: Where in Condor did this happen? (The dashboard preselects this for you.)
+      options:
+        - Agents & chat
+        - Portfolio
+        - Bots & controllers
+        - Trading & executors
+        - Routines & reports
+        - Settings & connections
+        - Dashboard (other)
+        - Telegram bot
+        - Gateway / DEX
+        - Not sure
+    validations:
+      required: true
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: What you expected, and what you got instead. Screenshots help.
+      placeholder: The portfolio chart stays blank after I switch servers, but the balances table updates.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      description: The shortest path from a fresh session to the bug.
+      value: |
+        1. 
+        2. 
+        3. 
+    validations:
+      required: true
+
+  - type: textarea
+    id: attachment
+    attributes:
+      label: Environment
+      description: |
+        Condor version, page, browser and recent errors. The dashboard's "Report an issue" button (🐛, top right) fills this in automatically; otherwise paste the output of `git rev-parse --short HEAD` and how you run Condor (source, Docker).
+    validations:
+      required: false
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs
+      description: Relevant lines from the bot log or the browser console. Redact keys, hosts and wallet addresses first.
+    validations:
+      required: false
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml
index 13eb0bc9..147822c1 100644
--- a/.github/ISSUE_TEMPLATE/feature_request.yml
+++ b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -1,35 +1,58 @@
-name: Feature request
-description: Suggest an idea that will improve the Hummingbot codebase
-title: "Feature Request"
-labels: enhancement
+name: Feature Request
+description: Suggest something Condor should be able to do
+title: "[Feature] "
+labels: [enhancement]
 body:
- - type: markdown
-   attributes:
-     value: |
-       ## **Before Submitting:**
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for the idea.
 
-       * Please edit the "Feature Request" to the title of the feature
-       * Please make sure to look on our GitHub issues to avoid duplicate tickets
-       * You can add additional `Labels` to support this ticket (connectors, strategies, etc)
-       * If this is something to do with installation and how to's we would recommend to visit our [Discord server](https://discord.gg/hummingbot) and [Hummingbot docs](https://hummingbot.org/docs/)
- - type: textarea
-   id: feature-suggestion
-   attributes:
-     label: Feature Suggestion
-     description: A clear and concise description of the feature request. If you have looked at the code and know exactly what code changes are needed then please consider submitting a pull request instead.
-     placeholder: How you want to achieve the desired behavior
-   validations:
-     required: true
- - type: textarea
-   id: feature-impact
-   attributes:
-     label: Impact
-     description: A succinct description of why you want the desired behavior specified above.
-     placeholder: The desired behavior will allow me to..
-   validations:
-     required: true
- - type: textarea
-   id: feature-additional-context
-   attributes:
-     label: Additional context
-     description: Add any other context or screenshots about the feature request here (optional)
+        **Before you file:** search the [open issues](https://github.com/hummingbot/condor/issues?q=is%3Aissue) — someone may already be arguing for it, and a second voice on one thread carries further than a second thread.
+
+        If you already know what the change looks like in code, a pull request is welcome instead.
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      description: Which part of Condor would this touch? (The dashboard preselects this for you.)
+      options:
+        - Agents & chat
+        - Portfolio
+        - Bots & controllers
+        - Trading & executors
+        - Routines & reports
+        - Settings & connections
+        - Dashboard (other)
+        - Telegram bot
+        - Gateway / DEX
+        - Not sure
+    validations:
+      required: true
+
+  - type: textarea
+    id: feature-suggestion
+    attributes:
+      label: What should it do
+      description: Describe the behavior you want, not the implementation.
+      placeholder: Let me filter the executors table by connector, the way the bots table already filters by status.
+    validations:
+      required: true
+
+  - type: textarea
+    id: feature-impact
+    attributes:
+      label: Why it matters
+      description: What this would let you do that you cannot do today, and how often you hit it.
+      placeholder: With 40 executors open I scroll past everything to find the two on Hyperliquid.
+    validations:
+      required: true
+
+  - type: textarea
+    id: feature-additional-context
+    attributes:
+      label: Additional context
+      description: Mockups, links, the workaround you use today, or the version you are on.
+    validations:
+      required: false

From 4eecf43ce024845b6b8c359df28f223c61d1e487 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Wed, 12 Aug 2026 01:12:27 +0300
Subject: [PATCH 023/116] (feat) add issue erpoting

---
 condor/web/app.py                             |   2 +
 condor/web/routes/meta.py                     |  37 +++
 frontend/src/components/ErrorBoundary.tsx     |  59 ++++-
 frontend/src/components/ReportIssueDialog.tsx | 250 ++++++++++++++++++
 frontend/src/components/layout/AppShell.tsx   |  15 +-
 frontend/src/lib/api.ts                       |  12 +
 frontend/src/lib/diagnostics.ts               | 183 +++++++++++++
 frontend/src/lib/github-issue.ts              | 128 +++++++++
 frontend/src/lib/page-context.ts              | 122 +++++++++
 frontend/src/lib/shared-socket.ts             |  11 +
 frontend/src/lib/websocket.ts                 |   5 +
 frontend/src/main.tsx                         |   5 +
 uv.lock                                       |   8 +-
 13 files changed, 828 insertions(+), 9 deletions(-)
 create mode 100644 condor/web/routes/meta.py
 create mode 100644 frontend/src/components/ReportIssueDialog.tsx
 create mode 100644 frontend/src/lib/diagnostics.ts
 create mode 100644 frontend/src/lib/github-issue.ts
 create mode 100644 frontend/src/lib/page-context.ts

diff --git a/condor/web/app.py b/condor/web/app.py
index c85930f5..1300ea72 100644
--- a/condor/web/app.py
+++ b/condor/web/app.py
@@ -22,6 +22,7 @@
     conversations,
     executors,
     market,
+    meta,
     portfolio,
     positions,
     reports,
@@ -80,6 +81,7 @@ def create_app() -> FastAPI:
     app.include_router(positions.router, prefix="/api/v1")
     app.include_router(backtesting.router, prefix="/api/v1")
     app.include_router(market.router, prefix="/api/v1")
+    app.include_router(meta.router, prefix="/api/v1")
     app.include_router(ws.router, prefix="/api/v1")
     app.include_router(agents.router, prefix="/api/v1")
     app.include_router(routines.router, prefix="/api/v1")
diff --git a/condor/web/routes/meta.py b/condor/web/routes/meta.py
new file mode 100644
index 00000000..bf5003cd
--- /dev/null
+++ b/condor/web/routes/meta.py
@@ -0,0 +1,37 @@
+"""Build identity for the dashboard.
+
+One endpoint, and it exists for a single reason: a bug report that does not say
+which commit it came from costs a round trip to find out. The fields are the
+same ones the telemetry context already computes for its own envelope — a short
+commit, a branch, a runtime — so nothing new is collected here, it is only shown
+to the logged-in user who is about to paste it into an issue.
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends
+
+from condor.telemetry import context
+from condor.web.auth import get_current_user
+from condor.web.models import WebUser
+
+router = APIRouter(prefix="/meta", tags=["meta"])
+
+
+@router.get("/env")
+async def get_env(user: WebUser = Depends(get_current_user)) -> dict:
+    """Version and platform of this install.
+
+    Authenticated: the commit an install runs is not a secret, but it is a
+    detail about someone's deployment and there is no reason to hand it to an
+    anonymous caller.
+    """
+    app = context.app()
+    return {
+        "version": app["version"],
+        "branch": app["branch"],
+        "python": app["python"],
+        "os": app["os"],
+        "arch": app["arch"],
+        "in_docker": app["in_docker"],
+    }
diff --git a/frontend/src/components/ErrorBoundary.tsx b/frontend/src/components/ErrorBoundary.tsx
index 63ca7a2e..6bbe6fd3 100644
--- a/frontend/src/components/ErrorBoundary.tsx
+++ b/frontend/src/components/ErrorBoundary.tsx
@@ -1,5 +1,9 @@
 import { Component, type ErrorInfo, type ReactNode } from "react";
 
+import { SERVER_KEY } from "@/lib/auth";
+import { areaForRoute, buildDiagnostics } from "@/lib/diagnostics";
+import { openIssueDraft } from "@/lib/github-issue";
+
 function isChunkLoadError(error: Error): boolean {
   const msg = error.message || "";
   return (
@@ -18,17 +22,20 @@ interface Props {
 interface State {
   hasError: boolean;
   error: Error | null;
+  /** React's component stack — the most useful half of a crash report. */
+  componentStack: string | null;
 }
 
 export class ErrorBoundary extends Component<Props, State> {
-  state: State = { hasError: false, error: null };
+  state: State = { hasError: false, error: null, componentStack: null };
 
   static getDerivedStateFromError(error: Error): State {
-    return { hasError: true, error };
+    return { hasError: true, error, componentStack: null };
   }
 
   componentDidCatch(error: Error, info: ErrorInfo) {
     console.error("[ErrorBoundary]", error, info.componentStack);
+    this.setState({ componentStack: info.componentStack ?? null });
 
     // Auto-reload once on chunk/module import failures (stale deploys)
     if (isChunkLoadError(error)) {
@@ -43,10 +50,46 @@ export class ErrorBoundary extends Component<Props, State> {
 
   componentDidUpdate(prevProps: Props) {
     if (prevProps.resetKey !== this.props.resetKey && this.state.hasError) {
-      this.setState({ hasError: false, error: null });
+      this.setState({ hasError: false, error: null, componentStack: null });
     }
   }
 
+  /**
+   * File the crash the boundary just caught.
+   *
+   * The message and component stack are the report — asking the user to
+   * retype them is asking for a worse one. Read from `window`/`localStorage`
+   * rather than router and server context: a class component that renders
+   * *because* the tree below it failed is the wrong place to add hooks.
+   */
+  private reportCrash = () => {
+    const error = this.state.error;
+    const route = window.location.pathname + window.location.search;
+    const stack = [
+      error?.stack || `${error?.name}: ${error?.message}`,
+      this.state.componentStack ? `\n\nComponent stack:${this.state.componentStack}` : "",
+    ].join("");
+
+    openIssueDraft({
+      kind: "bug",
+      title: `Crash: ${(error?.message || "unknown error").slice(0, 80)}`,
+      area: areaForRoute(route),
+      description:
+        "The dashboard crashed and showed the \"Something went wrong\" screen.\n\n" +
+        `Error: ${error?.message || "unknown"}`,
+      // The boundary knows the route, not the clicks that led there — the one
+      // thing it cannot fill in is left for the reporter to write.
+      detail: "1. \n2. \n3. ",
+      logs: "```\n" + stack + "\n```",
+      diagnostics: buildDiagnostics({
+        kind: "bug",
+        route,
+        server: localStorage.getItem(SERVER_KEY),
+        env: null,
+      }),
+    });
+  };
+
   render() {
     if (this.state.hasError) {
       return (
@@ -63,13 +106,21 @@ export class ErrorBoundary extends Component<Props, State> {
                 if (this.state.error && isChunkLoadError(this.state.error)) {
                   window.location.reload();
                 } else {
-                  this.setState({ hasError: false, error: null });
+                  this.setState({ hasError: false, error: null, componentStack: null });
                 }
               }}
               className="rounded-md bg-[var(--color-primary)] px-4 py-2 text-sm font-medium text-white transition-colors hover:opacity-90"
             >
               {this.state.error && isChunkLoadError(this.state.error) ? "Reload" : "Try Again"}
             </button>
+            {this.state.error && !isChunkLoadError(this.state.error) && (
+              <button
+                onClick={this.reportCrash}
+                className="ml-2 rounded-md border border-[var(--color-border)] px-4 py-2 text-sm text-[var(--color-text-muted)] transition-colors hover:bg-[var(--color-surface-hover)] hover:text-[var(--color-text)]"
+              >
+                Report this
+              </button>
+            )}
           </div>
         </div>
       );
diff --git a/frontend/src/components/ReportIssueDialog.tsx b/frontend/src/components/ReportIssueDialog.tsx
new file mode 100644
index 00000000..3a5e66c1
--- /dev/null
+++ b/frontend/src/components/ReportIssueDialog.tsx
@@ -0,0 +1,250 @@
+import { useQuery } from "@tanstack/react-query";
+import { useState } from "react";
+import { ChevronDown, ChevronRight, ExternalLink } from "lucide-react";
+import { useLocation } from "react-router-dom";
+
+import { useEscapeKey } from "@/hooks/useEscapeKey";
+import { useServer } from "@/hooks/useServer";
+import { api } from "@/lib/api";
+import { areaForRoute, buildDiagnostics } from "@/lib/diagnostics";
+import { ISSUE_REPO, openIssueDraft, type IssueKind } from "@/lib/github-issue";
+import { AREAS, type Area } from "@/lib/page-context";
+
+/**
+ * "Report an issue" — writes a GitHub issue draft, does not file it.
+ *
+ * The button hands off to GitHub's own form with every field prefilled; the
+ * user submits it themselves. That keeps the report attributed to them, keeps
+ * the reply thread in their notifications, and keeps this install free of a
+ * token that could write to the tracker.
+ *
+ * The diagnostics block is opt-in and shown verbatim before it leaves: it ends
+ * up in a public issue, so the person attaching it gets to read it first.
+ */
+export function ReportIssueDialog({
+  open,
+  onClose,
+}: {
+  open: boolean;
+  onClose: () => void;
+}) {
+  const [kind, setKind] = useState<IssueKind>("bug");
+  const [title, setTitle] = useState("");
+  const [description, setDescription] = useState("");
+  const [detail, setDetail] = useState("");
+  const [area, setArea] = useState<Area | null>(null);
+  const [includeDiagnostics, setIncludeDiagnostics] = useState(true);
+  const [showDiagnostics, setShowDiagnostics] = useState(false);
+
+  const { pathname, search } = useLocation();
+  const { server } = useServer();
+  // Version never changes while the tab is open, and a failed fetch must not
+  // block the report — the block just says the version is unavailable.
+  const { data: env } = useQuery({
+    queryKey: ["meta-env"],
+    queryFn: api.getEnv,
+    staleTime: Infinity,
+    retry: false,
+    enabled: open,
+  });
+
+  useEscapeKey(open, onClose);
+
+  if (!open) return null;
+
+  const isBug = kind === "bug";
+  const route = pathname + search;
+  // The page the user is on is the best guess at the area, and the best guess
+  // is what a dropdown should open on — `area` only holds an explicit override.
+  const effectiveArea = area ?? areaForRoute(route);
+  const diagnostics = buildDiagnostics({
+    kind,
+    route,
+    server,
+    env: env ?? null,
+  });
+  const canSubmit = title.trim().length > 0 && description.trim().length > 0;
+
+  const submit = () => {
+    if (!canSubmit) return;
+    openIssueDraft({
+      kind,
+      title,
+      area: effectiveArea,
+      description,
+      detail,
+      diagnostics: includeDiagnostics ? diagnostics : undefined,
+    });
+    onClose();
+    setTitle("");
+    setDescription("");
+    setDetail("");
+    setArea(null);
+  };
+
+  const inputClass =
+    "w-full rounded-md border border-[var(--color-border)] bg-[var(--color-bg)] px-3 py-1.5 text-sm text-[var(--color-text)] focus:border-[var(--color-primary)] focus:outline-none";
+
+  return (
+    <div
+      className="fixed inset-0 z-50 flex items-center justify-center bg-black/60 p-4 backdrop-blur-sm"
+      onClick={onClose}
+    >
+      <div
+        className="max-h-full w-full max-w-lg overflow-y-auto rounded-xl border border-[var(--color-border)] bg-[var(--color-surface)] p-6 shadow-2xl"
+        onClick={(e) => e.stopPropagation()}
+      >
+        <h2 className="text-lg font-semibold text-[var(--color-text)]">Report an issue</h2>
+        <p className="mt-1 mb-4 text-xs text-[var(--color-text-muted)]">
+          Opens a prefilled issue on{" "}
+          <span className="font-mono">{ISSUE_REPO}</span> in a new tab. You review and
+          submit it under your own GitHub account — nothing is sent from here.
+        </p>
+
+        <div className="mb-4 flex gap-1 rounded-lg bg-[var(--color-bg)] p-1">
+          {(["bug", "feature"] as const).map((k) => (
+            <button
+              key={k}
+              onClick={() => setKind(k)}
+              className={`flex-1 rounded-md px-3 py-1.5 text-sm transition-colors ${
+                kind === k
+                  ? "bg-[var(--color-primary)]/15 text-[var(--color-primary)]"
+                  : "text-[var(--color-text-muted)] hover:text-[var(--color-text)]"
+              }`}
+            >
+              {k === "bug" ? "Something is broken" : "Feature idea"}
+            </button>
+          ))}
+        </div>
+
+        <div className="space-y-3">
+          <div>
+            <label className="mb-1 block text-xs text-[var(--color-text-muted)]">
+              Title <span className="text-[var(--color-red)]">*</span>
+            </label>
+            <input
+              value={title}
+              onChange={(e) => setTitle(e.target.value)}
+              className={inputClass}
+              placeholder={
+                isBug ? "Portfolio shows a blank chart" : "Filter executors by connector"
+              }
+              autoFocus
+            />
+          </div>
+
+          <div>
+            <label className="mb-1 block text-xs text-[var(--color-text-muted)]">
+              Area
+            </label>
+            <select
+              value={effectiveArea}
+              onChange={(e) => setArea(e.target.value as Area)}
+              className={inputClass}
+            >
+              {AREAS.map((a) => (
+                <option key={a} value={a}>
+                  {a}
+                </option>
+              ))}
+            </select>
+            <p className="mt-1 text-[10px] text-[var(--color-text-muted)]/70">
+              Preselected from the page you were on.
+            </p>
+          </div>
+
+          <div>
+            <label className="mb-1 block text-xs text-[var(--color-text-muted)]">
+              {isBug ? "What happened" : "What should it do"}{" "}
+              <span className="text-[var(--color-red)]">*</span>
+            </label>
+            <textarea
+              value={description}
+              onChange={(e) => setDescription(e.target.value)}
+              rows={4}
+              className={`${inputClass} resize-y`}
+              placeholder={
+                isBug
+                  ? "What you expected, and what you got instead."
+                  : "Describe the behavior you want."
+              }
+            />
+          </div>
+
+          <div>
+            <label className="mb-1 block text-xs text-[var(--color-text-muted)]">
+              {isBug ? "Steps to reproduce" : "Why it matters"}
+            </label>
+            <textarea
+              value={detail}
+              onChange={(e) => setDetail(e.target.value)}
+              rows={3}
+              className={`${inputClass} resize-y`}
+              placeholder={
+                isBug ? "1.\n2.\n3." : "What this would let you do that you cannot today."
+              }
+            />
+          </div>
+
+          <div className="rounded-md border border-[var(--color-border)] bg-[var(--color-bg)] p-3">
+            <label className="flex cursor-pointer items-start gap-2">
+              <input
+                type="checkbox"
+                checked={includeDiagnostics}
+                onChange={(e) => setIncludeDiagnostics(e.target.checked)}
+                className="mt-0.5 accent-[var(--color-primary)]"
+              />
+              <span className="text-xs text-[var(--color-text)]">
+                Attach diagnostics
+                <span className="block text-[10px] text-[var(--color-text-muted)]">
+                  {isBug
+                    ? "Build version, page, live-data status, failing requests and recent console errors."
+                    : "Build version and the page you were on — nothing else."}{" "}
+                  Becomes part of a public issue — read it first.
+                </span>
+              </span>
+            </label>
+
+            {includeDiagnostics && (
+              <>
+                <button
+                  onClick={() => setShowDiagnostics((v) => !v)}
+                  className="mt-2 flex items-center gap-1 text-[11px] text-[var(--color-text-muted)] hover:text-[var(--color-text)]"
+                >
+                  {showDiagnostics ? (
+                    <ChevronDown className="h-3 w-3" />
+                  ) : (
+                    <ChevronRight className="h-3 w-3" />
+                  )}
+                  {showDiagnostics ? "Hide" : "Show"} what will be attached
+                </button>
+                {showDiagnostics && (
+                  <pre className="mt-2 max-h-40 overflow-auto whitespace-pre-wrap break-all rounded bg-[var(--color-surface)] p-2 font-mono text-[10px] text-[var(--color-text-muted)]">
+                    {diagnostics}
+                  </pre>
+                )}
+              </>
+            )}
+          </div>
+        </div>
+
+        <div className="mt-5 flex justify-end gap-3">
+          <button
+            onClick={onClose}
+            className="rounded-lg px-4 py-2 text-sm text-[var(--color-text-muted)] transition-colors hover:bg-[var(--color-surface-hover)] hover:text-[var(--color-text)]"
+          >
+            Cancel
+          </button>
+          <button
+            onClick={submit}
+            disabled={!canSubmit}
+            className="flex items-center gap-1.5 rounded-lg bg-[var(--color-primary)] px-4 py-2 text-sm font-medium text-white transition-opacity hover:opacity-90 disabled:opacity-40"
+          >
+            Continue on GitHub
+            <ExternalLink className="h-3.5 w-3.5" />
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/frontend/src/components/layout/AppShell.tsx b/frontend/src/components/layout/AppShell.tsx
index 1a0c08d2..0f17fc06 100644
--- a/frontend/src/components/layout/AppShell.tsx
+++ b/frontend/src/components/layout/AppShell.tsx
@@ -1,8 +1,9 @@
-import { useEffect } from "react";
+import { useEffect, useState } from "react";
 import {
   Activity,
   Bot,
   Brain,
+  Bug,
   Eye,
   Moon,
   Settings,
@@ -15,6 +16,7 @@ import { NavLink, Outlet, useLocation, useNavigate } from "react-router-dom";
 
 import { ConnectKeysOverlay } from "@/components/ConnectKeysOverlay";
 import { ErrorBoundary } from "@/components/ErrorBoundary";
+import { ReportIssueDialog } from "@/components/ReportIssueDialog";
 import { ChatProvider } from "@/hooks/useChat";
 import { useCredentials } from "@/hooks/useCredentials";
 import { usePrefetchData } from "@/hooks/usePrefetchData";
@@ -54,6 +56,7 @@ function AppShellBody() {
   const { theme, toggleTheme } = useTheme();
   const navigate = useNavigate();
   const { hasKeys, isLoading: keysLoading } = useCredentials();
+  const [reportOpen, setReportOpen] = useState(false);
 
   // The chat workspace takes the full height and owns its own scrolling, so
   // the shell drops `main`'s padding for it. It lives at `/` — the entry point
@@ -123,6 +126,14 @@ function AppShellBody() {
           <CurrencySelector />
 
           <div className="flex items-center gap-1">
+            <button
+              onClick={() => setReportOpen(true)}
+              className="rounded p-1.5 text-[var(--color-text-muted)] hover:bg-[var(--color-surface-hover)] hover:text-[var(--color-accent)]"
+              title="Report an issue"
+            >
+              <Bug className="h-4 w-4" />
+            </button>
+
             <NavLink
               to="/settings"
               className={({ isActive }) =>
@@ -166,6 +177,8 @@ function AppShellBody() {
         </ErrorBoundary>
         {showKeysOverlay && <ConnectKeysOverlay />}
       </main>
+
+      <ReportIssueDialog open={reportOpen} onClose={() => setReportOpen(false)} />
     </div>
   );
 }
diff --git a/frontend/src/lib/api.ts b/frontend/src/lib/api.ts
index 2cb06de5..8c16966e 100644
--- a/frontend/src/lib/api.ts
+++ b/frontend/src/lib/api.ts
@@ -952,6 +952,15 @@ export function parseCustomAgentKey(
 
 // ── Backtesting ──
 
+export interface AppEnvResponse {
+  version: string;
+  branch: string;
+  python: string;
+  os: string;
+  arch: string;
+  in_docker: boolean;
+}
+
 export interface BacktestTask {
   task_id: string;
   status: "pending" | "running" | "completed" | "failed";
@@ -967,6 +976,9 @@ export interface BacktestTask {
 export const api = {
   getServers: () => apiFetch<ServerInfo[]>("/api/v1/servers"),
 
+  /** Build identity — shown to the user when they file an issue. */
+  getEnv: () => apiFetch<AppEnvResponse>("/api/v1/meta/env"),
+
   getServerStatus: (name: string) =>
     apiFetch<{ online: boolean; error?: string }>(
       `/api/v1/servers/${encodeURIComponent(name)}/status`,
diff --git a/frontend/src/lib/diagnostics.ts b/frontend/src/lib/diagnostics.ts
new file mode 100644
index 00000000..526d4b8b
--- /dev/null
+++ b/frontend/src/lib/diagnostics.ts
@@ -0,0 +1,183 @@
+/**
+ * What a report should carry besides the prose.
+ *
+ * A report that says "it broke on the bots page" costs a round trip to find out
+ * which build, which browser, and what the console said. This module keeps a
+ * small ring of the last errors the session saw and renders them — together
+ * with the build identity from `/api/v1/meta/env` and the page state from
+ * `page-context.ts` — as a block the user can read in full before it goes
+ * anywhere. Nothing is sent from here: the caller pastes the result into a
+ * GitHub issue form (see `github-issue.ts`).
+ */
+
+import {
+  type Area,
+  describePage,
+  displayPrefs,
+  failingRequests,
+  liveDataStatus,
+} from "@/lib/page-context";
+
+export interface AppEnv {
+  version: string;
+  branch: string;
+  python: string;
+  os: string;
+  arch: string;
+  in_docker: boolean;
+}
+
+const MAX_ENTRIES = 8;
+const MAX_ENTRY_LEN = 300;
+
+interface Entry {
+  at: number;
+  text: string;
+}
+
+const buffer: Entry[] = [];
+let installed = false;
+
+/**
+ * Mask the shapes that carry a secret.
+ *
+ * A console error can quote a request that carried a key. The user reviews the
+ * block before submitting, but review is not a control you rely on for
+ * credentials — the obvious shapes get masked first, and the review catches
+ * what is left.
+ */
+function redact(text: string): string {
+  return text
+    .replace(/(bearer\s+)[\w.\-+/=]{8,}/gi, "$1***")
+    .replace(/((?:api[_-]?key|secret|token|password|passphrase)["'\s:=]+)[^\s"',}]{6,}/gi, "$1***")
+    .replace(/\beyJ[\w-]{10,}\.[\w-]+\.[\w-]+/g, "***jwt***");
+}
+
+function stringify(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (value instanceof Error) return `${value.name}: ${value.message}`;
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}
+
+function record(text: string) {
+  const clean = redact(text).replace(/\s+/g, " ").trim().slice(0, MAX_ENTRY_LEN);
+  if (!clean) return;
+  // A render loop can emit the same line hundreds of times; keeping one copy
+  // leaves room in the ring for the errors that came before it.
+  const last = buffer[buffer.length - 1];
+  if (last && last.text === clean) {
+    last.at = Date.now();
+    return;
+  }
+  buffer.push({ at: Date.now(), text: clean });
+  if (buffer.length > MAX_ENTRIES) buffer.shift();
+}
+
+/**
+ * Start recording. Call once, before the app renders.
+ *
+ * `console.error` is wrapped rather than replaced: the original is always
+ * invoked, so the devtools output is exactly what it was without this.
+ */
+export function installErrorRecorder() {
+  if (installed || typeof window === "undefined") return;
+  installed = true;
+
+  const original = console.error;
+  console.error = (...args: unknown[]) => {
+    try {
+      record(args.map(stringify).join(" "));
+    } catch {
+      // Recording must never be the reason an error goes unlogged.
+    }
+    original.apply(console, args as []);
+  };
+
+  window.addEventListener("error", (e) => {
+    const where = e.filename ? ` (${e.filename}:${e.lineno})` : "";
+    record(`${e.message}${where}`);
+  });
+
+  window.addEventListener("unhandledrejection", (e) => {
+    record(`Unhandled rejection: ${stringify(e.reason)}`);
+  });
+}
+
+/** The recorded errors, oldest first, each stamped with a local wall clock. */
+export function recentErrors(): string[] {
+  return buffer.map(
+    (e) => `[${new Date(e.at).toTimeString().slice(0, 8)}] ${e.text}`,
+  );
+}
+
+/** Fenced so GitHub renders the block as written — single newlines and all. */
+function fence(body: string): string {
+  return "```\n" + body + "\n```";
+}
+
+/**
+ * The block that goes in the issue.
+ *
+ * A bug and an idea need different evidence. A bug gets everything the app
+ * knows — build, page, live-data health, failing requests, console errors —
+ * because any of it can be the answer. An idea gets the build and the page it
+ * was had on, and nothing else: a stack trace under a feature request is noise
+ * that makes the request look like a crash report.
+ */
+export function buildDiagnostics(opts: {
+  kind: "bug" | "feature";
+  /** Full route, path and query together — `pathname + search`. */
+  route: string;
+  server: string | null;
+  env: AppEnv | null;
+}): string {
+  const { kind, server, env } = opts;
+  const page = describePage(...splitRoute(opts.route));
+  const lines: string[] = [];
+
+  lines.push(
+    env
+      ? `Condor ${env.version} (${env.branch}) · Python ${env.python} · ${env.os}/${env.arch}${env.in_docker ? " · docker" : ""}`
+      : "Condor version: unavailable",
+  );
+  lines.push(`Page: ${page.page}  [${page.route}]`);
+
+  if (kind === "feature") return fence(lines.join("\n"));
+
+  lines.push(`Server: ${server || "none selected"}`);
+  lines.push(`Live data: websocket ${liveDataStatus()}`);
+  lines.push(`Display: ${displayPrefs()}`);
+  lines.push(`Browser: ${navigator.userAgent}`);
+  lines.push(
+    `Viewport: ${window.innerWidth}x${window.innerHeight} · TZ: ${Intl.DateTimeFormat().resolvedOptions().timeZone}`,
+  );
+
+  const failing = failingRequests();
+  if (failing.length) {
+    lines.push("", "Failing requests:");
+    for (const line of failing) lines.push(`- ${redact(line)}`);
+  }
+
+  const errors = recentErrors();
+  if (errors.length) {
+    lines.push("", "Recent console errors:");
+    for (const line of errors) lines.push(`- ${line}`);
+  }
+
+  return fence(lines.join("\n"));
+}
+
+/** `"/bots?tab=archived"` → `["/bots", "?tab=archived"]`. */
+function splitRoute(route: string): [string, string] {
+  const at = route.indexOf("?");
+  return at === -1 ? [route, ""] : [route.slice(0, at), route.slice(at)];
+}
+
+/** The area the current page belongs to — the dialog's default selection. */
+export function areaForRoute(route: string): Area {
+  return describePage(...splitRoute(route)).area;
+}
diff --git a/frontend/src/lib/github-issue.ts b/frontend/src/lib/github-issue.ts
new file mode 100644
index 00000000..05b3c24e
--- /dev/null
+++ b/frontend/src/lib/github-issue.ts
@@ -0,0 +1,128 @@
+/**
+ * Prefilled GitHub issue links.
+ *
+ * The dashboard files no issues itself. It builds the URL of GitHub's own new-
+ * issue form with the fields already filled in, and the user submits it under
+ * their own account — so the report is attributed to the person who hit the
+ * bug, they get the reply notifications, and this install holds no token that
+ * could write to the tracker.
+ *
+ * The query keys are the `id`s of the fields in `.github/ISSUE_TEMPLATE/*.yml`.
+ * Renaming a field there silently drops its prefill here (GitHub ignores keys
+ * it does not recognize), so the two files move together.
+ */
+
+import type { Area } from "@/lib/page-context";
+
+export const ISSUE_REPO = "hummingbot/condor";
+
+/**
+ * GitHub answers 414 to a request line a few kilobytes past this, and browsers
+ * and proxies have their own limits below that. Staying well under it means a
+ * long report degrades by losing its diagnostics tail, not by failing to open.
+ */
+const MAX_URL_LEN = 6000;
+
+export type IssueKind = "bug" | "feature";
+
+export interface IssueDraft {
+  kind: IssueKind;
+  title: string;
+  /** Which part of Condor — matched against the template's dropdown labels. */
+  area?: Area;
+  /** What happened (bug) or what to build (feature). */
+  description: string;
+  /** Steps to reproduce (bug) or why it matters (feature). */
+  detail?: string;
+  /** The block from `buildDiagnostics`, when the user chose to include it. */
+  diagnostics?: string;
+  /** A stack trace or log excerpt. Bug template only — features have no such field. */
+  logs?: string;
+}
+
+interface FieldMap {
+  template: string;
+  description: string;
+  detail: string;
+  /** Where the diagnostics go — the first field trimmed when the URL is long. */
+  extra: string;
+  /** Free-form logs. Absent on the feature template, which has no such field. */
+  logs?: string;
+}
+
+const FIELDS: Record<IssueKind, FieldMap> = {
+  bug: {
+    template: "bug_report.yml",
+    description: "what-happened",
+    detail: "reproduce",
+    extra: "attachment",
+    logs: "logs",
+  },
+  feature: {
+    template: "feature_request.yml",
+    description: "feature-suggestion",
+    detail: "feature-impact",
+    extra: "feature-additional-context",
+  },
+};
+
+const TRUNCATED = "\n…(truncated)";
+
+/** Drop `key`'s tail until the whole URL fits; delete the field if it empties. */
+function trimField(
+  params: URLSearchParams,
+  key: string,
+  url: () => string,
+  floor: number,
+) {
+  if (!params.has(key)) return;
+  let value = params.get(key) ?? "";
+  while (url().length > MAX_URL_LEN && value.length > floor) {
+    value = value.slice(0, Math.max(floor, value.length - 400));
+    if (!value.trim()) {
+      params.delete(key);
+      return;
+    }
+    params.set(key, value + TRUNCATED);
+  }
+}
+
+export function buildIssueUrl(draft: IssueDraft): string {
+  const fields = FIELDS[draft.kind];
+  const base = `https://github.com/${ISSUE_REPO}/issues/new`;
+  const params = new URLSearchParams();
+
+  params.set("template", fields.template);
+  if (draft.title.trim()) params.set("title", draft.title.trim());
+  // GitHub matches a prefilled dropdown by its label. A value the template does
+  // not offer is ignored, leaving the field for the user to pick — so a stale
+  // label degrades to a manual choice, never to a broken link.
+  if (draft.area) params.set("area", draft.area);
+  params.set(fields.description, draft.description.trim());
+  if (draft.detail?.trim()) params.set(fields.detail, draft.detail.trim());
+  if (draft.diagnostics?.trim()) params.set(fields.extra, draft.diagnostics.trim());
+  if (fields.logs && draft.logs?.trim()) params.set(fields.logs, draft.logs.trim());
+
+  const url = () => `${base}?${params.toString()}`;
+
+  // Cut the machine-written parts to nothing before touching a word the user
+  // wrote, cheapest first: the environment block is short and reconstructible,
+  // a stack trace is not, and both keep their head — where the answer is. Only
+  // if the prose alone is oversized does it get trimmed, and never below a
+  // length that still describes the problem.
+  trimField(params, fields.extra, url, 0);
+  if (fields.logs) trimField(params, fields.logs, url, 0);
+  trimField(params, fields.detail, url, 0);
+  trimField(params, fields.description, url, 500);
+
+  return url();
+}
+
+/**
+ * Open the prefilled form. Called from a click handler so the popup blocker
+ * treats it as user-initiated; `noopener` keeps the new tab from reaching back
+ * into this one.
+ */
+export function openIssueDraft(draft: IssueDraft) {
+  window.open(buildIssueUrl(draft), "_blank", "noopener,noreferrer");
+}
diff --git a/frontend/src/lib/page-context.ts b/frontend/src/lib/page-context.ts
new file mode 100644
index 00000000..700bda5b
--- /dev/null
+++ b/frontend/src/lib/page-context.ts
@@ -0,0 +1,122 @@
+/**
+ * What the app can say about itself without asking the user.
+ *
+ * A report is only as good as the state it describes, and the person filing it
+ * should not have to know which server was selected, which query had failed, or
+ * what the route was called. All of that is already in the app — this module
+ * reads it out of the router path, the preference stores, the query cache and
+ * the socket, so the dialog can hand it over pre-written.
+ */
+
+import { queryClient } from "@/lib/queryClient";
+import { socketStatus } from "@/lib/shared-socket";
+
+/**
+ * The areas the issue templates offer. Kept identical, string for string, to
+ * the `area` dropdown options in `.github/ISSUE_TEMPLATE/*.yml`: GitHub matches
+ * a prefilled dropdown by its label, so a rewording on either side has to
+ * happen on both.
+ */
+export const AREAS = [
+  "Agents & chat",
+  "Portfolio",
+  "Bots & controllers",
+  "Trading & executors",
+  "Routines & reports",
+  "Settings & connections",
+  "Dashboard (other)",
+  "Telegram bot",
+  "Gateway / DEX",
+  "Not sure",
+] as const;
+
+export type Area = (typeof AREAS)[number];
+
+export interface PageContext {
+  /** Human name of the page, with the id it was showing. */
+  page: string;
+  /** The template area this page belongs to — the dialog's default. */
+  area: Area;
+  route: string;
+}
+
+/** Route → page name, area, and whatever the path segments identify. */
+export function describePage(pathname: string, search = ""): PageContext {
+  const [, first = "", second = "", third = "", fourth = ""] = pathname.split("/");
+  const tab = new URLSearchParams(search).get("tab");
+  const withTab = (name: string) => (tab ? `${name} · tab "${tab}"` : name);
+  const route = pathname + search;
+
+  const of = (page: string, area: Area): PageContext => ({ page, area, route });
+
+  switch (first) {
+    case "":
+      return of("Chat workspace", "Agents & chat");
+    case "agents":
+      if (second && third === "strategies" && fourth) {
+        return of(`Strategy detail (agent "${second}", strategy "${fourth}")`, "Agents & chat");
+      }
+      if (second) return of(`Agent detail ("${second}")`, "Agents & chat");
+      return of("Agents", "Agents & chat");
+    case "portfolio":
+      return of(withTab("Portfolio"), "Portfolio");
+    case "bots":
+      return second
+        ? of(`Bot detail ("${second}")`, "Bots & controllers")
+        : of(withTab("Bots"), "Bots & controllers");
+    case "trade":
+      return of(withTab("Trade"), "Trading & executors");
+    case "executors":
+      return of(withTab("Executors"), "Trading & executors");
+    case "routines":
+      return of(withTab("Routines"), "Routines & reports");
+    case "reports":
+      return of("Reports", "Routines & reports");
+    case "settings":
+      return of(withTab("Settings"), "Settings & connections");
+    default:
+      return of(pathname, "Dashboard (other)");
+  }
+}
+
+/**
+ * The requests that are currently failing, newest first.
+ *
+ * This is the half of a bug report users cannot write themselves: "the page is
+ * empty" and "`portfolio/history` is 502-ing" are the same event, and only the
+ * second one is actionable. Query keys are read as written — they name a
+ * server or a bot, which is the user's own data, and the block is shown to
+ * them before it goes anywhere.
+ */
+export function failingRequests(limit = 5): string[] {
+  try {
+    return queryClient
+      .getQueryCache()
+      .findAll()
+      .filter((q) => q.state.status === "error")
+      .sort((a, b) => (b.state.errorUpdatedAt ?? 0) - (a.state.errorUpdatedAt ?? 0))
+      .slice(0, limit)
+      .map((q) => {
+        const key = q.queryKey
+          .map((part) => (typeof part === "object" ? JSON.stringify(part) : String(part)))
+          .join(" / ");
+        const message = (q.state.error as Error | null)?.message ?? "unknown error";
+        return `${key} → ${message}`;
+      });
+  } catch {
+    // Diagnostics must never be the thing that breaks the report dialog.
+    return [];
+  }
+}
+
+/** Preferences that change what the page renders — and so what "wrong" means. */
+export function displayPrefs(): string {
+  const theme = localStorage.getItem("condor_theme") ?? "system";
+  const currency = localStorage.getItem("condor_display_currency") ?? "USDT";
+  return `theme ${theme} · currency ${currency}`;
+}
+
+/** Live-data health. A stale dashboard is usually a closed socket. */
+export function liveDataStatus(): string {
+  return socketStatus();
+}
diff --git a/frontend/src/lib/shared-socket.ts b/frontend/src/lib/shared-socket.ts
index d8f0d041..f42c7200 100644
--- a/frontend/src/lib/shared-socket.ts
+++ b/frontend/src/lib/shared-socket.ts
@@ -281,6 +281,17 @@ export function acquireSocket(token: string): CondorWebSocket {
   return socket ?? openSocket(token);
 }
 
+/**
+ * State of the shared connection, for a bug report to quote.
+ *
+ * "closed" while the dashboard is open is itself the bug in most stale-data
+ * reports, and it is not something a user can see.
+ */
+export function socketStatus(): "connected" | "connecting" | "closed" {
+  if (!socket) return "closed";
+  return socket.isOpen ? "connected" : "connecting";
+}
+
 /** Drop a reference. The last one closes the socket after a short grace period. */
 export function releaseSocket(): void {
   socketRefs = Math.max(0, socketRefs - 1);
diff --git a/frontend/src/lib/websocket.ts b/frontend/src/lib/websocket.ts
index ad49d551..3ce503bb 100644
--- a/frontend/src/lib/websocket.ts
+++ b/frontend/src/lib/websocket.ts
@@ -29,6 +29,11 @@ export class CondorWebSocket {
     this.token = token;
   }
 
+  /** Whether the underlying socket is open right now (diagnostics only). */
+  get isOpen(): boolean {
+    return this.ws?.readyState === WebSocket.OPEN;
+  }
+
   connect() {
     this.shouldConnect = true;
     this._connect();
diff --git a/frontend/src/main.tsx b/frontend/src/main.tsx
index bef5202a..9f6a4ac9 100644
--- a/frontend/src/main.tsx
+++ b/frontend/src/main.tsx
@@ -2,6 +2,11 @@ import { StrictMode } from 'react'
 import { createRoot } from 'react-dom/client'
 import './index.css'
 import App from './App.tsx'
+import { installErrorRecorder } from './lib/diagnostics'
+
+// Before the first render: an error thrown on mount is exactly the one a bug
+// report needs, and it happens before any component could install this.
+installErrorRecorder()
 
 createRoot(document.getElementById('root')!).render(
   <StrictMode>
diff --git a/uv.lock b/uv.lock
index d44ebcea..76f03edf 100644
--- a/uv.lock
+++ b/uv.lock
@@ -640,7 +640,7 @@ requires-dist = [
     { name = "fastapi" },
     { name = "faster-whisper" },
     { name = "geckoterminal-py" },
-    { name = "hummingbot-api-client", specifier = "==1.5.6" },
+    { name = "hummingbot-api-client", specifier = "==1.5.7" },
     { name = "isort", marker = "extra == 'dev'" },
     { name = "kaleido" },
     { name = "markdown", specifier = ">=3.10.2" },
@@ -1492,14 +1492,14 @@ wheels = [
 
 [[package]]
 name = "hummingbot-api-client"
-version = "1.5.6"
+version = "1.5.7"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "aiohttp" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/00/bd/4c0a9b857afedc2aeca245334610632f98dbe8ad5df6e262d501cd897173/hummingbot_api_client-1.5.6.tar.gz", hash = "sha256:88f8960b6f2b821d36e72a13e37297417d40293e60335f66b4c5c17cac4dfbd0", size = 39773, upload-time = "2026-08-03T21:50:28.863Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/f3/92/9bb06b365b8d9c457ad39aa58ffa471ef2668f43433b6fae5b338c57609f/hummingbot_api_client-1.5.7.tar.gz", hash = "sha256:65d9cef4f518fd9ab2dacd4de345e1d46ea30a1a19c01b730936078f9b441679", size = 41107, upload-time = "2026-08-10T14:46:53.626Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/91/ad/68034b1de34c4e99e063a9f384272b9a7a3298dbc241602ac224328e5a72/hummingbot_api_client-1.5.6-py3-none-any.whl", hash = "sha256:44806f9e358c55a24f30fc7f031c2b95e0569bece6bacaf0440d3a503576d07e", size = 46899, upload-time = "2026-08-03T21:50:27.584Z" },
+    { url = "https://files.pythonhosted.org/packages/eb/ce/50e80f122cbc5a80aa9a5c595381d54633fd2e72cfb639e78320f044b66c/hummingbot_api_client-1.5.7-py3-none-any.whl", hash = "sha256:a1a133f2ba7ef9f30ffec99ab61cf10377d8be210e39d85f0e76dc8f63bab5cb", size = 48960, upload-time = "2026-08-10T14:46:52.307Z" },
 ]
 
 [[package]]

From 0323ae18a0d2ec2eae59279275c56e491869115a Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Wed, 12 Aug 2026 01:12:47 +0300
Subject: [PATCH 024/116] (feat) add strategy builder skill

---
 .../_shared/skills/strategy_builder/SKILL.md  | 137 ++++++++++++++++++
 1 file changed, 137 insertions(+)
 create mode 100644 agents/_shared/skills/strategy_builder/SKILL.md

diff --git a/agents/_shared/skills/strategy_builder/SKILL.md b/agents/_shared/skills/strategy_builder/SKILL.md
new file mode 100644
index 00000000..dacdd775
--- /dev/null
+++ b/agents/_shared/skills/strategy_builder/SKILL.md
@@ -0,0 +1,137 @@
+---
+name: strategy_builder
+description: Give YOURSELF a loop — write a tick playbook (a strategy) under your own slug, dry-run it, and start it. The shared contract for how a strategy is authored, validated and launched; read by any agent that wants to act autonomously instead of only being consulted.
+when_to_use: You are an agent and the user wants you to act on a loop — run every N seconds, watch a condition, report on a schedule, or trade autonomously. Also read this before editing or re-launching a strategy you already own. NOT for creating or deleting other agents (that is Condor's agent_builder).
+created: '2026-08-11T00:00:00Z'
+source: chat
+---
+
+# Strategy Builder
+
+You are an **agent**. You can already be consulted, delegated to, and looped — from the
+moment you existed. This playbook covers the last of those: giving your loop a **specific
+tick playbook** instead of the generic default.
+
+A **strategy** is a tick system prompt the engine runs in a **session**, at a frequency
+the user sets. It lives at `agents/{your_slug}/strategies/{strategy_slug}/strategy.md` and
+it is yours — you author it, under your own slug.
+
+> **Scope.** This is about giving *yourself* a loop. Creating, editing or deleting *other*
+> agents belongs to Condor (`agent_builder`). If the user wants a whole new specialist,
+> say so and let them ask Condor.
+
+## When a strategy is worth it
+
+`start_agent(strategy_id="<your_slug>")` already works with no strategy — it ticks a
+default playbook driven by your AGENT.md. That default is deliberately generic. Write a
+strategy when the loop needs to be **specific and disciplined**: a fixed analysis order, a
+decision rule, executor schemas, risk limits.
+
+**The loop does NOT have to trade.** Define the tick task however the user wants:
+
+- read a routine's output and **decide whether to trade** (create/stop executors),
+- or just **send a report / notification**,
+- or watch a condition and act only when it's met.
+
+## Step 1 — Prepare (only if it trades)
+
+BEFORE writing the strategy, fetch the schema for every executor type the loop will use —
+`manage_executors(executor_type="grid_strike")`, etc. — and embed the required
+fields/types directly into the instructions. The tick LLM has no other way to learn them.
+Same for any controller config it manages (`manage_controllers`).
+
+If the loop should reason over structured data, make sure the routine exists first
+(`manage_routines(action="list", agent="<your_slug>")`). Routines are agent-scoped, so any
+strategy you own can call them. Need a new one? Do NOT write it inline — hand it to a
+background worker: `delegate(action="start", agent="condor", task="build a routine that …
+for agent <your_slug>")`.
+
+## Step 2 — Create the strategy
+
+```
+manage_trading_agent(
+    action="create_strategy",
+    agent_slug="<your_slug>",              # yourself
+    name="BRL MM",
+    description="…",
+    instructions="<tick system prompt>",
+    # agent_key omitted → inherits your model; overridable at launch
+    config={"connector_name": "binance", "frequency_sec": 60,
+            "total_amount_quote": 100, "execution_mode": "loop"}
+)
+```
+
+Returns the composite key `"<your_slug>.<strategy_slug>"` — that is the `strategy_id` for
+everything after.
+
+The tick instructions MUST include:
+
+- **Objective** — what one tick is for.
+- **Analysis** — which routine to call *by name* and how to read its output.
+- **Decision logic** — act / report / hold, with the condition for each.
+
+…and, only if it trades:
+
+- **Executor config** — the FULL schema: every required field, type, range, ordering rule.
+- **Parameter inference** — how to derive prices/side/TP from routine output + market data.
+- **Risk rules** — max position, position limits, stop behaviour.
+- **Error recovery** — on a failed create, re-fetch the schema, fix, retry once, journal it.
+
+**Generic vs specific:**
+- GENERIC (default): pair/connector are NOT in the instructions — they arrive at launch via
+  `trading_context`. Refer to "the configured trading pair"; keep a sensible `default_config`.
+- SPECIFIC: pair/connector baked in (e.g. an ETH/BTC ratio play).
+
+## Step 3 — Dry run before live (if it trades)
+
+```
+manage_trading_agent(action="start_agent", strategy_id="<your_slug.strategy_slug>",
+    config={"execution_mode": "dry_run",
+            "trading_context": "Trade BTC-USDT on binance_perpetual",
+            "frequency_sec": 60, "total_amount_quote": 100,
+            "risk_limits": {"max_position_size_quote": 200, "max_open_executors": 3}})
+```
+
+Review with `trading_agent_journal_read(agent_id=…, section="run:1")`: routines called
+right, decision logic sound, conditional language ("would place…"), no real create/stop
+calls, risk rules respected. Do not go live until the user is satisfied.
+
+> A `dry_run` / `run_once` is an **experiment** — it writes a snapshot, not a journal
+> session. Read it back the same way; don't expect a numbered run to persist.
+
+## Step 4 — Go live
+
+Offer `run_once` (single live tick), `loop` (continuous), or `loop` + `max_ticks`. Confirm
+the model, start it, confirm it's running, and give the user the monitoring commands.
+**Always include risk limits when the loop can trade.**
+
+## Monitoring what you own
+
+1. `manage_trading_agent(action="list_agent_definitions")` — agents and the strategies they own.
+2. `manage_trading_agent(action="list_agents")` — running loop instances.
+3. `manage_trading_agent(action="agent_status", agent_id=…)` — instance status.
+4. `trading_agent_journal_read(agent_id=…, section="summary"|"runs"|"run:N")`.
+
+## Reference
+
+**Model:** the strategy's `agent_key` defaults to yours; override per launch with
+`config={"agent_key": "…"}`. Never invent one — call `get_available_models` and pick from
+what the operator actually has, or leave it inherited. A pydantic-ai key
+(`ollama:`/`openai:`/`groq:`/`lmstudio:`/`openrouter:`/`custom@…`) enforces the `tools`
+allowlist; an ACP key (`claude-code`/`claude-acp`/`gemini`/`copilot`) runs unrestricted,
+with mutations still confirmation-gated.
+
+**Server:** leave `server_name` empty unless the user pins it. A strategy you own runs on
+whichever server your agent resolves.
+
+**Editing & deleting:** `update_strategy(strategy_id=…, instructions=…)` to revise the tick
+playbook; `delete_strategy(strategy_id=…)` to remove it. Stop any running instance first.
+
+## Rules
+
+- Author strategies **under your own slug only**. Another agent's fleet is not yours to edit.
+- Fetch executor/controller schemas BEFORE writing instructions that use them.
+- One strategy per loop job — don't overload a tick with unrelated objectives.
+- A loop doesn't have to trade. When it does: risk limits always, dry run always.
+- Show the user the dry-run journal before proposing to go live.
+- Don't write routine code inline — delegate it to a Condor worker.

From 244b40466ebc9be6a73bd27bc96d118db61a8cc9 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Wed, 12 Aug 2026 01:14:41 +0300
Subject: [PATCH 025/116] (docs) readme: web trade panel, agents, issue
 reporting

---
 README.md | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 1728aab6..063627cc 100644
--- a/README.md
+++ b/README.md
@@ -22,8 +22,11 @@ A Telegram bot for monitoring and trading with Hummingbot via the **Hummingbot A
 - **Bot Monitoring** - Track active Hummingbot trading bots with real-time status and metrics
 - **CLOB Trading** - Place orders on centralized exchanges (Binance, Bybit, etc.) with interactive menus
 - **DEX Trading** - Swap tokens and manage CLMM liquidity positions via Gateway
+- **Web Dashboard** - Browser UI (via **`/web`**) with a live trade panel that covers both CEX and DEX venues: order book trading, DEX swaps, and CLMM liquidity positions created and drawn directly on the chart
 - **Configuration** - Manage API servers, exchange credentials, and Gateway through Telegram (`/servers`, `/keys`, `/gateway`)
 - **AI Assistant** - Natural language trading help via **`/agent`** (optional OpenAI or OpenRouter keys, or any custom OpenAI-compatible endpoint like Venice AI; MCP tools when configured)
+- **AI Agents** - Domain agents that can be consulted, delegated to, or run on a loop — each can author its own tick strategy (analysis order, decision rules, risk limits) and run it autonomously with dry-run support
+- **Issue Reporting** - A **Report an issue** button in the web dashboard prefills a GitHub issue draft (with opt-in, review-before-send diagnostics) that you submit from your own GitHub account
 
 ## What you need
 
@@ -412,7 +415,7 @@ See `flows/` directory for detailed command flow documentation:
 - **Docs**: https://condor.hummingbot.org
 - **Installation guide**: https://condor.hummingbot.org/getting-started/installing
 - **Tailscale guide**: https://hummingbot.org/hummingbot-api/tailscale/
-- **Issues**: https://github.com/hummingbot/condor/issues
+- **Issues**: https://github.com/hummingbot/condor/issues — or use the **Report an issue** button in the web dashboard to prefill a bug report or feature request with diagnostics
 
 ---
 

From d667abced3c03d2898beba8aeeff4f59cf5599d7 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Wed, 12 Aug 2026 20:22:50 +0300
Subject: [PATCH 026/116] (feat) improve timeouts

---
 condor/agents/config.py       |   5 ++
 condor/agents/engine.py       |  20 ++++-
 condor/agents/shutdown.py     |  16 ++--
 condor/runtime/timeouts.py    |  14 +--
 condor/web/models.py          |  17 ++++
 condor/web/routes/agents.py   |   2 +
 condor/web/routes/settings.py | 156 ++++++++++++++++++++++++++++++++++
 7 files changed, 217 insertions(+), 13 deletions(-)

diff --git a/condor/agents/config.py b/condor/agents/config.py
index f7d536aa..88b418ac 100644
--- a/condor/agents/config.py
+++ b/condor/agents/config.py
@@ -44,6 +44,11 @@ class AgentConfig(BaseModel):
         description="Total capital budget for this session in quote currency",
     )
     frequency_sec: int = Field(default=60, description="Tick frequency in seconds")
+    tick_timeout_sec: int = Field(
+        default=0,
+        description="Wall-clock budget for one tick's agent session, in seconds; "
+        "0 = use the runtime default (10 min, or CONDOR_TIMEOUT_TICK_DEFAULT)",
+    )
     trading_context: str = Field(
         default="",
         description="Natural language session context that guides the agent's trading decisions",
diff --git a/condor/agents/engine.py b/condor/agents/engine.py
index a390fcdb..923959e6 100644
--- a/condor/agents/engine.py
+++ b/condor/agents/engine.py
@@ -28,6 +28,7 @@
 )
 from condor.acp.pydantic_ai_client import PydanticAIClient, is_pydantic_ai_model
 from condor.runtime.registry_file import LoopState
+from condor.runtime.timeouts import resolve_tick_timeout
 from condor.telemetry import taps as telemetry_taps
 
 from .agent import Agent
@@ -600,8 +601,15 @@ async def _tick(self) -> None:
         tool_call_map: dict[str, dict[str, Any]] = {}
 
         await acp_client.start()
+        # Wall-clock budget for this tick's agent session. Comes from the shared
+        # policy (10 min default, CONDOR_TIMEOUT_TICK_DEFAULT) unless the run
+        # config sets ``tick_timeout_sec`` -- a slower model or a tick that does
+        # real research needs more room than a quoting loop does.
+        tick_timeout = resolve_tick_timeout(
+            execution_mode=mode, strategy=self.config.get("tick_timeout_sec")
+        )
         try:
-            async with asyncio.timeout(300):
+            async with asyncio.timeout(tick_timeout):
                 async for event in self._collect_stream(acp_client, prompt):
                     if isinstance(event, TextChunk):
                         response_chunks.append(event.text)
@@ -610,7 +618,11 @@ async def _tick(self) -> None:
                         if new_tc is not None:
                             tool_calls.append(new_tc)
         except asyncio.TimeoutError:
-            log.warning("TickEngine %s: ACP prompt timed out", self.agent_id)
+            log.warning(
+                "TickEngine %s: ACP prompt timed out after %ds",
+                self.agent_id,
+                tick_timeout,
+            )
             response_chunks.append("(timed out)")
         finally:
             await acp_client.stop()
@@ -1016,6 +1028,10 @@ def get_info(self) -> dict[str, Any]:
             "close_type_counts": sd.get("close_type_counts", {}),
             "fees_known": sd.get("fees_known", True),
             "frequency_sec": self.config.get("frequency_sec", 60),
+            "tick_timeout_sec": resolve_tick_timeout(
+                execution_mode=self.config.get("execution_mode", "loop"),
+                strategy=self.config.get("tick_timeout_sec"),
+            ),
             "server_name": self.config.get("server_name", ""),
             "total_amount_quote": self.config.get("total_amount_quote", 100),
             "trading_context": self.config.get("trading_context", ""),
diff --git a/condor/agents/shutdown.py b/condor/agents/shutdown.py
index 05432c37..3912b859 100644
--- a/condor/agents/shutdown.py
+++ b/condor/agents/shutdown.py
@@ -20,6 +20,8 @@
 import logging
 from typing import Any
 
+from condor.runtime.timeouts import resolve_tick_timeout
+
 from .strategy import Strategy, _parse_frontmatter
 
 log = logging.getLogger(__name__)
@@ -298,10 +300,11 @@ async def _run_llm_cleanup(
 ) -> None:
     """Best-effort LLM nuance pass on top of the guaranteed deterministic floor.
 
-    Bounded by a hard 300s timeout (the same ceiling the tick ACP session runs
-    under) and fully fail-open: the safety-critical winddown already happened, so
-    any hang or error here is logged and swallowed — it can never strand a position
-    the way an LLM-only shutdown could.
+    Bounded by the same budget the tick agent session runs under (the shared
+    timeout policy, overridable per run with ``tick_timeout_sec``) and fully
+    fail-open: the safety-critical winddown already happened, so any hang or
+    error here is logged and swallowed — it can never strand a position the way
+    an LLM-only shutdown could.
     """
     agent = getattr(engine, "agent", None)
     if not body or agent is None:
@@ -312,7 +315,10 @@ async def _run_llm_cleanup(
         running = await _get_running_executors(engine, client)
         positions = await _fetch_positions(client, engine.agent_id)
         context = _build_llm_context(policy, running, positions, failures)
-        async with asyncio.timeout(300):
+        cleanup_timeout = resolve_tick_timeout(
+            strategy=engine.config.get("tick_timeout_sec")
+        )
+        async with asyncio.timeout(cleanup_timeout):
             await _run_agent_to_completion(
                 slug=agent.slug,
                 user_id=engine.user_id,
diff --git a/condor/runtime/timeouts.py b/condor/runtime/timeouts.py
index 90c27ba9..5a7e40cb 100644
--- a/condor/runtime/timeouts.py
+++ b/condor/runtime/timeouts.py
@@ -43,7 +43,8 @@ class TimeoutPolicy:
     sse_stream: int = 1800
     # Budget for one MCP tool call.
     mcp_call: float = 15.0
-    # Default budget for one strategy tick.
+    # Wall-clock budget for one agent session: a strategy tick's LLM turn, and
+    # the shutdown cleanup pass that runs under the same ceiling. 10 minutes.
     tick_default: int = 600
 
     @classmethod
@@ -78,15 +79,16 @@ def resolve_tick_timeout(
     caller: int | None = None,
     strategy: int | None = None,
 ) -> int:
-    """Pick a tick budget: explicit caller override > strategy config > default.
+    """Pick an agent-session budget: caller override > run config > policy.
 
-    A single-tick run (dry run / run once) is a human waiting on a result, so it
-    gets the shorter default; a loop tick is unattended and may take longer.
+    ``strategy`` is the run's ``tick_timeout_sec``; 0 or None means "no opinion",
+    which falls through to ``tick_default`` (10 min, or CONDOR_TIMEOUT_TICK_DEFAULT).
+    ``execution_mode`` is accepted so a future policy can price attended runs
+    (dry_run / run_once) differently from unattended loops; today they share one
+    budget, and saying so here beats a branch that pretends otherwise.
     """
     if caller:
         return int(caller)
     if strategy:
         return int(strategy)
-    if execution_mode in ("dry_run", "run_once"):
-        return TIMEOUTS.tick_default
     return TIMEOUTS.tick_default
diff --git a/condor/web/models.py b/condor/web/models.py
index 107f5da4..7b69dd53 100644
--- a/condor/web/models.py
+++ b/condor/web/models.py
@@ -509,6 +509,23 @@ class GatewayPullRequest(BaseModel):
     image: str = "hummingbot/gateway:latest"
 
 
+class GatewayNetworkUpdateRequest(BaseModel):
+    # Partial network config (snake_case keys, e.g. {"node_url": "https://..."}).
+    # The Gateway validates values against its own JSON schema.
+    config: dict[str, Any]
+
+
+class GatewayWalletAddRequest(BaseModel):
+    chain: str
+    private_key: str
+    set_default: bool = False
+
+
+class GatewayWalletDefaultRequest(BaseModel):
+    chain: str
+    address: str
+
+
 class AddCredentialRequest(BaseModel):
     connector_name: str
     credentials: dict[str, Any]
diff --git a/condor/web/routes/agents.py b/condor/web/routes/agents.py
index 12290351..030420c9 100644
--- a/condor/web/routes/agents.py
+++ b/condor/web/routes/agents.py
@@ -101,6 +101,7 @@ class RunningInstance(BaseModel):
     total_amount_quote: float = 100.0
     trading_context: str = ""
     frequency_sec: int = 60
+    tick_timeout_sec: int = 600
     execution_mode: str = "loop"
     risk_limits: dict[str, Any] = {}
 
@@ -777,6 +778,7 @@ def _instance_from_engine(engine, perf_by_id: dict) -> RunningInstance:
         total_amount_quote=info.get("total_amount_quote", 100),
         trading_context=info.get("trading_context", ""),
         frequency_sec=info.get("frequency_sec", 60),
+        tick_timeout_sec=info.get("tick_timeout_sec", 600),
         agent_key=info.get("agent_key", ""),
         execution_mode=info.get("execution_mode", "loop"),
         risk_limits=info.get("risk_limits", {}),
diff --git a/condor/web/routes/settings.py b/condor/web/routes/settings.py
index cd82f4ad..43f70454 100644
--- a/condor/web/routes/settings.py
+++ b/condor/web/routes/settings.py
@@ -10,8 +10,11 @@
     AddCredentialRequest,
     AddServerRequest,
     CredentialInfo,
+    GatewayNetworkUpdateRequest,
     GatewayPullRequest,
     GatewayStartRequest,
+    GatewayWalletAddRequest,
+    GatewayWalletDefaultRequest,
     ServerInfo,
     UpdateServerRequest,
     WebUser,
@@ -282,6 +285,159 @@ async def gateway_logs(
         raise upstream_error("Failed to fetch gateway logs", e)
 
 
+# ── Gateway Networks (RPC) ──
+
+
+@router.get("/gateway/networks")
+async def gateway_networks(
+    server: str = Query(...),
+    user: WebUser = Depends(get_current_user),
+):
+    cm = get_config_manager()
+    if not cm.has_server_access(user.id, server):
+        raise HTTPException(status_code=403, detail="No access")
+    client = await _get_client(cm, server)
+    try:
+        result = await client.gateway.list_networks()
+        networks = result.get("networks", result) if isinstance(result, dict) else result
+        return {"networks": networks}
+    except Exception as e:
+        logger.exception("Failed to list gateway networks from '%s'", server)
+        raise upstream_error("Failed to list gateway networks", e)
+
+
+@router.get("/gateway/networks/{network_id}")
+async def gateway_network_config(
+    network_id: str,
+    server: str = Query(...),
+    user: WebUser = Depends(get_current_user),
+):
+    cm = get_config_manager()
+    if not cm.has_server_access(user.id, server):
+        raise HTTPException(status_code=403, detail="No access")
+    client = await _get_client(cm, server)
+    try:
+        config = await client.gateway.get_network_config(network_id)
+        return {"network_id": network_id, "config": config}
+    except Exception as e:
+        logger.exception(
+            "Failed to fetch gateway network config '%s' from '%s'", network_id, server
+        )
+        raise upstream_error("Failed to fetch network config", e)
+
+
+@router.post("/gateway/networks/{network_id}")
+async def gateway_network_update(
+    network_id: str,
+    req: GatewayNetworkUpdateRequest,
+    server: str = Query(...),
+    user: WebUser = Depends(get_current_user),
+):
+    cm = get_config_manager()
+    if not cm.has_server_access(user.id, server):
+        raise HTTPException(status_code=403, detail="No access")
+    client = await _get_client(cm, server)
+    try:
+        result = await client.gateway.update_network_config(network_id, req.config)
+        return {"updated": True, "network_id": network_id, "result": result}
+    except Exception as e:
+        logger.exception(
+            "Failed to update gateway network config '%s' on '%s'", network_id, server
+        )
+        raise upstream_error("Failed to update network config", e)
+
+
+# ── Gateway Wallets ──
+
+
+@router.get("/gateway/wallets")
+async def gateway_wallets(
+    server: str = Query(...),
+    user: WebUser = Depends(get_current_user),
+):
+    cm = get_config_manager()
+    if not cm.has_server_access(user.id, server):
+        raise HTTPException(status_code=403, detail="No access")
+    client = await _get_client(cm, server)
+    try:
+        wallets = await client.accounts.list_gateway_wallets()
+        return {"wallets": wallets}
+    except Exception as e:
+        logger.exception("Failed to list gateway wallets from '%s'", server)
+        raise upstream_error("Failed to list gateway wallets", e)
+
+
+@router.post("/gateway/wallets")
+async def gateway_wallet_add(
+    req: GatewayWalletAddRequest,
+    server: str = Query(...),
+    user: WebUser = Depends(get_current_user),
+):
+    cm = get_config_manager()
+    if not cm.has_server_access(user.id, server):
+        raise HTTPException(status_code=403, detail="No access")
+    client = await _get_client(cm, server)
+    try:
+        result = await client.accounts.add_gateway_wallet(
+            chain=req.chain, private_key=req.private_key
+        )
+        address = result.get("address") if isinstance(result, dict) else None
+        if req.set_default and address:
+            await client.accounts.set_default_gateway_wallet(
+                chain=req.chain, address=address
+            )
+        return {"added": True, "chain": req.chain, "address": address}
+    except Exception as e:
+        # Never include the request payload here — it carries the private key.
+        logger.exception(
+            "Failed to add gateway wallet on chain '%s' via '%s'", req.chain, server
+        )
+        raise upstream_error("Failed to add wallet", e)
+
+
+@router.post("/gateway/wallets/default")
+async def gateway_wallet_set_default(
+    req: GatewayWalletDefaultRequest,
+    server: str = Query(...),
+    user: WebUser = Depends(get_current_user),
+):
+    cm = get_config_manager()
+    if not cm.has_server_access(user.id, server):
+        raise HTTPException(status_code=403, detail="No access")
+    client = await _get_client(cm, server)
+    try:
+        result = await client.accounts.set_default_gateway_wallet(
+            chain=req.chain, address=req.address
+        )
+        return {"default": True, "chain": req.chain, "address": req.address, "result": result}
+    except Exception as e:
+        logger.exception(
+            "Failed to set default gateway wallet on '%s' via '%s'", req.chain, server
+        )
+        raise upstream_error("Failed to set default wallet", e)
+
+
+@router.delete("/gateway/wallets/{chain}/{address}")
+async def gateway_wallet_remove(
+    chain: str,
+    address: str,
+    server: str = Query(...),
+    user: WebUser = Depends(get_current_user),
+):
+    cm = get_config_manager()
+    if not cm.has_server_access(user.id, server):
+        raise HTTPException(status_code=403, detail="No access")
+    client = await _get_client(cm, server)
+    try:
+        result = await client.accounts.remove_gateway_wallet(chain=chain, address=address)
+        return {"removed": True, "chain": chain, "address": address, "result": result}
+    except Exception as e:
+        logger.exception(
+            "Failed to remove gateway wallet %s on '%s' via '%s'", address, chain, server
+        )
+        raise upstream_error("Failed to remove wallet", e)
+
+
 # ── Voice Preferences ──
 
 

From 53462be4fd2a41510948b1bdf5de48d3e299916c Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Wed, 12 Aug 2026 20:22:57 +0300
Subject: [PATCH 027/116] (feat) improve front wallet

---
 .../src/components/ConnectKeysOverlay.tsx     |   7 +-
 .../src/components/agent/AgentControls.tsx    |  24 +-
 .../src/components/agent/AgentOverviewTab.tsx |   4 +
 .../components/settings/ApiKeysSettings.tsx   | 241 +++++++++++++++++-
 .../settings/ConnectHyperliquid.tsx           |   2 +-
 .../components/settings/GatewaySettings.tsx   | 219 ++++++++++++++++
 frontend/src/hooks/useCredentials.ts          |  18 +-
 frontend/src/lib/api.ts                       |  65 +++++
 frontend/src/pages/Settings.tsx               |   2 +-
 9 files changed, 564 insertions(+), 18 deletions(-)

diff --git a/frontend/src/components/ConnectKeysOverlay.tsx b/frontend/src/components/ConnectKeysOverlay.tsx
index cace8df3..571d2391 100644
--- a/frontend/src/components/ConnectKeysOverlay.tsx
+++ b/frontend/src/components/ConnectKeysOverlay.tsx
@@ -19,10 +19,11 @@ export function ConnectKeysOverlay() {
 
           {/* Copy */}
           <h2 className="mb-2 text-xl font-bold text-[var(--color-text)]">
-            Connect Your Exchange
+            Connect an Exchange or Wallet
           </h2>
           <p className="mb-6 max-w-xs text-sm leading-relaxed text-[var(--color-text-muted)]">
-            Add your exchange API keys to unlock portfolio tracking, trading, and bot management.
+            Add exchange API keys or a DEX wallet to unlock portfolio tracking, trading, and bot
+            management.
           </p>
 
           {/* CTA */}
@@ -30,7 +31,7 @@ export function ConnectKeysOverlay() {
             onClick={() => navigate("/settings?tab=keys")}
             className="flex items-center gap-2 rounded-lg bg-[var(--color-primary)] px-6 py-2.5 text-sm font-semibold text-white transition-all hover:bg-[var(--color-primary-hover)] hover:shadow-lg hover:shadow-[var(--color-primary)]/20 active:scale-[0.98]"
           >
-            Connect API Keys
+            Connect Keys &amp; Wallets
             <ArrowRight className="h-4 w-4" />
           </button>
 
diff --git a/frontend/src/components/agent/AgentControls.tsx b/frontend/src/components/agent/AgentControls.tsx
index 81bae005..c5b0d027 100644
--- a/frontend/src/components/agent/AgentControls.tsx
+++ b/frontend/src/components/agent/AgentControls.tsx
@@ -40,6 +40,11 @@ export function StartSessionDialog({
   const [serverName, setServerName] = useState((agentConfig.server_name as string) || "");
   const [totalAmountQuote, setTotalAmountQuote] = useState(String(agentConfig.total_amount_quote ?? 100));
   const [frequencySec, setFrequencySec] = useState(String(agentConfig.frequency_sec ?? 60));
+  // 0 in the config means "use the backend default" (10 min); show the resolved
+  // number so the field never reads as an unlimited budget.
+  const [tickTimeoutSec, setTickTimeoutSec] = useState(
+    String(Number(agentConfig.tick_timeout_sec) || 600),
+  );
   const [maxPositionSize, setMaxPositionSize] = useState(String(riskDefaults.max_position_size_quote ?? 500));
   const [maxOpenExecutors, setMaxOpenExecutors] = useState(String(riskDefaults.max_open_executors ?? 5));
   const [maxDrawdown, setMaxDrawdown] = useState(String(riskDefaults.max_drawdown_pct ?? -1));
@@ -56,6 +61,7 @@ export function StartSessionDialog({
         server_name: serverName,
         total_amount_quote: Number(totalAmountQuote) || 100,
         frequency_sec: Number(frequencySec) || 60,
+        tick_timeout_sec: Number(tickTimeoutSec) || 600,
         execution_mode: executionMode,
         risk_limits: {
           max_position_size_quote: Number(maxPositionSize) || 500,
@@ -160,8 +166,8 @@ export function StartSessionDialog({
             </select>
           </div>
 
-          {/* Budget + Frequency row */}
-          <div className={`grid gap-4 ${executionMode === "loop" ? "grid-cols-2" : "grid-cols-1"}`}>
+          {/* Budget + Frequency + Tick timeout row */}
+          <div className={`grid gap-4 ${executionMode === "loop" ? "grid-cols-3" : "grid-cols-2"}`}>
             <div>
               <label className={labelClass}>
                 Total Amount Quote
@@ -190,6 +196,20 @@ export function StartSessionDialog({
                 />
               </div>
             )}
+            <div>
+              <label className={labelClass} title="Wall-clock budget for one tick's agent session">
+                <Clock className="h-3.5 w-3.5" />
+                Tick Timeout (sec)
+              </label>
+              <input
+                type="number"
+                min={30}
+                step={30}
+                value={tickTimeoutSec}
+                onChange={(e) => setTickTimeoutSec(e.target.value)}
+                className={inputClass}
+              />
+            </div>
           </div>
 
           {/* Risk Limits */}
diff --git a/frontend/src/components/agent/AgentOverviewTab.tsx b/frontend/src/components/agent/AgentOverviewTab.tsx
index 0675049a..f081b245 100644
--- a/frontend/src/components/agent/AgentOverviewTab.tsx
+++ b/frontend/src/components/agent/AgentOverviewTab.tsx
@@ -128,6 +128,10 @@ export function InstanceCard({ instance }: { instance: import("@/lib/api").Runni
           <span className="text-[var(--color-text-muted)]">frequency</span>
           <span className="text-[var(--color-text)]">{instance.frequency_sec}s</span>
         </div>
+        <div className="flex justify-between">
+          <span className="text-[var(--color-text-muted)]">tick timeout</span>
+          <span className="text-[var(--color-text)]">{instance.tick_timeout_sec}s</span>
+        </div>
         {Object.entries(riskLimits).map(([k, v]) => {
           // These are risk LIMITS (max_*), not current values — keep the "max"
           // so e.g. "open executors: 10" isn't misread as 10 executors open now.
diff --git a/frontend/src/components/settings/ApiKeysSettings.tsx b/frontend/src/components/settings/ApiKeysSettings.tsx
index 92032905..6ef641d5 100644
--- a/frontend/src/components/settings/ApiKeysSettings.tsx
+++ b/frontend/src/components/settings/ApiKeysSettings.tsx
@@ -6,16 +6,25 @@ import {
   Key,
   Loader2,
   Plus,
+  Star,
   Trash2,
+  Wallet,
   X,
 } from "lucide-react";
 import { useEffect, useMemo, useState } from "react";
 
 import { useServer } from "@/hooks/useServer";
-import { type ConnectorInfo, type CredentialInfo, api } from "@/lib/api";
+import { type ConnectorInfo, type CredentialInfo, type GatewayWalletGroup, api } from "@/lib/api";
 import { ConnectHyperliquid } from "./ConnectHyperliquid";
+import { ImportGatewayWallet, type WalletChain } from "./ImportGatewayWallet";
 
-type Step = "list" | "select-type" | "select-exchange" | "fill-fields" | "connect-hyperliquid";
+type Step =
+  | "list"
+  | "select-type"
+  | "select-exchange"
+  | "fill-fields"
+  | "connect-hyperliquid"
+  | "import-wallet";
 
 const isHyperliquid = (name: string) => name.startsWith("hyperliquid");
 
@@ -23,6 +32,7 @@ interface AddFlowState {
   step: Step;
   connectorType: string;
   connectorName: string;
+  walletChain: WalletChain | "";
   fields: Record<string, unknown>;
   values: Record<string, string>;
 }
@@ -31,10 +41,16 @@ const INITIAL_FLOW: AddFlowState = {
   step: "list",
   connectorType: "",
   connectorName: "",
+  walletChain: "",
   fields: {},
   values: {},
 };
 
+const WALLET_CHAINS: { chain: WalletChain; label: string }[] = [
+  { chain: "solana", label: "Solana" },
+  { chain: "ethereum", label: "Ethereum/EVM" },
+];
+
 // Substrings that mark a connector config field as a sensitive credential.
 // Connector keys vary (api_key, secret_key, passphrase, private_key, api_token,
 // mnemonic, seed, ...), so we match by substring on both the field name and type
@@ -60,6 +76,7 @@ export function ApiKeysSettings() {
   const qc = useQueryClient();
   const [flow, setFlow] = useState<AddFlowState>(INITIAL_FLOW);
   const [confirmDelete, setConfirmDelete] = useState<string | null>(null);
+  const [confirmDeleteWallet, setConfirmDeleteWallet] = useState<string | null>(null);
 
   const { data: credsData, isLoading: loadingCreds } = useQuery({
     queryKey: ["settings-credentials", server],
@@ -67,6 +84,23 @@ export function ApiKeysSettings() {
     enabled: !!server,
   });
 
+  // Gateway wallets — an error (e.g. Gateway not running) renders as a muted note, not a failure.
+  const { data: walletsData, error: walletsError } = useQuery({
+    queryKey: ["gateway-wallets", server],
+    queryFn: () => api.getGatewayWallets(server!),
+    enabled: !!server,
+    retry: false,
+  });
+
+  // Same query key as GatewaySettings so the status is shared across the two tabs.
+  const { data: gatewayStatus } = useQuery({
+    queryKey: ["gateway-status", server],
+    queryFn: () => api.getGatewayStatus(server!),
+    enabled: !!server,
+    retry: false,
+  });
+  const gatewayRunning = gatewayStatus?.running === true;
+
   const { data: connectorsData, isLoading: loadingConnectors } = useQuery({
     queryKey: ["settings-connectors", server, flow.connectorType],
     queryFn: () => api.getAvailableConnectors(server!, flow.connectorType || undefined),
@@ -110,6 +144,31 @@ export function ApiKeysSettings() {
     onSuccess: () => { invalidate(); setConfirmDelete(null); },
   });
 
+  const invalidateWallets = () => qc.invalidateQueries({ queryKey: ["gateway-wallets", server] });
+
+  const defaultWalletMut = useMutation({
+    mutationFn: (w: { chain: string; address: string }) => api.setDefaultGatewayWallet(server!, w),
+    onSuccess: invalidateWallets,
+  });
+
+  const deleteWalletMut = useMutation({
+    mutationFn: ({ chain, address }: { chain: string; address: string }) =>
+      api.removeGatewayWallet(server!, chain, address),
+    onSuccess: () => { invalidateWallets(); setConfirmDeleteWallet(null); },
+  });
+
+  const wallets = useMemo(
+    () =>
+      (walletsData?.wallets ?? []).flatMap((group: GatewayWalletGroup) =>
+        (group.walletAddresses ?? []).map((address) => ({
+          chain: group.chain,
+          address,
+          isDefault: address === group.default_address,
+        })),
+      ),
+    [walletsData],
+  );
+
   // Normalize credentials — API may return strings or objects
   const credentials: CredentialInfo[] = useMemo(() => {
     const raw = credsData?.credentials ?? [];
@@ -232,6 +291,57 @@ export function ApiKeysSettings() {
     );
   }
 
+  // ── Add wallet flow ──
+
+  if (flow.step === "import-wallet" && flow.walletChain) {
+    return (
+      <div className="space-y-4">
+        <button
+          onClick={() => setFlow(INITIAL_FLOW)}
+          className="flex items-center gap-1.5 text-xs text-[var(--color-text-muted)] hover:text-[var(--color-text)]"
+        >
+          <ArrowLeft className="h-3.5 w-3.5" /> Back
+        </button>
+        <div>
+          <h2 className="text-lg font-semibold text-[var(--color-text)]">Add Wallet to Gateway</h2>
+          <p className="mt-1 text-xs text-[var(--color-text-muted)]">
+            Gateway signs DEX transactions on your server, so it needs the wallet's private key.
+            Browser wallets never share private keys with apps — export the key manually and paste
+            it below.
+          </p>
+        </div>
+
+        {/* Chain tabs */}
+        <div className="flex gap-1 rounded-lg border border-[var(--color-border)] bg-[var(--color-surface)] p-1">
+          {WALLET_CHAINS.map(({ chain, label }) => (
+            <button
+              key={chain}
+              onClick={() => setFlow({ ...flow, walletChain: chain })}
+              className={`flex-1 rounded-md px-3 py-1.5 text-sm font-medium transition-colors ${
+                flow.walletChain === chain
+                  ? "bg-[var(--color-primary)]/15 text-[var(--color-primary)]"
+                  : "text-[var(--color-text-muted)] hover:bg-[var(--color-surface-hover)] hover:text-[var(--color-text)]"
+              }`}
+            >
+              {label}
+            </button>
+          ))}
+        </div>
+
+        <ImportGatewayWallet
+          key={flow.walletChain}
+          server={server}
+          chain={flow.walletChain}
+          onBack={() => setFlow(INITIAL_FLOW)}
+          onDone={() => {
+            invalidateWallets();
+            setFlow(INITIAL_FLOW);
+          }}
+        />
+      </div>
+    );
+  }
+
   if (flow.step === "select-exchange") {
     const connectors: ConnectorInfo[] = [...(connectorsData?.connectors ?? [])].sort((a, b) =>
       a.name.localeCompare(b.name),
@@ -378,14 +488,30 @@ export function ApiKeysSettings() {
     <div className="space-y-4">
       <div className="flex items-center justify-between">
         <p className="text-sm text-[var(--color-text-muted)]">
-          {credentials.length} credential{credentials.length !== 1 ? "s" : ""} configured
+          {credentials.length} credential{credentials.length !== 1 ? "s" : ""}
+          {wallets.length > 0 && `, ${wallets.length} wallet${wallets.length !== 1 ? "s" : ""}`}{" "}
+          configured
         </p>
-        <button
-          onClick={() => setFlow({ ...INITIAL_FLOW, step: "select-type" })}
-          className="flex items-center gap-1.5 rounded-md bg-[var(--color-primary)] px-3 py-1.5 text-xs font-medium text-white transition-colors hover:bg-[var(--color-primary)]/80"
-        >
-          <Plus className="h-3.5 w-3.5" /> Add API Key
-        </button>
+        <div className="flex items-center gap-2">
+          <button
+            onClick={() =>
+              setFlow({ ...INITIAL_FLOW, step: "import-wallet", walletChain: "solana" })
+            }
+            disabled={!gatewayRunning}
+            title={
+              gatewayRunning ? undefined : "Gateway is not running — start it from the Gateway tab."
+            }
+            className="flex items-center gap-1.5 rounded-md border border-[var(--color-border)] bg-[var(--color-surface)] px-3 py-1.5 text-xs font-medium text-[var(--color-text)] transition-colors hover:border-[var(--color-border-hover)] hover:bg-[var(--color-surface-hover)] disabled:cursor-not-allowed disabled:opacity-50 disabled:hover:border-[var(--color-border)] disabled:hover:bg-[var(--color-surface)]"
+          >
+            <Wallet className="h-3.5 w-3.5" /> Add Wallet
+          </button>
+          <button
+            onClick={() => setFlow({ ...INITIAL_FLOW, step: "select-type" })}
+            className="flex items-center gap-1.5 rounded-md bg-[var(--color-primary)] px-3 py-1.5 text-xs font-medium text-white transition-colors hover:bg-[var(--color-primary)]/80"
+          >
+            <Plus className="h-3.5 w-3.5" /> Add API Key
+          </button>
+        </div>
       </div>
 
       {loadingCreds ? (
@@ -455,6 +581,103 @@ export function ApiKeysSettings() {
           ))}
         </div>
       )}
+
+      {/* ── Gateway wallets ── */}
+      <div>
+        <h3 className="mb-2 text-xs font-semibold uppercase tracking-wider text-[var(--color-text-muted)]">
+          Wallets
+        </h3>
+        {walletsError ? (
+          <p className="rounded-lg border border-[var(--color-border)] bg-[var(--color-surface)] p-3 text-xs text-[var(--color-text-muted)]">
+            Gateway is not reachable — start it from the Gateway tab to manage wallets.
+          </p>
+        ) : wallets.length === 0 ? (
+          <p className="rounded-lg border border-[var(--color-border)] bg-[var(--color-surface)] p-3 text-xs text-[var(--color-text-muted)]">
+            No wallets in Gateway. Add one to trade on DEXs.
+          </p>
+        ) : (
+          <div className="space-y-2">
+            {wallets.map((w) => {
+              const walletKey = `${w.chain}:${w.address}`;
+              return (
+                <div
+                  key={walletKey}
+                  className="flex items-center justify-between gap-3 rounded-lg border border-[var(--color-border)] bg-[var(--color-surface)] p-3 transition-colors hover:border-[var(--color-border-hover)]"
+                >
+                  <div className="flex min-w-0 items-center gap-3">
+                    <div className="flex h-8 w-8 shrink-0 items-center justify-center rounded-md bg-[var(--color-surface-hover)] text-[var(--color-text-muted)]">
+                      <Wallet className="h-4 w-4" />
+                    </div>
+                    <div className="min-w-0">
+                      <div className="flex items-center gap-1.5">
+                        <span className="text-xs font-medium capitalize text-[var(--color-text)]">
+                          {w.chain}
+                        </span>
+                        {w.isDefault && (
+                          <span
+                            className="flex items-center gap-0.5 rounded bg-[var(--color-primary)]/10 px-1.5 py-0.5 text-[10px] font-medium text-[var(--color-primary)]"
+                            title="Default wallet for this chain"
+                          >
+                            <Star className="h-2.5 w-2.5" /> default
+                          </span>
+                        )}
+                      </div>
+                      <p className="truncate font-mono text-xs text-[var(--color-text-muted)]">
+                        {w.address}
+                      </p>
+                    </div>
+                  </div>
+
+                  <div className="flex shrink-0 items-center gap-1">
+                    {!w.isDefault && confirmDeleteWallet !== walletKey && (
+                      <button
+                        onClick={() =>
+                          defaultWalletMut.mutate({ chain: w.chain, address: w.address })
+                        }
+                        disabled={defaultWalletMut.isPending}
+                        className="rounded p-1.5 text-[var(--color-text-muted)] hover:bg-[var(--color-surface-hover)] hover:text-[var(--color-primary)] disabled:opacity-50"
+                        title="Set as default wallet for this chain"
+                      >
+                        <Star className="h-3.5 w-3.5" />
+                      </button>
+                    )}
+                    {confirmDeleteWallet === walletKey ? (
+                      <>
+                        <button
+                          onClick={() =>
+                            deleteWalletMut.mutate({ chain: w.chain, address: w.address })
+                          }
+                          disabled={deleteWalletMut.isPending}
+                          className="rounded p-1.5 text-[var(--color-red)] hover:bg-red-500/10"
+                          title="Confirm remove"
+                        >
+                          <Check className="h-3.5 w-3.5" />
+                        </button>
+                        <button
+                          onClick={() => setConfirmDeleteWallet(null)}
+                          className="rounded p-1.5 text-[var(--color-text-muted)] hover:bg-[var(--color-surface-hover)]"
+                          title="Cancel remove"
+                          aria-label="Cancel remove"
+                        >
+                          <X className="h-3.5 w-3.5" />
+                        </button>
+                      </>
+                    ) : (
+                      <button
+                        onClick={() => setConfirmDeleteWallet(walletKey)}
+                        className="rounded p-1.5 text-[var(--color-text-muted)] hover:bg-[var(--color-surface-hover)] hover:text-[var(--color-red)]"
+                        title="Remove wallet from Gateway"
+                      >
+                        <Trash2 className="h-3.5 w-3.5" />
+                      </button>
+                    )}
+                  </div>
+                </div>
+              );
+            })}
+          </div>
+        )}
+      </div>
     </div>
   );
 }
diff --git a/frontend/src/components/settings/ConnectHyperliquid.tsx b/frontend/src/components/settings/ConnectHyperliquid.tsx
index 82b98050..e91c28a2 100644
--- a/frontend/src/components/settings/ConnectHyperliquid.tsx
+++ b/frontend/src/components/settings/ConnectHyperliquid.tsx
@@ -147,7 +147,7 @@ export function ConnectHyperliquid({
         const reason = (failed[0].result as PromiseRejectedResult).reason as { message?: string };
         setPartial(
           `Connected, but ${failed.map((f) => f.name).join(", ")} could not be saved ` +
-            `(${reason?.message || "validation failed"}). Retry it from the API Keys list — no re-signing needed.`,
+            `(${reason?.message || "validation failed"}). Retry it from the Keys and Wallets list — no re-signing needed.`,
         );
       }
 
diff --git a/frontend/src/components/settings/GatewaySettings.tsx b/frontend/src/components/settings/GatewaySettings.tsx
index d6b7cd42..555f037c 100644
--- a/frontend/src/components/settings/GatewaySettings.tsx
+++ b/frontend/src/components/settings/GatewaySettings.tsx
@@ -4,6 +4,7 @@ import {
   ChevronDown,
   ChevronRight,
   Download,
+  Globe,
   Loader2,
   Play,
   RefreshCw,
@@ -40,6 +41,221 @@ function formatDuration(sec: number): string {
   return `${Math.floor(sec / 60)}m ${Math.floor(sec % 60)}s`;
 }
 
+// Config keys that describe the network itself and must not be edited from the UI.
+const READONLY_NETWORK_KEYS = new Set([
+  "chain_id",
+  "native_currency_symbol",
+  "gecko_id",
+  "default_network",
+  "default_networks",
+  "default_wallet",
+]);
+
+function NetworkConfigEditor({ server, networkId }: { server: string; networkId: string }) {
+  const qc = useQueryClient();
+  const [draft, setDraft] = useState<Record<string, string>>({});
+
+  const { data, isLoading, error } = useQuery({
+    queryKey: ["gateway-network-config", server, networkId],
+    queryFn: () => api.getGatewayNetworkConfig(server, networkId),
+  });
+
+  const saveMut = useMutation({
+    mutationFn: (config: Record<string, unknown>) =>
+      api.updateGatewayNetworkConfig(server, networkId, config),
+    onSuccess: () => {
+      setDraft({});
+      qc.invalidateQueries({ queryKey: ["gateway-network-config", server, networkId] });
+    },
+  });
+
+  if (isLoading) {
+    return (
+      <div className="flex items-center gap-2 p-3 text-xs text-[var(--color-text-muted)]">
+        <Loader2 className="h-3 w-3 animate-spin" /> Loading config...
+      </div>
+    );
+  }
+  if (error || !data) {
+    return (
+      <p className="p-3 text-xs text-[var(--color-red)]">
+        Failed to load config{error ? `: ${(error as Error).message}` : ""}
+      </p>
+    );
+  }
+
+  const config = data.config ?? {};
+  const editableEntries = Object.entries(config).filter(
+    ([key, value]) =>
+      !READONLY_NETWORK_KEYS.has(key) &&
+      (typeof value === "string" || typeof value === "number" || typeof value === "boolean"),
+  );
+
+  const changed = Object.entries(draft).filter(
+    ([key, value]) => value !== String(config[key] ?? ""),
+  );
+
+  const save = () => {
+    const updates: Record<string, unknown> = {};
+    for (const [key, value] of changed) {
+      const original = config[key];
+      if (typeof original === "number") {
+        const num = Number(value);
+        if (isNaN(num)) continue;
+        updates[key] = num;
+      } else if (typeof original === "boolean") {
+        updates[key] = value === "true";
+      } else {
+        updates[key] = value;
+      }
+    }
+    if (Object.keys(updates).length > 0) saveMut.mutate(updates);
+  };
+
+  return (
+    <div className="space-y-2 p-3">
+      {editableEntries.map(([key, value]) => {
+        const current = draft[key] ?? String(value ?? "");
+        const isDirty = draft[key] !== undefined && draft[key] !== String(value ?? "");
+        return (
+          <div key={key} className="flex items-center gap-2">
+            <label
+              className="w-44 shrink-0 truncate font-mono text-xs text-[var(--color-text-muted)]"
+              title={key}
+            >
+              {key}
+            </label>
+            {typeof value === "boolean" ? (
+              <input
+                type="checkbox"
+                checked={current === "true"}
+                onChange={(e) => setDraft((d) => ({ ...d, [key]: String(e.target.checked) }))}
+                className="h-3.5 w-3.5"
+              />
+            ) : (
+              <input
+                value={current}
+                onChange={(e) => setDraft((d) => ({ ...d, [key]: e.target.value }))}
+                className={`flex-1 rounded-md border bg-[var(--color-bg)] px-2 py-1 font-mono text-xs text-[var(--color-text)] focus:border-[var(--color-primary)] focus:outline-none ${
+                  isDirty ? "border-[var(--color-primary)]/60" : "border-[var(--color-border)]"
+                }`}
+              />
+            )}
+          </div>
+        );
+      })}
+
+      <div className="flex items-center gap-2 pt-1">
+        <button
+          onClick={save}
+          disabled={changed.length === 0 || saveMut.isPending}
+          className="flex items-center gap-1.5 rounded-md bg-[var(--color-primary)] px-3 py-1.5 text-xs font-medium text-white transition-colors hover:bg-[var(--color-primary)]/80 disabled:opacity-50"
+        >
+          {saveMut.isPending ? <Loader2 className="h-3 w-3 animate-spin" /> : <Check className="h-3 w-3" />}
+          Save {changed.length > 0 ? `(${changed.length})` : ""}
+        </button>
+        {changed.length > 0 && (
+          <button
+            onClick={() => setDraft({})}
+            className="rounded-md px-2 py-1.5 text-xs text-[var(--color-text-muted)] hover:bg-[var(--color-surface-hover)]"
+          >
+            Discard
+          </button>
+        )}
+        {saveMut.isSuccess && changed.length === 0 && (
+          <span className="flex items-center gap-1 text-xs text-emerald-400">
+            <Check className="h-3 w-3" /> Saved
+          </span>
+        )}
+        {saveMut.error && (
+          <span className="text-xs text-[var(--color-red)]">{saveMut.error.message}</span>
+        )}
+      </div>
+    </div>
+  );
+}
+
+function GatewayNetworks({ server, running }: { server: string; running: boolean }) {
+  const [open, setOpen] = useState(false);
+  const [expanded, setExpanded] = useState<string | null>(null);
+
+  const { data, isLoading, error } = useQuery({
+    queryKey: ["gateway-networks", server],
+    queryFn: () => api.getGatewayNetworks(server),
+    enabled: open && running,
+  });
+
+  const networks = data?.networks ?? [];
+  const chains = [...new Set(networks.map((n) => n.chain))].sort();
+
+  return (
+    <div className="rounded-lg border border-[var(--color-border)] bg-[var(--color-surface)]">
+      <button
+        onClick={() => setOpen(!open)}
+        className="flex w-full items-center justify-between p-3 text-sm text-[var(--color-text)] hover:bg-[var(--color-surface-hover)]"
+      >
+        <div className="flex items-center gap-2">
+          <Globe className="h-4 w-4" />
+          <span className="font-medium">Networks & RPC</span>
+        </div>
+        {open ? <ChevronDown className="h-4 w-4" /> : <ChevronRight className="h-4 w-4" />}
+      </button>
+      {open && (
+        <div className="border-t border-[var(--color-border)] p-3 space-y-3">
+          {!running ? (
+            <p className="text-xs text-[var(--color-text-muted)]">
+              Start the Gateway to view and edit network configuration.
+            </p>
+          ) : isLoading ? (
+            <div className="flex items-center gap-2 text-xs text-[var(--color-text-muted)]">
+              <Loader2 className="h-3 w-3 animate-spin" /> Loading networks...
+            </div>
+          ) : error ? (
+            <p className="text-xs text-[var(--color-red)]">{(error as Error).message}</p>
+          ) : (
+            chains.map((chain) => (
+              <div key={chain}>
+                <p className="mb-1.5 text-xs font-semibold uppercase tracking-wide text-[var(--color-text-muted)]">
+                  {chain}
+                </p>
+                <div className="space-y-1">
+                  {networks
+                    .filter((n) => n.chain === chain)
+                    .map((n) => (
+                      <div
+                        key={n.network_id}
+                        className="rounded-md border border-[var(--color-border)] bg-[var(--color-bg)]"
+                      >
+                        <button
+                          onClick={() =>
+                            setExpanded(expanded === n.network_id ? null : n.network_id)
+                          }
+                          className="flex w-full items-center justify-between px-3 py-2 text-xs text-[var(--color-text)] hover:bg-[var(--color-surface-hover)]"
+                        >
+                          <span className="font-mono">{n.network}</span>
+                          {expanded === n.network_id ? (
+                            <ChevronDown className="h-3 w-3" />
+                          ) : (
+                            <ChevronRight className="h-3 w-3" />
+                          )}
+                        </button>
+                        {expanded === n.network_id && (
+                          <div className="border-t border-[var(--color-border)]">
+                            <NetworkConfigEditor server={server} networkId={n.network_id} />
+                          </div>
+                        )}
+                      </div>
+                    ))}
+                </div>
+              </div>
+            ))
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
+
 export function GatewaySettings() {
   const { server } = useServer();
   const qc = useQueryClient();
@@ -415,6 +631,9 @@ export function GatewaySettings() {
         </div>
       )}
 
+      {/* Networks & RPC */}
+      <GatewayNetworks server={server} running={running} />
+
       {/* Logs */}
       <div className="rounded-lg border border-[var(--color-border)] bg-[var(--color-surface)]">
         <button
diff --git a/frontend/src/hooks/useCredentials.ts b/frontend/src/hooks/useCredentials.ts
index 99753bc4..210f67d8 100644
--- a/frontend/src/hooks/useCredentials.ts
+++ b/frontend/src/hooks/useCredentials.ts
@@ -6,15 +6,29 @@ import { api } from "@/lib/api";
 export function useCredentials() {
   const { server } = useServer();
 
-  const { data, isLoading } = useQuery({
+  const { data, isLoading: credsLoading } = useQuery({
     queryKey: ["settings-credentials", server],
     queryFn: () => api.getCredentials(server!),
     enabled: !!server,
     staleTime: 30000,
   });
 
+  // A Gateway wallet (Solana/Ethereum) unlocks the portfolio just like a CEX key does.
+  // Errors (e.g. Gateway not running) simply count as "no wallets".
+  const { data: walletsData, isLoading: walletsLoading } = useQuery({
+    queryKey: ["gateway-wallets", server],
+    queryFn: () => api.getGatewayWallets(server!),
+    enabled: !!server,
+    staleTime: 30000,
+    retry: false,
+  });
+
   const credentials = data?.credentials ?? [];
-  const hasKeys = credentials.length > 0;
+  const hasWallets = (walletsData?.wallets ?? []).some(
+    (g) => (g.walletAddresses ?? []).length > 0,
+  );
+  const hasKeys = credentials.length > 0 || hasWallets;
+  const isLoading = credsLoading || walletsLoading;
 
   return { hasKeys, isLoading, credentials };
 }
diff --git a/frontend/src/lib/api.ts b/frontend/src/lib/api.ts
index 8c16966e..a5bcbfbf 100644
--- a/frontend/src/lib/api.ts
+++ b/frontend/src/lib/api.ts
@@ -383,6 +383,8 @@ export interface RunningInstance {
   total_amount_quote: number;
   trading_context: string;
   frequency_sec: number;
+  /** Wall-clock budget for one tick's agent session, in seconds. */
+  tick_timeout_sec: number;
   execution_mode: "dry_run" | "run_once" | "loop";
   risk_limits: Record<string, unknown>;
 }
@@ -773,6 +775,23 @@ export interface GatewayStatus {
   container_status?: string;
 }
 
+export interface GatewayNetworkInfo {
+  network_id: string;
+  chain: string;
+  network: string;
+}
+
+export interface GatewayNetworkConfig {
+  network_id: string;
+  config: Record<string, unknown>;
+}
+
+export interface GatewayWalletGroup {
+  chain: string;
+  walletAddresses: string[];
+  default_address?: string;
+}
+
 export interface CredentialInfo {
   connector_name: string;
   connector_type: string;
@@ -1745,6 +1764,52 @@ export const api = {
   getGatewayLogs: (server: string) =>
     apiFetch<{ logs: string }>(`/api/v1/settings/gateway/logs?server=${encodeURIComponent(server)}`),
 
+  getGatewayNetworks: (server: string) =>
+    apiFetch<{ networks: GatewayNetworkInfo[] }>(
+      `/api/v1/settings/gateway/networks?server=${encodeURIComponent(server)}`,
+    ),
+
+  getGatewayNetworkConfig: (server: string, networkId: string) =>
+    apiFetch<GatewayNetworkConfig>(
+      `/api/v1/settings/gateway/networks/${encodeURIComponent(networkId)}?server=${encodeURIComponent(server)}`,
+    ),
+
+  updateGatewayNetworkConfig: (
+    server: string,
+    networkId: string,
+    config: Record<string, unknown>,
+  ) =>
+    apiFetch<{ updated: boolean; network_id: string }>(
+      `/api/v1/settings/gateway/networks/${encodeURIComponent(networkId)}?server=${encodeURIComponent(server)}`,
+      { method: "POST", body: JSON.stringify({ config }) },
+    ),
+
+  getGatewayWallets: (server: string) =>
+    apiFetch<{ wallets: GatewayWalletGroup[] }>(
+      `/api/v1/settings/gateway/wallets?server=${encodeURIComponent(server)}`,
+    ),
+
+  addGatewayWallet: (
+    server: string,
+    data: { chain: string; private_key: string; set_default?: boolean },
+  ) =>
+    apiFetch<{ added: boolean; chain: string; address: string | null }>(
+      `/api/v1/settings/gateway/wallets?server=${encodeURIComponent(server)}`,
+      { method: "POST", body: JSON.stringify(data) },
+    ),
+
+  setDefaultGatewayWallet: (server: string, data: { chain: string; address: string }) =>
+    apiFetch<{ default: boolean }>(
+      `/api/v1/settings/gateway/wallets/default?server=${encodeURIComponent(server)}`,
+      { method: "POST", body: JSON.stringify(data) },
+    ),
+
+  removeGatewayWallet: (server: string, chain: string, address: string) =>
+    apiFetch<{ removed: boolean }>(
+      `/api/v1/settings/gateway/wallets/${encodeURIComponent(chain)}/${encodeURIComponent(address)}?server=${encodeURIComponent(server)}`,
+      { method: "DELETE" },
+    ),
+
   getCredentials: (server: string) =>
     apiFetch<{ credentials: (CredentialInfo | string)[] }>(`/api/v1/settings/credentials?server=${encodeURIComponent(server)}`),
 
diff --git a/frontend/src/pages/Settings.tsx b/frontend/src/pages/Settings.tsx
index 1d0677b0..da9a97b4 100644
--- a/frontend/src/pages/Settings.tsx
+++ b/frontend/src/pages/Settings.tsx
@@ -11,7 +11,7 @@ import { useAuth } from "@/lib/auth";
 const TABS = [
   { key: "servers", label: "Servers" },
   { key: "gateway", label: "Gateway" },
-  { key: "keys", label: "API Keys" },
+  { key: "keys", label: "Keys and Wallets" },
   { key: "llm", label: "LLM Endpoints" },
   { key: "voice", label: "Voice & AI" },
 ] as const;

From e5c4835b290394ee330905b81f0b6c54e9c95897 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Wed, 12 Aug 2026 20:23:09 +0300
Subject: [PATCH 028/116] (feat) add runtime

---
 mcp_servers/condor/server.py        |  4 +++-
 tests/runtime/test_runtime_state.py | 32 +++++++++++++++++++++++++++++
 2 files changed, 35 insertions(+), 1 deletion(-)

diff --git a/mcp_servers/condor/server.py b/mcp_servers/condor/server.py
index 657cd025..37d41b7c 100644
--- a/mcp_servers/condor/server.py
+++ b/mcp_servers/condor/server.py
@@ -637,7 +637,9 @@ async def manage_trading_agent(
         skills: List of optional skill names to enable (for create/update_strategy).
         config: Agent config overrides (for create/update_strategy/start) or routine config (for run_routine).
             For start_agent, supports: agent_key (override strategy default), model_base_url (for LM Studio/vLLM),
-            execution_mode, frequency_sec, total_amount_quote, trading_context, risk_limits, server_name, max_ticks.
+            execution_mode, frequency_sec, tick_timeout_sec (wall-clock budget for one tick's
+            agent session; 0 = runtime default of 600s), total_amount_quote, trading_context,
+            risk_limits, server_name, max_ticks.
         tools: Tool-name allowlist for the agent (create/update_agent). Empty/None = unrestricted.
         when_to_consult: One-line hint describing when to route work to this agent (create/update_agent). Purely for routing — every agent is consultable with or without it; it falls back to the description.
         server_required: Whether the agent needs a Hummingbot server (create/update_agent). Default True.
diff --git a/tests/runtime/test_runtime_state.py b/tests/runtime/test_runtime_state.py
index 81b32326..7f39bfe8 100644
--- a/tests/runtime/test_runtime_state.py
+++ b/tests/runtime/test_runtime_state.py
@@ -226,6 +226,38 @@ def test_resolve_tick_timeout_precedence():
     assert resolve_tick_timeout("loop") == TimeoutPolicy().tick_default
 
 
+def test_agent_session_budget_defaults_to_ten_minutes():
+    """The out-of-the-box budget for one agent session is 10 minutes."""
+    assert TimeoutPolicy().tick_default == 600
+    assert resolve_tick_timeout("dry_run") == 600
+
+
+def test_agent_session_budget_is_configurable_by_env(monkeypatch):
+    monkeypatch.setenv("CONDOR_TIMEOUT_TICK_DEFAULT", "1200")
+    assert TimeoutPolicy.load().tick_default == 1200
+
+
+def test_tick_timeout_sec_is_a_run_config_field():
+    """A run can widen its own budget without touching the deployment env."""
+    from condor.agents.config import AgentConfig
+
+    assert AgentConfig().tick_timeout_sec == 0  # 0 = defer to the policy
+    cfg = AgentConfig.from_dict({"tick_timeout_sec": 1800})
+    assert resolve_tick_timeout(strategy=cfg.tick_timeout_sec) == 1800
+
+
+def test_engine_tick_has_no_hardcoded_budget():
+    """engine/_tick and the shutdown pass resolve the budget, not a literal."""
+    import inspect
+
+    from condor.agents import engine, shutdown
+
+    tick_src = inspect.getsource(engine.TickEngine._tick)
+    assert "resolve_tick_timeout" in tick_src
+    assert "asyncio.timeout(300)" not in tick_src
+    assert "asyncio.timeout(300)" not in inspect.getsource(shutdown)
+
+
 def test_timeouts_are_sourced_from_the_policy():
     """The migrated call sites read the policy instead of their own literal."""
     from condor.runtime import sessions

From 9a57bdf85cf1a57bbeaca3c7a99e40030182e9a2 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Wed, 12 Aug 2026 20:23:19 +0300
Subject: [PATCH 029/116] (feat) add gateway wallet

---
 .../settings/ImportGatewayWallet.tsx          | 184 ++++++++++++++++++
 1 file changed, 184 insertions(+)
 create mode 100644 frontend/src/components/settings/ImportGatewayWallet.tsx

diff --git a/frontend/src/components/settings/ImportGatewayWallet.tsx b/frontend/src/components/settings/ImportGatewayWallet.tsx
new file mode 100644
index 00000000..75afcc05
--- /dev/null
+++ b/frontend/src/components/settings/ImportGatewayWallet.tsx
@@ -0,0 +1,184 @@
+import { AlertCircle, Check, Loader2 } from "lucide-react";
+import { useMemo, useState } from "react";
+import { privateKeyToAccount } from "viem/accounts";
+
+import { api } from "@/lib/api";
+
+export type WalletChain = "solana" | "ethereum";
+
+// Browser wallets (Phantom, MetaMask, Rabby) never expose private keys to websites — that's by
+// design, and why this flow is a manual export + paste instead of a one-click "Connect".
+const EXPORT_INSTRUCTIONS: Record<WalletChain, { wallet: string; steps: string }[]> = {
+  solana: [
+    {
+      wallet: "Phantom",
+      steps: "Settings → Manage Accounts → select account → Show Private Key",
+    },
+  ],
+  ethereum: [
+    { wallet: "MetaMask", steps: "⋮ menu → Account details → Show private key" },
+    { wallet: "Rabby", steps: "Click address → Address Detail → Backup Private Key" },
+  ],
+};
+
+const EVM_KEY_RE = /^(0x)?[0-9a-fA-F]{64}$/;
+// Phantom exports the keypair as base58, typically 87–88 chars.
+const SOLANA_KEY_RE = /^[1-9A-HJ-NP-Za-km-z]{64,120}$/;
+
+export function ImportGatewayWallet({
+  server,
+  chain,
+  onBack,
+  onDone,
+}: {
+  server: string;
+  chain: WalletChain;
+  onBack: () => void;
+  onDone: () => void;
+}) {
+  const [key, setKey] = useState("");
+  const [setDefault, setSetDefault] = useState(true);
+  const [saving, setSaving] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [importedAddress, setImportedAddress] = useState<string | null>(null);
+
+  const trimmed = key.trim();
+
+  // For Ethereum we can derive the address locally before importing, so the user sees exactly
+  // which account the pasted key controls. Solana derivation would need an ed25519 lib — the
+  // imported address is shown from Gateway's response instead.
+  const derived = useMemo(() => {
+    if (chain !== "ethereum" || !EVM_KEY_RE.test(trimmed)) return null;
+    try {
+      const hex = (trimmed.startsWith("0x") ? trimmed : `0x${trimmed}`) as `0x${string}`;
+      return privateKeyToAccount(hex).address;
+    } catch {
+      return null;
+    }
+  }, [chain, trimmed]);
+
+  const keyLooksValid = chain === "ethereum" ? derived !== null : SOLANA_KEY_RE.test(trimmed);
+
+  async function handleImport() {
+    setError(null);
+    setSaving(true);
+    try {
+      const privateKey =
+        chain === "ethereum" && !trimmed.startsWith("0x") ? `0x${trimmed}` : trimmed;
+      const res = await api.addGatewayWallet(server, {
+        chain,
+        private_key: privateKey,
+        set_default: setDefault,
+      });
+      setImportedAddress(res.address ?? derived ?? "");
+      setKey("");
+      window.setTimeout(onDone, 1500);
+    } catch (e) {
+      const err = e as { message?: string };
+      setError(err.message || "Failed to import wallet into Gateway.");
+    } finally {
+      setSaving(false);
+    }
+  }
+
+  return (
+    <div className="space-y-4">
+      <div className="rounded-lg border border-[var(--color-border)] bg-[var(--color-surface)] p-3">
+        <p className="mb-1.5 text-xs font-medium text-[var(--color-text)]">
+          Where to find your private key
+        </p>
+        <ul className="space-y-1 text-xs text-[var(--color-text-muted)]">
+          {EXPORT_INSTRUCTIONS[chain].map(({ wallet, steps }) => (
+            <li key={wallet}>
+              <span className="text-[var(--color-text)]">{wallet}:</span> {steps}
+            </li>
+          ))}
+        </ul>
+      </div>
+
+      {importedAddress !== null ? (
+        <div className="flex items-start gap-2 rounded-lg border border-[var(--color-primary)]/30 bg-[var(--color-primary)]/5 p-3 text-sm text-[var(--color-text)]">
+          <Check className="mt-0.5 h-4 w-4 shrink-0 text-[var(--color-primary)]" />
+          <span>
+            Wallet imported into Gateway.
+            {importedAddress && (
+              <span className="ml-1 break-all font-mono text-xs text-[var(--color-text-muted)]">
+                {importedAddress}
+              </span>
+            )}
+          </span>
+        </div>
+      ) : (
+        <div className="space-y-3">
+          <div>
+            <label className="mb-1 block text-xs text-[var(--color-text-muted)]">Private key</label>
+            <input
+              type="password"
+              autoComplete="off"
+              value={key}
+              onChange={(e) => setKey(e.target.value)}
+              disabled={saving}
+              placeholder={
+                chain === "ethereum" ? "0x… (64 hex characters)" : "Base58 private key from Phantom"
+              }
+              className="w-full rounded-md border border-[var(--color-border)] bg-[var(--color-bg)] px-3 py-1.5 font-mono text-sm text-[var(--color-text)] focus:border-[var(--color-primary)] focus:outline-none disabled:opacity-50"
+            />
+            {derived && (
+              <p className="mt-1 break-all font-mono text-xs text-[var(--color-text-muted)]">
+                Will import: {derived}
+              </p>
+            )}
+            {trimmed.length > 0 && !keyLooksValid && (
+              <p className="mt-1 text-xs text-[var(--color-red)]">
+                {chain === "ethereum"
+                  ? "Expected a 64-character hex private key (with or without 0x prefix)."
+                  : "Expected a base58 private key (no 0x, no brackets)."}
+              </p>
+            )}
+          </div>
+
+          <label className="flex cursor-pointer items-center gap-2 text-xs text-[var(--color-text)]">
+            <input
+              type="checkbox"
+              checked={setDefault}
+              onChange={(e) => setSetDefault(e.target.checked)}
+              disabled={saving}
+              className="h-3.5 w-3.5 accent-[var(--color-primary)]"
+            />
+            Set as default wallet for this chain
+          </label>
+
+          <p className="text-xs text-[var(--color-text-muted)]">
+            The key is sent to your Hummingbot API server and stored encrypted by the Gateway. It is
+            never persisted by this dashboard.
+          </p>
+
+          {error && (
+            <div className="flex items-start gap-2 rounded-md border border-[var(--color-red)]/30 bg-red-500/5 p-2.5 text-xs text-[var(--color-red)]">
+              <AlertCircle className="mt-0.5 h-3.5 w-3.5 shrink-0" />
+              <span>{error}</span>
+            </div>
+          )}
+
+          <div className="flex items-center gap-2">
+            <button
+              onClick={handleImport}
+              disabled={saving || !keyLooksValid}
+              className="flex items-center gap-1.5 rounded-md bg-[var(--color-primary)] px-4 py-1.5 text-xs font-medium text-white transition-colors hover:bg-[var(--color-primary)]/80 disabled:opacity-50"
+            >
+              {saving && <Loader2 className="h-3 w-3 animate-spin" />}
+              Import into Gateway
+            </button>
+            <button
+              onClick={onBack}
+              disabled={saving}
+              className="rounded-md px-3 py-1.5 text-xs text-[var(--color-text-muted)] hover:bg-[var(--color-surface-hover)] disabled:opacity-50"
+            >
+              Cancel
+            </button>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}

From 6a91de7a7599adbc0622a6ecb2d40273962dc01f Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Thu, 13 Aug 2026 10:06:47 +0300
Subject: [PATCH 030/116] (feat) candles: pin a chart to one DEX pool
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The candle channel gains an optional sixth segment, the pool address:
`candles:{server}:{connector}:{pair}:{interval}[:{pool}]`. A gateway pair
like SOL-USDC exists in dozens of pools, and until now every DEX chart in
the dashboard silently drew whichever pool `_resolve_pool` judged deepest.

All three sites that read the channel (backfill, WS stream, REST poll
fallback) went through `parse_candle_channel` — each used to unpack exactly
five names, so a six-part channel raised ValueError in a place nobody
watches: a chart that backfills but never ticks, or ticks but never
backfills. `useCandleStore` and `TradeChart` carry the address through to
the REST backfill, which already accepted it.

Omitting the pool reproduces today's five-segment channel byte for byte,
so no CLOB chart changes.
---
 condor/web/ws_manager.py                     |  45 ++++--
 frontend/src/components/trade/TradeChart.tsx |  20 ++-
 frontend/src/hooks/useCandleStore.ts         |  10 +-
 tests/test_candle_channel_pool_segment.py    | 158 +++++++++++++++++++
 4 files changed, 217 insertions(+), 16 deletions(-)
 create mode 100644 tests/test_candle_channel_pool_segment.py

diff --git a/condor/web/ws_manager.py b/condor/web/ws_manager.py
index ccfca149..2b79d152 100644
--- a/condor/web/ws_manager.py
+++ b/condor/web/ws_manager.py
@@ -68,6 +68,29 @@ def _coerce_duration(value: object) -> int | None:
     return duration if duration > 0 else None
 
 
+def parse_candle_channel(channel: str) -> tuple[str, str, str, str, str | None] | None:
+    """Split a candle channel into its parts, or ``None`` if it is malformed.
+
+    The channel is ``candles:{server}:{connector}:{pair}:{interval}[:{pool_address}]``.
+    The pool address is an **optional sixth segment**, set by the DEX page so a
+    chart is pinned to the exact pool the user opened instead of whichever pool
+    ``dex_candles._resolve_pool`` judges deepest for the pair. A five-part channel
+    (every CLOB chart) parses to ``pool_address=None`` and is byte-identical to
+    what it was before the segment existed.
+
+    Every consumer must go through here: unpacking five names off ``split(":")``
+    raises ``ValueError`` on a six-part channel, and each of the three call sites
+    fails silently in a different way (a stream that never backfills, a backfill
+    that never ticks).
+    """
+    parts = channel.split(":")
+    if len(parts) < 5:
+        return None
+    server_name, connector, pair, interval = parts[1:5]
+    pool_address = parts[5] if len(parts) > 5 else None
+    return server_name, connector, pair, interval, pool_address or None
+
+
 class _CandleBuffer:
     """Per-channel candle buffer with dynamic sizing based on interval + duration."""
 
@@ -498,10 +521,10 @@ async def _handle_candle_duration_change(
 
     async def _backfill_candles(self, channel: str) -> None:
         """Fetch historical candles to fill the buffer gap."""
-        parts = channel.split(":")
-        if len(parts) < 5:
+        parsed = parse_candle_channel(channel)
+        if parsed is None:
             return
-        _, server_name, connector, pair, interval = parts
+        server_name, connector, pair, interval, pool_address = parsed
         buf = self._candle_buffers.get(channel)
         if buf is None:
             return
@@ -525,7 +548,7 @@ async def _backfill_candles(self, channel: str) -> None:
 
             if dex_candles.uses_gecko_candles(connector):
                 candles = await dex_candles.fetch_dex_candles(
-                    connector, None, pair, interval, start_time, end_time
+                    connector, pool_address, pair, interval, start_time, end_time
                 )
                 if candles:
                     buf.upsert_many(candles)
@@ -1006,10 +1029,10 @@ async def _run_ws_stream(
                 backoff = min(backoff * 2, 60)
 
     async def _candle_stream(self, channel: str) -> None:
-        parts = channel.split(":")
-        if len(parts) < 5:
+        parsed = parse_candle_channel(channel)
+        if parsed is None:
             return
-        _, server_name, connector, pair, interval = parts
+        server_name, connector, pair, interval, pool_address = parsed
 
         from config_manager import get_config_manager
 
@@ -1179,10 +1202,10 @@ async def _candle_poll_fallback(self, channel: str) -> None:
         from — this loop *is* the feed, so it polls from the first tick and never
         waits for staleness.
         """
-        parts = channel.split(":")
-        if len(parts) < 5:
+        parsed = parse_candle_channel(channel)
+        if parsed is None:
             return
-        _, server_name, connector, pair, interval = parts
+        server_name, connector, pair, interval, pool_address = parsed
         interval_sec = _INTERVAL_SECONDS.get(interval, 60)
         gecko = dex_candles.uses_gecko_candles(connector)
         # How long without a WS update before we consider it stale
@@ -1228,7 +1251,7 @@ async def _candle_poll_fallback(self, channel: str) -> None:
                     if gecko:
                         candles = await dex_candles.fetch_dex_candles(
                             connector,
-                            None,
+                            pool_address,
                             pair,
                             interval,
                             now - interval_sec * 5,
diff --git a/frontend/src/components/trade/TradeChart.tsx b/frontend/src/components/trade/TradeChart.tsx
index 07d22ada..1ee10f3d 100644
--- a/frontend/src/components/trade/TradeChart.tsx
+++ b/frontend/src/components/trade/TradeChart.tsx
@@ -16,6 +16,11 @@ interface TradeChartProps {
   connector: string;
   pair: string;
   interval: string;
+  /**
+   * Chart this exact DEX pool instead of letting the backend resolve one from
+   * the pair. Set by the DEX pool workspace; every CLOB chart omits it.
+   */
+  poolAddress?: string;
   lookbackSeconds: number;
   startPrice: number;
   endPrice: number;
@@ -45,6 +50,7 @@ export function TradeChart({
   connector,
   pair,
   interval,
+  poolAddress,
   lookbackSeconds,
   startPrice,
   endPrice,
@@ -98,7 +104,13 @@ export function TradeChart({
   const positionLinesRef = useRef<import("lightweight-charts").IPriceLine[]>([]);
 
   // ── Candle data from the singleton store (WS live + cached) ──
-  const { candles, mergeCandles, setDuration } = useCandleStore(server, connector, pair, interval);
+  const { candles, mergeCandles, setDuration } = useCandleStore(
+    server,
+    connector,
+    pair,
+    interval,
+    poolAddress,
+  );
 
   // ── Filter executor overlays to those within candle time range ──
   const filteredOverlays = useMemo(() => {
@@ -117,7 +129,7 @@ export function TradeChart({
   // ── REST backfill on pair/interval/lookback change ──
   const backfillKeyRef = useRef("");
   useEffect(() => {
-    const backfillKey = `${server}:${connector}:${pair}:${interval}:${lookbackSeconds}`;
+    const backfillKey = `${server}:${connector}:${pair}:${interval}:${lookbackSeconds}:${poolAddress ?? ""}`;
     if (backfillKey === backfillKeyRef.current) return;
     backfillKeyRef.current = backfillKey;
 
@@ -129,7 +141,7 @@ export function TradeChart({
     const fetchWithRetry = (attempt: number) => {
       if (cancelled) return;
       api
-        .getCandles(server, connector, pair, interval, 5000, startTime)
+        .getCandles(server, connector, pair, interval, 5000, startTime, undefined, poolAddress)
         .then((fetched) => {
           if (!cancelled && fetched?.length) mergeCandles(fetched);
         })
@@ -142,7 +154,7 @@ export function TradeChart({
     fetchWithRetry(0);
 
     return () => { cancelled = true; };
-  }, [server, connector, pair, interval, lookbackSeconds]); // eslint-disable-line react-hooks/exhaustive-deps
+  }, [server, connector, pair, interval, poolAddress, lookbackSeconds]); // eslint-disable-line react-hooks/exhaustive-deps
 
   // ── Initialize chart ONCE ──
   useEffect(() => {
diff --git a/frontend/src/hooks/useCandleStore.ts b/frontend/src/hooks/useCandleStore.ts
index 9bc5d3e7..1a011f77 100644
--- a/frontend/src/hooks/useCandleStore.ts
+++ b/frontend/src/hooks/useCandleStore.ts
@@ -25,6 +25,13 @@ export function useCandleStore(
   connector: string,
   pair: string,
   interval: string,
+  /**
+   * Pin the stream to one DEX pool. A gateway pair like `SOL-USDC` exists in
+   * dozens of pools, and without this the backend charts whichever one it judges
+   * deepest — which is exactly the guess the DEX page exists to overturn. Omitted
+   * (every CLOB chart) the channel keeps its five segments, byte for byte.
+   */
+  poolAddress?: string,
 ): {
   candles: CandleData[];
   isStale: boolean;
@@ -32,7 +39,8 @@ export function useCandleStore(
   setDuration: (seconds: number) => void;
 } {
   const key = server
-    ? `candles:${server}:${connector}:${pair}:${interval}`
+    ? `candles:${server}:${connector}:${pair}:${interval}` +
+      (poolAddress ? `:${poolAddress}` : "")
     : "";
 
   const [candles, setCandles] = useState<CandleData[]>([]);
diff --git a/tests/test_candle_channel_pool_segment.py b/tests/test_candle_channel_pool_segment.py
new file mode 100644
index 00000000..c01132f4
--- /dev/null
+++ b/tests/test_candle_channel_pool_segment.py
@@ -0,0 +1,158 @@
+"""The candle channel's optional sixth segment: the pool address (FEAT-044).
+
+A DEX chart must be drawn from the pool the user opened, not from whichever pool
+``dex_candles._resolve_pool`` judges deepest for the pair. The channel carries it
+as ``candles:{server}:{connector}:{pair}:{interval}[:{pool_address}]``.
+
+Three sites read that channel — the backfill, the WS stream and the REST poll
+fallback — and each used to unpack exactly five names, so a six-part channel
+raised ``ValueError`` in a place nobody watches: a chart that backfills but never
+ticks, or ticks but never backfills. All three go through
+``parse_candle_channel`` now, and this file exercises all three deliberately.
+"""
+
+import asyncio
+
+import pytest
+
+import condor.web.ws_manager as wsm
+from condor.web.ws_manager import WebSocketManager, parse_candle_channel
+
+POOL = "8sLbNZoA1cfnvMJLPfp98ZLAnFSYCFApfJKMbiXNLwxj"
+FIVE = "candles:srv:solana-mainnet-beta:SOL-USDC:1m"
+SIX = f"{FIVE}:{POOL}"
+
+
+def run(coro):
+    return asyncio.run(coro)
+
+
+# ── the parser ──
+
+
+def test_five_part_channel_parses_with_no_pool():
+    assert parse_candle_channel(FIVE) == (
+        "srv",
+        "solana-mainnet-beta",
+        "SOL-USDC",
+        "1m",
+        None,
+    )
+
+
+def test_six_part_channel_parses_the_pool_address():
+    assert parse_candle_channel(SIX) == (
+        "srv",
+        "solana-mainnet-beta",
+        "SOL-USDC",
+        "1m",
+        POOL,
+    )
+
+
+def test_clob_channel_is_unchanged_shape():
+    """A CEX chart's channel keeps five segments and no pool address."""
+    assert parse_candle_channel("candles:srv:binance:BTC-USDT:1m") == (
+        "srv",
+        "binance",
+        "BTC-USDT",
+        "1m",
+        None,
+    )
+
+
+def test_empty_sixth_segment_is_no_pool():
+    assert parse_candle_channel(FIVE + ":")[4] is None
+
+
+@pytest.mark.parametrize("channel", ["candles", "candles:srv", "candles:srv:binance"])
+def test_short_channels_are_rejected(channel):
+    assert parse_candle_channel(channel) is None
+
+
+# ── the three call sites ──
+
+
+@pytest.fixture
+def spy_fetch(monkeypatch):
+    """Record every ``fetch_dex_candles`` call this module makes."""
+    calls: list[dict] = []
+
+    async def fake_fetch(connector, pool_address, pair, interval, *a, **kw):
+        calls.append(
+            {
+                "connector": connector,
+                "pool_address": pool_address,
+                "pair": pair,
+                "interval": interval,
+            }
+        )
+        return []
+
+    monkeypatch.setattr(wsm.dex_candles, "fetch_dex_candles", fake_fetch)
+    return calls
+
+
+@pytest.mark.parametrize(
+    "channel,expected", [(FIVE, None), (SIX, POOL)], ids=["five-part", "six-part"]
+)
+def test_backfill_passes_the_channel_pool(spy_fetch, channel, expected):
+    mgr = WebSocketManager()
+    mgr._candle_buffers[channel] = wsm._CandleBuffer("1m", 3600)
+    run(mgr._backfill_candles(channel))
+    assert spy_fetch, "backfill never reached fetch_dex_candles"
+    assert spy_fetch[0]["pool_address"] == expected
+    assert spy_fetch[0]["pair"] == "SOL-USDC"
+
+
+@pytest.mark.parametrize("channel", [FIVE, SIX], ids=["five-part", "six-part"])
+def test_candle_stream_parses_without_raising(monkeypatch, channel):
+    """The gecko branch short-circuits, but only after unpacking the channel."""
+    started: list[str] = []
+    monkeypatch.setattr(
+        WebSocketManager,
+        "_ensure_candle_poll_fallback",
+        lambda self, ch: started.append(ch),
+    )
+    run(WebSocketManager()._candle_stream(channel))
+    assert started == [channel]
+
+
+@pytest.mark.parametrize(
+    "channel,expected", [(FIVE, None), (SIX, POOL)], ids=["five-part", "six-part"]
+)
+def test_poll_fallback_passes_the_channel_pool(monkeypatch, channel, expected):
+    """The REST fallback is the whole stream for a gecko-charted venue."""
+    mgr = WebSocketManager()
+    mgr._candle_buffers[channel] = wsm._CandleBuffer("1m", 3600)
+    seen: list = []
+
+    async def fake_fetch(connector, pool_address, pair, interval, *a, **kw):
+        seen.append(pool_address)
+        raise asyncio.CancelledError  # one poll is all we need
+
+    monkeypatch.setattr(wsm.dex_candles, "fetch_dex_candles", fake_fetch)
+
+    # The loop sleeps a 30s poll interval before its first fetch; collapse it.
+    real_sleep = asyncio.sleep
+
+    async def instant(_seconds):
+        await real_sleep(0)
+
+    monkeypatch.setattr(wsm.asyncio, "sleep", instant)
+
+    async def drive():
+        task = asyncio.ensure_future(mgr._candle_poll_fallback(channel))
+        for _ in range(50):
+            if seen:
+                break
+            await real_sleep(0)
+        task.cancel()
+        try:
+            await task
+        except asyncio.CancelledError:
+            pass
+
+    run(drive())
+    assert seen, "poll fallback never reached fetch_dex_candles"
+    assert seen[0] == expected

From f35d4ef423f37bb3b27b7fa49df8f22daceedc80 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Thu, 13 Aug 2026 10:06:55 +0300
Subject: [PATCH 031/116] (feat) dex: pool discovery behind one server-scoped
 route
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`pool_data` is already the single module that talks to GeckoTerminal, so
the three sources Telegram's /lp offers land there rather than opening a
new seam: `list_gecko_pools` (trending/top/new/by-token),
`list_gateway_pools` (a CLMM connector's own listing, with APR and bin
step) and `fetch_pool_by_address` for a deep link.

`normalize_pool_data` gains base/quote token addresses — without the base
mint there is no `<base_mint>-<quote_symbol>` to hand an executor — and
every row is decorated with the venue facts a pool-first UI cannot derive:
lp_provider/lp_supported, gateway_network, tradable, trading_pair and
has_bins. A pool with no LP provider is a state to render, not an error.

Lists are TTL-cached process-wide: GeckoTerminal rate-limits per IP and
every viewer shares the budget the candle poll loop depends on. An
upstream failure answers `{"pools": []}` like /market/venues, not a 502.
---
 condor/web/app.py                |   2 +
 condor/web/routes/dex.py         | 126 +++++++
 handlers/dex/geckoterminal.py    |  15 +-
 handlers/dex/pool_data.py        | 350 ++++++++++++++++++++
 tests/test_dex_pool_discovery.py | 543 +++++++++++++++++++++++++++++++
 5 files changed, 1025 insertions(+), 11 deletions(-)
 create mode 100644 condor/web/routes/dex.py
 create mode 100644 tests/test_dex_pool_discovery.py

diff --git a/condor/web/app.py b/condor/web/app.py
index 1300ea72..40b47299 100644
--- a/condor/web/app.py
+++ b/condor/web/app.py
@@ -20,6 +20,7 @@
     confirmations,
     controller_performance,
     conversations,
+    dex,
     executors,
     market,
     meta,
@@ -81,6 +82,7 @@ def create_app() -> FastAPI:
     app.include_router(positions.router, prefix="/api/v1")
     app.include_router(backtesting.router, prefix="/api/v1")
     app.include_router(market.router, prefix="/api/v1")
+    app.include_router(dex.router, prefix="/api/v1")
     app.include_router(meta.router, prefix="/api/v1")
     app.include_router(ws.router, prefix="/api/v1")
     app.include_router(agents.router, prefix="/api/v1")
diff --git a/condor/web/routes/dex.py b/condor/web/routes/dex.py
new file mode 100644
index 00000000..8ecf0615
--- /dev/null
+++ b/condor/web/routes/dex.py
@@ -0,0 +1,126 @@
+"""Pool discovery for the DEX page.
+
+The DEX page is pool-first: `SOL-USDC` exists in dozens of pools across Meteora,
+Orca, Raydium and Uniswap with different fee tiers, bin steps, TVL and APR, and
+which one you are in *is* the decision. So this router browses pools rather than
+pairs, from the same three sources Telegram's ``/lp`` flow offers.
+
+Everything upstream lives in ``handlers.dex.pool_data`` — the single module that
+talks to GeckoTerminal — so these handlers are auth, validation and shape, with no
+fetching or normalization of their own.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+
+from condor import dex_candles
+from condor.web.auth import get_current_user
+from condor.web.models import WebUser
+from config_manager import get_config_manager
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(tags=["dex"])
+
+# A token or pool address: an EVM 0x-address or a base58 Solana pubkey. Both reach
+# GeckoTerminal as a URL path segment, so they are validated before they get there
+# — the same guard ``/market/candles`` and ``/market/token-symbol`` already apply.
+_ADDRESS_RE = dex_candles.ADDRESS_RE
+_POOL_ADDRESS_RE = _ADDRESS_RE
+
+
+@router.get("/servers/{name}/dex/pools")
+async def list_pools(
+    name: str,
+    source: str = Query(
+        default="gecko",
+        description="'gecko' (a chain's trending/top/new pools, or a token's) or "
+        "'gateway' (a CLMM connector's own listing, with APR and bin step)",
+    ),
+    network: str = Query(
+        default="solana-mainnet-beta",
+        description="source=gecko: the chain, as a Gateway network or gecko id",
+    ),
+    view: str = Query(
+        default="trending", description="source=gecko: trending | top | new | token"
+    ),
+    connector: str = Query(
+        default="meteora", description="source=gateway: meteora | orca | raydium | ..."
+    ),
+    query: str | None = Query(
+        default=None,
+        description="source=gecko+view=token: the token address. "
+        "source=gateway: free text matched against pool names.",
+    ),
+    limit: int = Query(default=20, ge=1, le=100),
+    user: WebUser = Depends(get_current_user),
+):
+    """Pools to browse, from one of the two upstreams.
+
+    ``source`` is the discriminator because the two take genuinely different
+    arguments — gecko searches by *token address* on a chain, Gateway searches free
+    text within a connector — and one merged parameter set would mean documenting
+    which combinations are meaningless.
+
+    An upstream failure answers ``{"pools": []}`` with a warning, like
+    ``/market/venues``: the browser's empty state is something the user can act on,
+    a 502 is not.
+    """
+    cm = get_config_manager()
+    if not cm.has_server_access(user.id, name):
+        raise HTTPException(status_code=403, detail="No access")
+
+    from handlers.dex.pool_data import list_gateway_pools, list_gecko_pools
+
+    source = (source or "gecko").strip().lower()
+
+    if source == "gateway":
+        try:
+            client = await cm.get_client(name)
+        except Exception as e:
+            logger.warning("Gateway pools unavailable for %s: %s", name, e)
+            return {"pools": [], "source": source}
+        pools = await list_gateway_pools(client, connector, search=query, limit=limit)
+        return {"pools": pools, "source": source}
+
+    if source != "gecko":
+        raise HTTPException(status_code=400, detail="Unknown source")
+
+    view = (view or "trending").strip().lower()
+    token = (query or "").strip()
+    # A ticker would be pasted straight into a GeckoTerminal path segment.
+    if view == "token" and not _ADDRESS_RE.match(token):
+        raise HTTPException(status_code=400, detail="Invalid token address")
+
+    pools = await list_gecko_pools(network, view=view, token=token, limit=limit)
+    return {"pools": pools, "source": source}
+
+
+@router.get("/servers/{name}/dex/pools/{pool_address}")
+async def get_pool(
+    name: str,
+    pool_address: str,
+    network: str = Query(default="solana-mainnet-beta"),
+    user: WebUser = Depends(get_current_user),
+):
+    """One pool by address, so ``/dex/{network}/{address}`` renders from a URL alone.
+
+    404 when the pool is genuinely unknown *or* the lookup failed: either way the
+    workspace has nothing to draw, and the two are indistinguishable to the user.
+    """
+    cm = get_config_manager()
+    if not cm.has_server_access(user.id, name):
+        raise HTTPException(status_code=403, detail="No access")
+
+    if not _POOL_ADDRESS_RE.match(pool_address):
+        raise HTTPException(status_code=400, detail="Invalid pool_address")
+
+    from handlers.dex.pool_data import fetch_pool_by_address
+
+    pool = await fetch_pool_by_address(network, pool_address)
+    if not pool:
+        raise HTTPException(status_code=404, detail="Pool not found")
+    return pool
diff --git a/handlers/dex/geckoterminal.py b/handlers/dex/geckoterminal.py
index 8d094d5f..b6bfc43b 100644
--- a/handlers/dex/geckoterminal.py
+++ b/handlers/dex/geckoterminal.py
@@ -21,6 +21,7 @@
 from utils.telegram_formatters import escape_markdown_v2
 
 from ._shared import cached_call
+from .pool_data import GECKO_TO_GATEWAY_NETWORK as _GECKO_TO_GATEWAY_NETWORK
 from .pool_data import can_fetch_liquidity, fetch_liquidity_bins, get_connector_for_dex
 from .visualizations import (
     generate_combined_chart,
@@ -1492,17 +1493,9 @@ async def process_gecko_search(
         )
 
 
-# GeckoTerminal to Gateway network mapping
-GECKO_TO_GATEWAY_NETWORK = {
-    "solana": "solana-mainnet-beta",
-    "eth": "ethereum-mainnet",
-    "base": "base-mainnet",
-    "arbitrum": "arbitrum-one",
-    "bsc": "bsc-mainnet",
-    "polygon_pos": "polygon-mainnet",
-    "avalanche": "avalanche-mainnet",
-    "optimism": "optimism-mainnet",
-}
+# GeckoTerminal to Gateway network mapping. Defined in pool_data, next to its
+# inverse (NETWORK_TO_GECKO), because the web pool browser routes its rows by it.
+GECKO_TO_GATEWAY_NETWORK = _GECKO_TO_GATEWAY_NETWORK
 
 # Default connectors by network chain
 NETWORK_DEFAULT_CONNECTOR = {
diff --git a/handlers/dex/pool_data.py b/handlers/dex/pool_data.py
index c343c434..851924b1 100644
--- a/handlers/dex/pool_data.py
+++ b/handlers/dex/pool_data.py
@@ -90,6 +90,22 @@
     "xrpl": "xrpl",
 }
 
+# The inverse of NETWORK_TO_GECKO, one entry per gecko chain: the Gateway network
+# id a pool discovered on that chain belongs to. Lives here rather than in the
+# Telegram handler that used to own it because the pool browser's rows are routed
+# by it (``/dex/{gateway_network}/{address}``), and a gecko chain with no entry is
+# one Gateway cannot reach — a state to render, not an error.
+GECKO_TO_GATEWAY_NETWORK = {
+    "solana": "solana-mainnet-beta",
+    "eth": "ethereum-mainnet",
+    "base": "base-mainnet",
+    "arbitrum": "arbitrum-one",
+    "bsc": "bsc-mainnet",
+    "polygon_pos": "polygon-mainnet",
+    "avalanche": "avalanche-mainnet",
+    "optimism": "optimism-mainnet",
+}
+
 # Networks whose venues quote *tickers* rather than token addresses. An XRPL token
 # is a (currency, issuer) pair that the connector hides behind a symbol like
 # ``SOLO-XRP``, so its pool can only be found by searching for that symbol —
@@ -113,6 +129,12 @@
 BINS_CACHE_TTL = 60  # 1 minute
 TOKEN_SYMBOL_TTL = 24 * 3600  # a mint's ticker does not change
 TOKEN_POOL_TTL = 3600  # a token's main pool is stable over an hour
+# Pool *lists* are the pool browser's hot path and GeckoTerminal rate-limits per
+# IP across every dashboard viewer and every polling chart, so these are not an
+# optimization: an un-cached browser refetching per keystroke would starve the
+# candle poll loop of the same budget.
+POOL_LIST_TTL = 60  # gecko trending/top/new/token lists
+GATEWAY_POOL_LIST_TTL = 30  # gateway CLMM lists, per (connector, search)
 
 # GeckoTerminal's OHLCV endpoint only accepts these aggregates, and its client
 # raises ValueError on anything else. Charts pick their own interval, so map an
@@ -805,6 +827,45 @@ async def fetch_liquidity_bins(
         return None, None, f"Failed to fetch liquidity: {str(e)}"
 
 
+def _token_address_from_id(token_id: Any) -> str:
+    """``solana_<mint>`` → ``<mint>``. Anything without the prefix passes through.
+
+    GeckoTerminal ids are ``{network}_{address}`` in the relationships block, but
+    ``process_pools_list`` already strips them on its list endpoints and the
+    by-address endpoint does not. Neither a base58 pubkey nor an EVM 0x-address
+    contains an underscore, so stripping is idempotent and safe for both shapes.
+    """
+    text = str(token_id or "").strip()
+    if not text or text.lower() == "nan":
+        return ""
+    _head, sep, tail = text.partition("_")
+    return tail if sep and tail else text
+
+
+def _gecko_token_address(pool: dict, attrs: dict, side: str) -> str:
+    """The ``base``/``quote`` token address on a GeckoTerminal pool row.
+
+    Reads the nested ``relationships.{side}_token.data.id`` the raw API returns,
+    then the flat ``{side}_token_id`` / ``{side}_token_address`` columns a
+    DataFrame row carries instead. Columns have moved between library versions,
+    so every known shape is tried before giving up.
+    """
+    rel = ((pool.get("relationships") or {}).get(f"{side}_token") or {}).get("data")
+    nested = (rel or {}).get("id") if isinstance(rel, dict) else None
+    token_obj = attrs.get(f"{side}_token")
+    candidates = (
+        nested,
+        attrs.get(f"{side}_token_id"),
+        attrs.get(f"{side}_token_address"),
+        token_obj.get("address") if isinstance(token_obj, dict) else None,
+    )
+    for candidate in candidates:
+        address = _token_address_from_id(candidate)
+        if address:
+            return address
+    return ""
+
+
 def normalize_pool_data(pool: dict, source: str = "gecko") -> Dict[str, Any]:
     """Normalize pool data from different sources to a common format
 
@@ -824,6 +885,11 @@ def normalize_pool_data(pool: dict, source: str = "gecko") -> Dict[str, Any]:
             "name": attrs.get("name", "Unknown"),
             "base_token_symbol": attrs.get("base_token_symbol", "???"),
             "quote_token_symbol": attrs.get("quote_token_symbol", "???"),
+            # A pool-first UI cannot do without the mints: an LP or DEX order
+            # executor's trading_pair is ``<base_mint>-<quote_symbol>``, so a pool
+            # with no base address is a pool nothing can be opened in.
+            "base_token_address": _gecko_token_address(pool, attrs, "base"),
+            "quote_token_address": _gecko_token_address(pool, attrs, "quote"),
             "base_token_price_usd": attrs.get("base_token_price_usd"),
             "quote_token_price_usd": attrs.get("quote_token_price_usd"),
             "network": pool.get("network") or attrs.get("network", "solana"),
@@ -868,6 +934,8 @@ def normalize_pool_data(pool: dict, source: str = "gecko") -> Dict[str, Any]:
             "base_fee_percentage": pool.get("base_fee_percentage"),
             "mint_x": pool.get("mint_x"),
             "mint_y": pool.get("mint_y"),
+            "base_token_address": str(pool.get("mint_x") or ""),
+            "quote_token_address": str(pool.get("mint_y") or ""),
             "source": "gateway",
         }
 
@@ -932,3 +1000,285 @@ def extract_pair_from_name(name: str) -> Tuple[str, str]:
                 return parts[0].strip(), parts[1].strip()
 
     return name, "???"
+
+
+# ── Pool discovery ──
+# The pool browser's three sources, behind one module. Telegram's /lp flow reaches
+# GeckoTerminal and Gateway CLMM through its own inline fetching, each wrapped in
+# MarkdownV2 table building and per-user caching, so none of it is callable from a
+# web route. These are: the same upstreams, normalized, decorated and TTL-cached
+# process-wide, with no presentation attached.
+
+GECKO_POOL_VIEWS = ("trending", "top", "new", "token")
+
+_gecko_pool_list_cache: Dict[Tuple, Tuple[float, List[Dict[str, Any]]]] = {}
+_gateway_pool_list_cache: Dict[Tuple, Tuple[float, List[Dict[str, Any]]]] = {}
+_pool_by_address_cache: Dict[Tuple[str, str], Tuple[float, Dict[str, Any]]] = {}
+
+# A pool list is a browser page, not a report: cap what an upstream can be asked
+# for so one query cannot drag a thousand rows through normalization.
+_POOL_LIST_MAX = 100
+
+
+def _coerce_pool_rows(result: Any, limit: int = 20) -> List[Dict[str, Any]]:
+    """``DataFrame | {"data": [...]} | [...]`` → a list of raw pool dicts.
+
+    ``geckoterminal_py`` answers the pool-list endpoints with a pandas DataFrame,
+    but the raw JSON shapes turn up too (a hand-rolled ``api_request``, a recorded
+    fixture), and which one arrives has changed across library versions. Anything
+    that is not a mapping is dropped rather than crashing the whole listing.
+    """
+    if result is None:
+        return []
+
+    try:
+        import pandas as pd
+
+        if isinstance(result, pd.DataFrame):
+            rows = result.to_dict("records")
+            return [r for r in rows if isinstance(r, dict)][:limit]
+    except ImportError:  # pragma: no cover - pandas ships with geckoterminal_py
+        pass
+
+    if isinstance(result, dict):
+        rows = result.get("data") or []
+    elif isinstance(result, list):
+        rows = result
+    else:
+        rows = getattr(result, "data", None) or []
+
+    if isinstance(rows, dict):  # a by-address response: one pool, not a list
+        rows = [rows]
+    return [r for r in rows if isinstance(r, dict)][:limit]
+
+
+def decorate_pool(info: Dict[str, Any], network: str) -> Dict[str, Any]:
+    """Add the venue facts a pool-first UI cannot derive on its own, in place.
+
+    A browser row has to answer three questions before the user clicks it — can I
+    chart this pool, can I trade in it, can I LP in it — and every one of them is
+    a fact about *our* connectors, not about the pool. Deciding them here keeps
+    the frontend from re-deriving venue rules it cannot know, and keeps "chart yes,
+    LP no" a renderable state rather than an executor that fails on create.
+    """
+    dex_id = str(info.get("dex_id") or "")
+    gecko_network = get_gecko_network(network)
+    gateway_network = GECKO_TO_GATEWAY_NETWORK.get(gecko_network) or (
+        network if network in NETWORK_TO_GECKO else ""
+    )
+
+    # normalize_pool_data reports "???" for a symbol GeckoTerminal only publishes
+    # inside the pool's display name; _fill_pool_pair_fields has parsed it by now.
+    def _symbol(side: str) -> str:
+        for key in (f"{side}_symbol", f"{side}_token_symbol"):
+            value = str(info.get(key) or "").strip()
+            if value and value != "???":
+                return value.upper()
+        return ""
+
+    base_symbol, quote_symbol = _symbol("base"), _symbol("quote")
+    info["base_symbol"] = base_symbol or "???"
+    info["quote_symbol"] = quote_symbol or "???"
+    info["base_token_symbol"] = base_symbol or "???"
+    info["quote_token_symbol"] = quote_symbol or "???"
+
+    provider = lp_provider_for_dex(dex_id, network)
+    info["lp_provider"] = provider
+    info["lp_supported"] = provider is not None
+    info["gateway_network"] = gateway_network
+    info["network"] = network
+    info["gecko_network"] = gecko_network
+    # A chain GeckoTerminal indexes is not necessarily one Gateway reaches.
+    info["tradable"] = bool(gateway_network) and gateway_network in NETWORK_TO_GECKO
+    # Consumed by the liquidity-bin depth chart (FEAT-045); decided here because
+    # it is the same kind of venue fact as lp_supported.
+    info["has_bins"] = can_fetch_liquidity(dex_id, network)
+
+    # The <base_mint>-<quote_symbol> form LP and DEX order executors already carry,
+    # except on a network whose venues quote tickers rather than addresses (xrpl),
+    # where the base *is* a symbol.
+    base = base_symbol if uses_symbol_pairs(network) else info.get("base_token_address")
+    base = str(base or "")
+    info["trading_pair"] = f"{base}-{quote_symbol}" if base and quote_symbol else ""
+    return info
+
+
+def _normalize_gecko_pool(row: Dict[str, Any], network: str) -> Dict[str, Any]:
+    """One raw GeckoTerminal pool row → a decorated, normalized pool."""
+    info = normalize_pool_data(row, source="gecko")
+    _fill_pool_pair_fields(info, network, row)
+    return decorate_pool(info, network)
+
+
+def _clamp_pool_limit(limit: Any) -> int:
+    try:
+        value = int(limit)
+    except (TypeError, ValueError):
+        return 20
+    return max(1, min(value, _POOL_LIST_MAX))
+
+
+async def list_gecko_pools(
+    network: str,
+    view: str = "trending",
+    token: Optional[str] = None,
+    limit: int = 20,
+) -> List[Dict[str, Any]]:
+    """GeckoTerminal pools for a chain: ``trending``, ``top``, ``new`` or by token.
+
+    ``network`` may be a Gateway network id or a gecko chain id — ``get_gecko_network``
+    normalizes either. ``view="token"`` needs ``token`` to be a real address; a
+    ticker would be pasted straight into a URL path segment, so it is refused here.
+
+    An upstream failure answers ``[]`` (and is not cached), because the caller's
+    honest rendering of "no pools" is more useful than an error the user cannot act
+    on. A successful empty answer *is* cached — that chain really has no such list.
+    """
+    from condor.dex_candles import ADDRESS_RE
+
+    gnet = get_gecko_network(network)
+    view = (view or "trending").strip().lower()
+    if view not in GECKO_POOL_VIEWS:
+        view = "trending"
+    token = (token or "").strip()
+    if view == "token" and not ADDRESS_RE.match(token):
+        return []
+    limit = _clamp_pool_limit(limit)
+
+    key = (gnet, view, token, limit)
+    cached = _ttl_get(_gecko_pool_list_cache, key, POOL_LIST_TTL)
+    if cached is not None:
+        return [dict(row) for row in cached]
+
+    client = _gecko_client()
+    try:
+        if view == "trending":
+            result = await client.get_trending_pools_by_network(gnet)
+        elif view == "top":
+            result = await client.get_top_pools_by_network(gnet)
+        elif view == "new":
+            result = await client.get_new_pools_by_network(gnet)
+        else:
+            result = await client.get_top_pools_by_network_token(gnet, token)
+    except Exception as e:
+        # Includes the KeyError geckoterminal_py raises post-processing an empty
+        # result set, and every rate-limit response.
+        logger.warning("gecko pool list failed net=%s view=%s: %s", gnet, view, e)
+        return []
+
+    pools: List[Dict[str, Any]] = []
+    for row in _coerce_pool_rows(result, limit):
+        try:
+            pool = _normalize_gecko_pool(row, network)
+        except Exception as e:
+            logger.info("gecko pool row skipped net=%s: %s", gnet, e)
+            continue
+        if pool.get("address"):
+            pools.append(pool)
+
+    _ttl_put(_gecko_pool_list_cache, key, pools, POOL_LIST_TTL)
+    return [dict(row) for row in pools]
+
+
+def gateway_connector_network(connector: str) -> str:
+    """The network a Gateway CLMM connector's pools live on."""
+    return LIQUIDITY_SUPPORTED_DEXES.get((connector or "").strip().lower(), "solana")
+
+
+async def list_gateway_pools(
+    client: Any,
+    connector: str,
+    search: Optional[str] = None,
+    limit: int = 20,
+) -> List[Dict[str, Any]]:
+    """Gateway CLMM pools for a connector, optionally filtered by free text.
+
+    Unlike the gecko sources this one is server-scoped (it needs a Hummingbot API
+    client) and searches *within* a connector by name rather than by token address
+    — which is why the route keeps the two behind a ``source`` discriminator
+    instead of one parameter set with meaningless combinations.
+    """
+    connector = (connector or "").strip().lower()
+    if not connector:
+        return []
+    search = (search or "").strip() or None
+    limit = _clamp_pool_limit(limit)
+
+    key = (connector, search or "", limit)
+    cached = _ttl_get(_gateway_pool_list_cache, key, GATEWAY_POOL_LIST_TTL)
+    if cached is not None:
+        return [dict(row) for row in cached]
+
+    if client is None or not hasattr(client, "gateway_clmm"):
+        logger.warning("Gateway CLMM unavailable for connector=%s", connector)
+        return []
+
+    try:
+        result = await client.gateway_clmm.get_pools(
+            connector=connector, page=0, limit=limit, search_term=search
+        )
+    except Exception as e:
+        logger.warning("gateway pool list failed connector=%s: %s", connector, e)
+        return []
+
+    raw = result.get("pools") if isinstance(result, dict) else result
+    network = gateway_connector_network(connector)
+    pools: List[Dict[str, Any]] = []
+    for row in _coerce_pool_rows(raw, limit):
+        row = dict(row)
+        row.setdefault("connector", connector)
+        try:
+            pool = decorate_pool(normalize_pool_data(row, source="gateway"), network)
+        except Exception as e:
+            logger.info("gateway pool row skipped connector=%s: %s", connector, e)
+            continue
+        if pool.get("address"):
+            pools.append(pool)
+
+    _ttl_put(_gateway_pool_list_cache, key, pools, GATEWAY_POOL_LIST_TTL)
+    return [dict(row) for row in pools]
+
+
+async def fetch_pool_by_address(
+    network: str, pool_address: str
+) -> Optional[Dict[str, Any]]:
+    """One normalized pool, for a deep link or a reload of the pool workspace.
+
+    The workspace has to render from a URL alone, with no state carried over from
+    the browser that linked to it, so the pool is fetched by address rather than
+    looked up in a list. A pool that genuinely does not exist is cached as such;
+    a failed lookup is not.
+    """
+    from condor.dex_candles import ADDRESS_RE
+
+    pool_address = (pool_address or "").strip()
+    if not ADDRESS_RE.match(pool_address):
+        return None
+
+    gnet = get_gecko_network(network)
+    key = (gnet, pool_address)
+    cached = _ttl_get(_pool_by_address_cache, key, POOL_LIST_TTL)
+    if cached is not None:
+        return dict(cached) if cached else None
+
+    try:
+        result = await _gecko_client().get_pool_by_network_address(gnet, pool_address)
+    except Exception as e:
+        logger.info("pool lookup failed net=%s pool=%s: %s", gnet, pool_address, e)
+        return None
+
+    rows = _coerce_pool_rows(result, 1)
+    if not rows:
+        _ttl_put(_pool_by_address_cache, key, {}, POOL_LIST_TTL)
+        return None
+
+    try:
+        pool = _normalize_gecko_pool(rows[0], network)
+    except Exception as e:
+        logger.info("pool parse failed net=%s pool=%s: %s", gnet, pool_address, e)
+        return None
+
+    if not pool.get("address"):
+        pool["address"] = pool_address
+    _ttl_put(_pool_by_address_cache, key, pool, POOL_LIST_TTL)
+    return dict(pool)
diff --git a/tests/test_dex_pool_discovery.py b/tests/test_dex_pool_discovery.py
new file mode 100644
index 00000000..63c71ba4
--- /dev/null
+++ b/tests/test_dex_pool_discovery.py
@@ -0,0 +1,543 @@
+"""Pool discovery in handlers/dex/pool_data.py (FEAT-044).
+
+The DEX page is pool-first, so every row it renders has to answer three questions
+the frontend cannot: can I chart this pool, can I trade in it, can I LP in it.
+That is what ``decorate_pool`` decides, and what these tests pin — against the
+DataFrame shape ``geckoterminal_py`` actually returns (flat columns, symbols only
+inside the display name) and the Gateway CLMM payload shape.
+"""
+
+import asyncio
+
+import pandas as pd
+import pytest
+from fastapi import FastAPI
+from starlette.testclient import TestClient
+
+import condor.web.routes.dex as dex_routes
+from condor.web.auth import get_current_user
+from condor.web.models import WebUser
+from handlers.dex import pool_data
+
+POOL = "8sLbNZoA1cfnvMJLPfp98ZLAnFSYCFApfJKMbiXNLwxj"
+SOL = "So11111111111111111111111111111111111111112"
+USDC = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
+
+
+def run(coro):
+    return asyncio.run(coro)
+
+
+@pytest.fixture(autouse=True)
+def _clear_caches():
+    for cache in (
+        pool_data._gecko_pool_list_cache,
+        pool_data._gateway_pool_list_cache,
+        pool_data._pool_by_address_cache,
+    ):
+        cache.clear()
+    yield
+
+
+def gecko_row(dex_id="meteora", name="SOL / USDC", address=POOL):
+    """One row as ``process_pools_list`` produces it: flat, ids already stripped."""
+    return {
+        "id": f"solana_{address}",
+        "type": "pool",
+        "name": name,
+        "address": address,
+        "dex_id": dex_id,
+        "base_token_id": SOL,
+        "quote_token_id": USDC,
+        "network_id": "solana",
+        "base_token_price_usd": "150.0",
+        "quote_token_price_usd": "1.0",
+        "reserve_in_usd": "12500000.0",
+        "volume_usd_h24": "4200000.0",
+        "price_change_percentage_h24": "-3.5",
+        "fdv_usd": "9000000000",
+        "market_cap_usd": "8000000000",
+        "pool_created_at": "2024-01-01T00:00:00Z",
+    }
+
+
+def gateway_row(**over):
+    row = {
+        "pool_address": POOL,
+        "connector": "meteora",
+        "trading_pair": "SOL-USDC",
+        "base_symbol": "SOL",
+        "quote_symbol": "USDC",
+        "mint_x": SOL,
+        "mint_y": USDC,
+        "liquidity": 4_500_000.0,
+        "volume_24h": 1_200_000.0,
+        "apr": 42.5,
+        "bin_step": 20,
+        "base_fee_percentage": 0.2,
+        "price": 150.0,
+    }
+    row.update(over)
+    return row
+
+
+class FakeGecko:
+    """Stands in for the shared GeckoTerminalAsyncClient."""
+
+    def __init__(self, frame=None, error=None):
+        self.frame = frame
+        self.error = error
+        self.calls: list[tuple] = []
+
+    async def _answer(self, *args):
+        self.calls.append(args)
+        if self.error:
+            raise self.error
+        return self.frame
+
+    async def get_trending_pools_by_network(self, n):
+        return await self._answer("trending", n)
+
+    async def get_top_pools_by_network(self, n):
+        return await self._answer("top", n)
+
+    async def get_new_pools_by_network(self, n):
+        return await self._answer("new", n)
+
+    async def get_top_pools_by_network_token(self, n, t):
+        return await self._answer("token", n, t)
+
+    async def get_pool_by_network_address(self, n, a):
+        return await self._answer("address", n, a)
+
+
+@pytest.fixture
+def fake_gecko(monkeypatch):
+    def install(frame=None, error=None):
+        client = FakeGecko(frame, error)
+        monkeypatch.setattr(pool_data, "_gecko_client", lambda: client)
+        return client
+
+    return install
+
+
+# ── _coerce_pool_rows ──
+
+
+def test_coerce_handles_a_dataframe():
+    rows = pool_data._coerce_pool_rows(pd.DataFrame([gecko_row(), gecko_row()]), 10)
+    assert len(rows) == 2 and rows[0]["address"] == POOL
+
+
+def test_coerce_handles_json_envelope_and_bare_list():
+    assert pool_data._coerce_pool_rows({"data": [gecko_row()]}, 10)[0]["name"] == (
+        "SOL / USDC"
+    )
+    assert len(pool_data._coerce_pool_rows([gecko_row()], 10)) == 1
+
+
+def test_coerce_handles_a_single_pool_mapping():
+    """The by-address endpoint answers with one pool, not a list."""
+    assert len(pool_data._coerce_pool_rows({"data": gecko_row()}, 1)) == 1
+
+
+def test_coerce_respects_the_limit_and_drops_non_mappings():
+    assert len(pool_data._coerce_pool_rows([gecko_row()] * 5, 2)) == 2
+    assert pool_data._coerce_pool_rows([gecko_row(), "junk", None], 10) == [gecko_row()]
+
+
+def test_coerce_of_nothing_is_empty():
+    assert pool_data._coerce_pool_rows(None, 10) == []
+    assert pool_data._coerce_pool_rows(pd.DataFrame(), 10) == []
+
+
+# ── normalization: the two new address keys ──
+
+
+def test_gecko_normalization_carries_token_addresses():
+    info = pool_data.normalize_pool_data(gecko_row(), source="gecko")
+    assert info["base_token_address"] == SOL
+    assert info["quote_token_address"] == USDC
+
+
+def test_gecko_normalization_reads_nested_relationships():
+    """The raw API shape, where ids are still ``{network}_{address}``."""
+    raw = {
+        "id": f"solana_{POOL}",
+        "attributes": {"address": POOL, "name": "SOL / USDC", "dex_id": "meteora"},
+        "relationships": {
+            "base_token": {"data": {"id": f"solana_{SOL}"}},
+            "quote_token": {"data": {"id": f"solana_{USDC}"}},
+        },
+    }
+    info = pool_data.normalize_pool_data(raw, source="gecko")
+    assert (info["base_token_address"], info["quote_token_address"]) == (SOL, USDC)
+
+
+def test_gateway_normalization_takes_addresses_from_the_mints():
+    info = pool_data.normalize_pool_data(gateway_row(), source="gateway")
+    assert info["base_token_address"] == SOL
+    assert info["quote_token_address"] == USDC
+
+
+def test_missing_token_addresses_are_empty_not_an_error():
+    info = pool_data.normalize_pool_data({"address": POOL}, source="gecko")
+    assert info["base_token_address"] == ""
+
+
+# ── decoration ──
+
+
+def test_meteora_pool_is_lp_supported_and_tradable():
+    pool = pool_data._normalize_gecko_pool(gecko_row("meteora"), "solana-mainnet-beta")
+    assert pool["lp_provider"] == "meteora/clmm"
+    assert pool["lp_supported"] is True
+    assert pool["tradable"] is True
+    assert pool["gateway_network"] == "solana-mainnet-beta"
+    assert pool["has_bins"] is True
+
+
+def test_raydium_amm_v4_pool_is_charted_but_not_lp_able():
+    """Plain ``raydium`` is the constant-product AMM; only raydium-clmm is CLMM."""
+    pool = pool_data._normalize_gecko_pool(gecko_row("raydium"), "solana-mainnet-beta")
+    assert pool["lp_provider"] is None
+    assert pool["lp_supported"] is False
+    # Still a pool the user can chart and swap in — a state, not an error.
+    assert pool["tradable"] is True
+    assert pool["trading_pair"] == f"{SOL}-USDC"
+
+
+def test_raydium_clmm_pool_is_lp_able():
+    pool = pool_data._normalize_gecko_pool(
+        gecko_row("raydium-clmm"), "solana-mainnet-beta"
+    )
+    assert pool["lp_provider"] == "raydium/clmm"
+
+
+def test_pool_on_a_chain_gateway_cannot_reach_is_not_tradable():
+    pool = pool_data._normalize_gecko_pool(gecko_row("cetus"), "sui-network")
+    assert pool["tradable"] is False
+    assert pool["gateway_network"] == ""
+    assert pool["lp_supported"] is False
+
+
+def test_trading_pair_is_base_mint_dash_quote_symbol():
+    """The form LP and DEX order executors already carry (FEAT-042)."""
+    pool = pool_data._normalize_gecko_pool(gecko_row(), "solana-mainnet-beta")
+    assert pool["trading_pair"] == f"{SOL}-USDC"
+    assert pool["base_symbol"] == "SOL"
+    assert pool["quote_symbol"] == "USDC"
+
+
+def test_trading_pair_is_empty_when_the_base_mint_is_unknown():
+    row = gecko_row()
+    row["base_token_id"] = ""
+    pool = pool_data._normalize_gecko_pool(row, "solana-mainnet-beta")
+    assert pool["trading_pair"] == ""
+
+
+def test_symbols_are_parsed_out_of_the_pool_display_name():
+    """GeckoTerminal publishes no symbol column — only ``"BONK / SOL"``."""
+    pool = pool_data._normalize_gecko_pool(
+        gecko_row(name="BONK / SOL"), "solana-mainnet-beta"
+    )
+    assert (pool["base_token_symbol"], pool["quote_token_symbol"]) == ("BONK", "SOL")
+
+
+def test_gateway_pool_keeps_its_apr_and_bin_step_through_decoration():
+    pool = pool_data.decorate_pool(
+        pool_data.normalize_pool_data(gateway_row(), source="gateway"), "solana"
+    )
+    assert pool["apr"] == 42.5
+    assert pool["bin_step"] == 20
+    assert pool["lp_provider"] == "meteora/clmm"
+    assert pool["trading_pair"] == f"{SOL}-USDC"
+
+
+# ── list_gecko_pools ──
+
+
+@pytest.mark.parametrize(
+    "view,expected", [("trending", "trending"), ("top", "top"), ("new", "new")]
+)
+def test_each_gecko_view_hits_its_own_endpoint(fake_gecko, view, expected):
+    client = fake_gecko(pd.DataFrame([gecko_row()]))
+    pools = run(pool_data.list_gecko_pools("solana-mainnet-beta", view=view))
+    assert client.calls[0][0] == expected
+    assert client.calls[0][1] == "solana"  # gateway id normalized to the gecko chain
+    assert len(pools) == 1
+
+
+def test_unknown_view_falls_back_to_trending(fake_gecko):
+    client = fake_gecko(pd.DataFrame([gecko_row()]))
+    run(pool_data.list_gecko_pools("solana", view="nonsense"))
+    assert client.calls[0][0] == "trending"
+
+
+def test_token_view_requires_a_real_address(fake_gecko):
+    client = fake_gecko(pd.DataFrame([gecko_row()]))
+    assert run(pool_data.list_gecko_pools("solana", view="token", token="SOL")) == []
+    assert run(pool_data.list_gecko_pools("solana", view="token", token="")) == []
+    assert client.calls == [], "a ticker must never reach a URL path segment"
+
+
+def test_token_view_passes_the_mint_through(fake_gecko):
+    client = fake_gecko(pd.DataFrame([gecko_row()]))
+    run(pool_data.list_gecko_pools("solana", view="token", token=SOL))
+    assert client.calls[0] == ("token", "solana", SOL)
+
+
+def test_an_upstream_failure_is_an_empty_list_not_an_exception(fake_gecko):
+    fake_gecko(error=RuntimeError("429 rate limited"))
+    assert run(pool_data.list_gecko_pools("solana")) == []
+
+
+def test_a_failure_is_not_cached(fake_gecko):
+    fake_gecko(error=RuntimeError("boom"))
+    run(pool_data.list_gecko_pools("solana"))
+    client = fake_gecko(pd.DataFrame([gecko_row()]))
+    assert len(run(pool_data.list_gecko_pools("solana"))) == 1
+
+
+def test_lists_are_ttl_cached_across_callers(fake_gecko):
+    """Every viewer shares one GeckoTerminal budget, so the list is cached."""
+    client = fake_gecko(pd.DataFrame([gecko_row()]))
+    run(pool_data.list_gecko_pools("solana"))
+    run(pool_data.list_gecko_pools("solana"))
+    assert len(client.calls) == 1
+
+
+def test_cached_rows_are_copies_a_caller_cannot_poison(fake_gecko):
+    fake_gecko(pd.DataFrame([gecko_row()]))
+    first = run(pool_data.list_gecko_pools("solana"))
+    first[0]["address"] = "mutated"
+    assert run(pool_data.list_gecko_pools("solana"))[0]["address"] == POOL
+
+
+def test_rows_with_no_address_are_dropped(fake_gecko):
+    """A row with neither an address nor an id to recover one from is unusable."""
+    row = gecko_row()
+    row["address"] = ""
+    row["id"] = ""
+    fake_gecko(pd.DataFrame([row, gecko_row()]))
+    assert len(run(pool_data.list_gecko_pools("solana"))) == 1
+
+
+def test_limit_is_clamped(fake_gecko):
+    fake_gecko(pd.DataFrame([gecko_row(address=POOL)] * 60))
+    assert len(run(pool_data.list_gecko_pools("solana", limit=5))) == 5
+    assert len(run(pool_data.list_gecko_pools("solana", limit=10_000))) == 60
+
+
+# ── list_gateway_pools ──
+
+
+class FakeClmm:
+    def __init__(self, payload=None, error=None):
+        self.payload = payload
+        self.error = error
+        self.calls: list[dict] = []
+
+    async def get_pools(self, **kwargs):
+        self.calls.append(kwargs)
+        if self.error:
+            raise self.error
+        return self.payload
+
+
+class FakeClient:
+    def __init__(self, clmm):
+        self.gateway_clmm = clmm
+
+
+def test_gateway_pools_are_normalized_and_decorated():
+    clmm = FakeClmm({"pools": [gateway_row()]})
+    pools = run(pool_data.list_gateway_pools(FakeClient(clmm), "meteora"))
+    assert len(pools) == 1
+    assert pools[0]["source"] == "gateway"
+    assert pools[0]["apr"] == 42.5
+    assert pools[0]["lp_supported"] is True
+    assert pools[0]["gateway_network"] == "solana-mainnet-beta"
+    assert clmm.calls[0]["connector"] == "meteora"
+
+
+def test_gateway_search_term_is_forwarded():
+    clmm = FakeClmm({"pools": []})
+    run(pool_data.list_gateway_pools(FakeClient(clmm), "orca", search="SOL"))
+    assert clmm.calls[0]["search_term"] == "SOL"
+
+
+def test_blank_gateway_search_is_no_search():
+    clmm = FakeClmm({"pools": []})
+    run(pool_data.list_gateway_pools(FakeClient(clmm), "orca", search="   "))
+    assert clmm.calls[0]["search_term"] is None
+
+
+def test_gateway_failure_is_an_empty_list():
+    clmm = FakeClmm(error=RuntimeError("gateway down"))
+    assert run(pool_data.list_gateway_pools(FakeClient(clmm), "meteora")) == []
+
+
+def test_client_without_gateway_clmm_is_an_empty_list():
+    assert run(pool_data.list_gateway_pools(object(), "meteora")) == []
+    assert run(pool_data.list_gateway_pools(None, "meteora")) == []
+
+
+def test_gateway_lists_are_cached_per_connector_and_search():
+    clmm = FakeClmm({"pools": [gateway_row()]})
+    client = FakeClient(clmm)
+    run(pool_data.list_gateway_pools(client, "meteora"))
+    run(pool_data.list_gateway_pools(client, "meteora"))
+    assert len(clmm.calls) == 1
+    run(pool_data.list_gateway_pools(client, "meteora", search="SOL"))
+    assert len(clmm.calls) == 2
+
+
+# ── fetch_pool_by_address ──
+
+
+def test_pool_by_address_returns_one_decorated_pool(fake_gecko):
+    client = fake_gecko(pd.DataFrame([gecko_row()]))
+    pool = run(pool_data.fetch_pool_by_address("solana-mainnet-beta", POOL))
+    assert pool["address"] == POOL
+    assert pool["lp_provider"] == "meteora/clmm"
+    assert client.calls[0] == ("address", "solana", POOL)
+
+
+def test_pool_by_address_refuses_a_non_address(fake_gecko):
+    client = fake_gecko(pd.DataFrame([gecko_row()]))
+    assert run(pool_data.fetch_pool_by_address("solana", "../../etc/passwd")) is None
+    assert client.calls == []
+
+
+def test_unknown_pool_is_none_and_cached(fake_gecko):
+    client = fake_gecko(pd.DataFrame())
+    assert run(pool_data.fetch_pool_by_address("solana", POOL)) is None
+    assert run(pool_data.fetch_pool_by_address("solana", POOL)) is None
+    assert len(client.calls) == 1
+
+
+def test_pool_by_address_failure_is_none_and_not_cached(fake_gecko):
+    fake_gecko(error=RuntimeError("boom"))
+    assert run(pool_data.fetch_pool_by_address("solana", POOL)) is None
+    client = fake_gecko(pd.DataFrame([gecko_row()]))
+    assert run(pool_data.fetch_pool_by_address("solana", POOL)) is not None
+
+
+# ── the route (condor/web/routes/dex.py) ──
+
+
+USER = WebUser(id=111, username="u", first_name="U", role="user")
+
+
+class FakeConfigManager:
+    def __init__(self, allowed=True, client=None, client_error=None):
+        self.allowed = allowed
+        self._client = client
+        self._client_error = client_error
+
+    def has_server_access(self, user_id, name, *a, **kw):
+        return self.allowed
+
+    async def get_client(self, name):
+        if self._client_error:
+            raise self._client_error
+        return self._client
+
+
+@pytest.fixture
+def route_client(monkeypatch):
+    def build(allowed=True, client=None, client_error=None):
+        cm = FakeConfigManager(allowed, client, client_error)
+        monkeypatch.setattr(dex_routes, "get_config_manager", lambda: cm)
+        app = FastAPI()
+        app.include_router(dex_routes.router)
+        app.dependency_overrides[get_current_user] = lambda: USER
+        return TestClient(app)
+
+    return build
+
+
+def test_gecko_source_lists_pools(route_client, fake_gecko):
+    fake_gecko(pd.DataFrame([gecko_row()]))
+    r = route_client().get("/servers/srv/dex/pools?source=gecko&view=trending")
+    assert r.status_code == 200
+    body = r.json()
+    assert body["source"] == "gecko"
+    assert body["pools"][0]["address"] == POOL
+    assert body["pools"][0]["lp_supported"] is True
+
+
+def test_gecko_token_view_rejects_a_ticker(route_client, fake_gecko):
+    client = fake_gecko(pd.DataFrame([gecko_row()]))
+    r = route_client().get("/servers/srv/dex/pools?source=gecko&view=token&query=SOL")
+    assert r.status_code == 400
+    assert client.calls == []
+
+
+def test_gecko_token_view_accepts_a_mint(route_client, fake_gecko):
+    client = fake_gecko(pd.DataFrame([gecko_row()]))
+    r = route_client().get(
+        f"/servers/srv/dex/pools?source=gecko&view=token&query={SOL}"
+    )
+    assert r.status_code == 200
+    assert client.calls[0] == ("token", "solana", SOL)
+
+
+def test_gateway_source_lists_pools(route_client):
+    clmm = FakeClmm({"pools": [gateway_row()]})
+    r = route_client(client=FakeClient(clmm)).get(
+        "/servers/srv/dex/pools?source=gateway&connector=meteora&query=SOL"
+    )
+    assert r.status_code == 200
+    body = r.json()
+    assert body["source"] == "gateway"
+    assert body["pools"][0]["apr"] == 42.5
+    assert clmm.calls[0]["search_term"] == "SOL"
+
+
+def test_an_unknown_source_is_a_400(route_client):
+    assert route_client().get("/servers/srv/dex/pools?source=moon").status_code == 400
+
+
+def test_upstream_failure_is_an_empty_list_not_a_502(route_client, fake_gecko):
+    fake_gecko(error=RuntimeError("429"))
+    r = route_client().get("/servers/srv/dex/pools")
+    assert r.status_code == 200 and r.json()["pools"] == []
+
+
+def test_an_unreachable_server_is_an_empty_gateway_list(route_client):
+    r = route_client(client_error=RuntimeError("no server")).get(
+        "/servers/srv/dex/pools?source=gateway&connector=meteora"
+    )
+    assert r.status_code == 200 and r.json()["pools"] == []
+
+
+def test_no_server_access_is_a_403(route_client, fake_gecko):
+    fake_gecko(pd.DataFrame([gecko_row()]))
+    assert route_client(allowed=False).get("/servers/srv/dex/pools").status_code == 403
+    r = route_client(allowed=False).get(f"/servers/srv/dex/pools/{POOL}")
+    assert r.status_code == 403
+
+
+def test_pool_by_address_renders_from_the_url_alone(route_client, fake_gecko):
+    fake_gecko(pd.DataFrame([gecko_row()]))
+    r = route_client().get(f"/servers/srv/dex/pools/{POOL}?network=solana-mainnet-beta")
+    assert r.status_code == 200
+    pool = r.json()
+    assert pool["address"] == POOL
+    assert pool["trading_pair"] == f"{SOL}-USDC"
+    assert pool["gateway_network"] == "solana-mainnet-beta"
+
+
+def test_pool_by_address_rejects_a_non_address(route_client, fake_gecko):
+    client = fake_gecko(pd.DataFrame([gecko_row()]))
+    assert (
+        route_client().get("/servers/srv/dex/pools/not-an-address").status_code == 400
+    )
+    assert client.calls == []
+
+
+def test_unknown_pool_is_a_404(route_client, fake_gecko):
+    fake_gecko(pd.DataFrame())
+    assert route_client().get(f"/servers/srv/dex/pools/{POOL}").status_code == 404

From 8d90422602d29c55511f4025009f151f816e500b Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Thu, 13 Aug 2026 10:11:20 +0300
Subject: [PATCH 032/116] (feat) dex: a page where the pool is the unit
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

/dex browses pools from the three sources Telegram's /lp offers —
GeckoTerminal trending/top/new per chain, gecko token search by mint, and
the Gateway CLMM listings for Meteora and Orca with APR and bin step — and
/dex/{network}/{address} opens one.

The workspace pins everything to that exact pool: the chart carries its
address, the Order and LP tabs create in it, and the bottom pane shows the
executors already running there. The LP panel's auto-resolution is
overridden from the opened pool (via poolTouched), because the user picked
it and resolution must not second-guess the choice.

A pool with no CLMM provider — a router pool, a plain AMM, Uniswap v4 —
renders the Order tab and a stated reason where the LP tab would be. A
chain gecko indexes but Gateway cannot reach is greyed with the reason
rather than hidden. Neither is an error.

The chain selector is fed by the gateway networks in /market/venues, and
`connectorCapabilities` decides the tab set — same module Trade feeds,
one filter apart, no new connector predicate.
---
 frontend/src/App.tsx                          |   4 +
 frontend/src/components/dex/PoolBrowser.tsx   | 279 ++++++++++++
 .../src/components/dex/PoolSourceTabs.tsx     | 134 ++++++
 frontend/src/components/dex/PoolStats.tsx     | 109 +++++
 frontend/src/components/layout/AppShell.tsx   |   2 +
 frontend/src/lib/api.ts                       |  74 +++
 frontend/src/pages/Dex.tsx                    | 134 ++++++
 frontend/src/pages/DexPool.tsx                | 424 ++++++++++++++++++
 8 files changed, 1160 insertions(+)
 create mode 100644 frontend/src/components/dex/PoolBrowser.tsx
 create mode 100644 frontend/src/components/dex/PoolSourceTabs.tsx
 create mode 100644 frontend/src/components/dex/PoolStats.tsx
 create mode 100644 frontend/src/pages/Dex.tsx
 create mode 100644 frontend/src/pages/DexPool.tsx

diff --git a/frontend/src/App.tsx b/frontend/src/App.tsx
index e0051398..9baf1b4f 100644
--- a/frontend/src/App.tsx
+++ b/frontend/src/App.tsx
@@ -11,6 +11,8 @@ import { Agents } from "@/pages/Agents";
 import { BotDetail } from "@/pages/BotDetail";
 import { Bots } from "@/pages/Bots";
 import { CreateExecutor } from "@/pages/CreateExecutor";
+import { Dex } from "@/pages/Dex";
+import { DexPool } from "@/pages/DexPool";
 import { Executors } from "@/pages/Executors";
 import { Login } from "@/pages/Login";
 import { Portfolio } from "@/pages/Portfolio";
@@ -71,6 +73,8 @@ export default function App() {
                 <Route path="/bots" element={<Bots />} />
                 <Route path="/bots/:id" element={<BotDetail />} />
                 <Route path="/trade" element={<CreateExecutor />} />
+            <Route path="/dex" element={<Dex />} />
+            <Route path="/dex/:network/:address" element={<DexPool />} />
                 <Route path="/executors" element={<Executors />} />
                 <Route path="/executors/new" element={<Navigate to="/trade" replace />} />
                 <Route path="/executors/new-grid" element={<Navigate to="/trade?type=grid" replace />} />
diff --git a/frontend/src/components/dex/PoolBrowser.tsx b/frontend/src/components/dex/PoolBrowser.tsx
new file mode 100644
index 00000000..2465a613
--- /dev/null
+++ b/frontend/src/components/dex/PoolBrowser.tsx
@@ -0,0 +1,279 @@
+import { ChevronDown, ChevronUp } from "lucide-react";
+import { useMemo, useState } from "react";
+import { useNavigate } from "react-router-dom";
+
+import type { PoolSummary } from "@/lib/api";
+
+type SortKey =
+  | "name"
+  | "dex_id"
+  | "reserve_usd"
+  | "volume_24h"
+  | "price_change_24h"
+  | "apr";
+type SortDir = "asc" | "desc";
+
+function num(v: unknown): number {
+  const n = typeof v === "string" ? parseFloat(v) : (v as number);
+  return Number.isFinite(n) ? n : 0;
+}
+
+function usd(v: unknown): string {
+  const n = num(v);
+  if (!n) return "—";
+  if (n >= 1e9) return `$${(n / 1e9).toFixed(2)}B`;
+  if (n >= 1e6) return `$${(n / 1e6).toFixed(2)}M`;
+  if (n >= 1e3) return `$${(n / 1e3).toFixed(1)}K`;
+  return `$${n.toFixed(2)}`;
+}
+
+function pct(v: number | null | undefined): string {
+  return v === null || v === undefined ? "—" : `${v.toFixed(2)}%`;
+}
+
+function pairLabel(p: PoolSummary): string {
+  const base = p.base_symbol && p.base_symbol !== "???" ? p.base_symbol : null;
+  const quote =
+    p.quote_symbol && p.quote_symbol !== "???" ? p.quote_symbol : null;
+  return base && quote ? `${base}-${quote}` : p.name || p.address.slice(0, 8);
+}
+
+function SortTh({
+  label,
+  col,
+  sortKey,
+  sortDir,
+  onSort,
+  align = "left",
+}: {
+  label: string;
+  col: SortKey;
+  sortKey: SortKey;
+  sortDir: SortDir;
+  onSort: (k: SortKey) => void;
+  align?: "left" | "right";
+}) {
+  const active = sortKey === col;
+  return (
+    <th
+      onClick={() => onSort(col)}
+      className={`cursor-pointer select-none px-4 py-3 text-xs font-medium uppercase tracking-wider text-[var(--color-text-muted)] transition-colors hover:text-[var(--color-text)] ${
+        align === "right" ? "text-right" : "text-left"
+      }`}
+    >
+      <div
+        className={`flex items-center gap-1 ${align === "right" ? "justify-end" : ""}`}
+      >
+        {label}
+        {active &&
+          (sortDir === "asc" ? (
+            <ChevronUp className="h-3 w-3" />
+          ) : (
+            <ChevronDown className="h-3 w-3" />
+          ))}
+      </div>
+    </th>
+  );
+}
+
+interface Props {
+  pools: PoolSummary[];
+  isLoading: boolean;
+  /** Shown in place of rows when there are none — the empty state, not an error. */
+  emptyMessage: string;
+  /** True when Gateway supplied the rows, so APR and bin step have values. */
+  showGatewayColumns: boolean;
+}
+
+/**
+ * The pool table. A pool Gateway cannot reach is rendered greyed with the reason
+ * rather than hidden: a chain GeckoTerminal indexes but Condor does not trade on
+ * is a fact worth seeing, not a row to silently drop.
+ */
+export function PoolBrowser({
+  pools,
+  isLoading,
+  emptyMessage,
+  showGatewayColumns,
+}: Props) {
+  const navigate = useNavigate();
+  const [sortKey, setSortKey] = useState<SortKey>("reserve_usd");
+  const [sortDir, setSortDir] = useState<SortDir>("desc");
+
+  const handleSort = (key: SortKey) => {
+    if (key === sortKey) setSortDir(sortDir === "asc" ? "desc" : "asc");
+    else {
+      setSortKey(key);
+      setSortDir("desc");
+    }
+  };
+
+  const sorted = useMemo(() => {
+    const rows = [...pools];
+    rows.sort((a, b) => {
+      let cmp: number;
+      if (sortKey === "name") cmp = pairLabel(a).localeCompare(pairLabel(b));
+      else if (sortKey === "dex_id") cmp = a.dex_id.localeCompare(b.dex_id);
+      else cmp = num(a[sortKey]) - num(b[sortKey]);
+      return sortDir === "asc" ? cmp : -cmp;
+    });
+    return rows;
+  }, [pools, sortKey, sortDir]);
+
+  if (isLoading) {
+    return (
+      <div className="px-4 py-10 text-center text-sm text-[var(--color-text-muted)]">
+        Loading pools…
+      </div>
+    );
+  }
+
+  if (!sorted.length) {
+    return (
+      <div className="px-4 py-10 text-center text-sm text-[var(--color-text-muted)]">
+        {emptyMessage}
+      </div>
+    );
+  }
+
+  return (
+    <div className="overflow-x-auto">
+      <table className="w-full text-sm">
+        <thead>
+          <tr className="border-b border-[var(--color-border)] bg-[var(--color-surface)]">
+            <SortTh
+              label="Pair"
+              col="name"
+              sortKey={sortKey}
+              sortDir={sortDir}
+              onSort={handleSort}
+            />
+            <SortTh
+              label="DEX"
+              col="dex_id"
+              sortKey={sortKey}
+              sortDir={sortDir}
+              onSort={handleSort}
+            />
+            <SortTh
+              label="TVL"
+              col="reserve_usd"
+              sortKey={sortKey}
+              sortDir={sortDir}
+              onSort={handleSort}
+              align="right"
+            />
+            <SortTh
+              label="Vol 24h"
+              col="volume_24h"
+              sortKey={sortKey}
+              sortDir={sortDir}
+              onSort={handleSort}
+              align="right"
+            />
+            <SortTh
+              label="24h"
+              col="price_change_24h"
+              sortKey={sortKey}
+              sortDir={sortDir}
+              onSort={handleSort}
+              align="right"
+            />
+            {showGatewayColumns && (
+              <>
+                <SortTh
+                  label="APR"
+                  col="apr"
+                  sortKey={sortKey}
+                  sortDir={sortDir}
+                  onSort={handleSort}
+                  align="right"
+                />
+                <th className="px-4 py-3 text-right text-xs font-medium uppercase tracking-wider text-[var(--color-text-muted)]">
+                  Bin
+                </th>
+              </>
+            )}
+            <th className="px-4 py-3 text-right text-xs font-medium uppercase tracking-wider text-[var(--color-text-muted)]">
+              LP
+            </th>
+          </tr>
+        </thead>
+        <tbody>
+          {sorted.map((p) => {
+            const change = p.price_change_24h;
+            return (
+              <tr
+                key={`${p.dex_id}:${p.address}`}
+                onClick={() =>
+                  p.tradable &&
+                  navigate(`/dex/${p.gateway_network}/${p.address}`)
+                }
+                title={
+                  p.tradable
+                    ? undefined
+                    : "Gateway has no connector for this chain"
+                }
+                className={`border-b border-[var(--color-border)] transition-colors ${
+                  p.tradable
+                    ? "cursor-pointer hover:bg-[var(--color-surface-hover)]"
+                    : "opacity-40"
+                }`}
+              >
+                <td className="px-4 py-2.5 font-medium">
+                  {pairLabel(p)}
+                  {!p.tradable && (
+                    <span className="ml-2 text-[10px] font-normal text-[var(--color-text-muted)]">
+                      not on Gateway
+                    </span>
+                  )}
+                </td>
+                <td className="px-4 py-2.5 text-[var(--color-text-muted)]">
+                  {p.dex_id}
+                </td>
+                <td className="px-4 py-2.5 text-right tabular-nums">
+                  {usd(p.reserve_usd)}
+                </td>
+                <td className="px-4 py-2.5 text-right tabular-nums">
+                  {usd(p.volume_24h)}
+                </td>
+                <td
+                  className={`px-4 py-2.5 text-right tabular-nums ${
+                    change === null || change === undefined
+                      ? "text-[var(--color-text-muted)]"
+                      : change >= 0
+                        ? "text-[var(--color-green)]"
+                        : "text-[var(--color-red)]"
+                  }`}
+                >
+                  {pct(change)}
+                </td>
+                {showGatewayColumns && (
+                  <>
+                    <td className="px-4 py-2.5 text-right tabular-nums">
+                      {pct(p.apr)}
+                    </td>
+                    <td className="px-4 py-2.5 text-right tabular-nums text-[var(--color-text-muted)]">
+                      {p.bin_step ?? "—"}
+                    </td>
+                  </>
+                )}
+                <td className="px-4 py-2.5 text-right">
+                  {p.lp_supported ? (
+                    <span className="rounded border border-[var(--color-primary)] px-1.5 py-0.5 text-[10px] font-medium text-[var(--color-primary)]">
+                      LP
+                    </span>
+                  ) : (
+                    <span className="text-[10px] text-[var(--color-text-muted)]">
+                      swap only
+                    </span>
+                  )}
+                </td>
+              </tr>
+            );
+          })}
+        </tbody>
+      </table>
+    </div>
+  );
+}
diff --git a/frontend/src/components/dex/PoolSourceTabs.tsx b/frontend/src/components/dex/PoolSourceTabs.tsx
new file mode 100644
index 00000000..53e7e97e
--- /dev/null
+++ b/frontend/src/components/dex/PoolSourceTabs.tsx
@@ -0,0 +1,134 @@
+import { Search } from "lucide-react";
+
+/**
+ * Which pool listing to browse. The two upstreams take genuinely different
+ * arguments — GeckoTerminal ranks a *chain*'s pools and searches by token
+ * address, Gateway CLMM lists one *connector*'s pools and searches free text —
+ * so they are separate tabs rather than one filter row with modes.
+ */
+export type PoolSource =
+  | { kind: "gecko"; view: "trending" | "top" | "new" | "token" }
+  | { kind: "gateway"; connector: string };
+
+export const GECKO_TABS = [
+  { view: "trending", label: "Trending" },
+  { view: "top", label: "Top" },
+  { view: "new", label: "New" },
+  { view: "token", label: "Token" },
+] as const;
+
+/** The CLMM connectors Gateway can list pools for (and open positions in). */
+export const GATEWAY_TABS = [
+  { connector: "meteora", label: "Meteora" },
+  { connector: "orca", label: "Orca" },
+] as const;
+
+export function sameSource(a: PoolSource, b: PoolSource): boolean {
+  if (a.kind === "gecko" && b.kind === "gecko") return a.view === b.view;
+  if (a.kind === "gateway" && b.kind === "gateway")
+    return a.connector === b.connector;
+  return false;
+}
+
+const TAB_BASE =
+  "px-3 py-1.5 text-xs font-medium transition-colors border-b-2 -mb-px";
+
+interface Props {
+  source: PoolSource;
+  onSourceChange: (s: PoolSource) => void;
+  /** Gateway networks from `venues` — never a hardcoded chain list. */
+  networks: string[];
+  network: string;
+  onNetworkChange: (n: string) => void;
+  query: string;
+  onQueryChange: (q: string) => void;
+}
+
+export function PoolSourceTabs({
+  source,
+  onSourceChange,
+  networks,
+  network,
+  onNetworkChange,
+  query,
+  onQueryChange,
+}: Props) {
+  const searchLabel =
+    source.kind === "gateway"
+      ? "Filter pools by name…"
+      : "Token address (mint or 0x…)";
+  const searchShown = source.kind === "gateway" || source.view === "token";
+
+  return (
+    <div className="flex flex-wrap items-center gap-x-4 gap-y-2 border-b border-[var(--color-border)] px-4">
+      <div className="flex items-center">
+        {GECKO_TABS.map((t) => {
+          const active = sameSource(source, { kind: "gecko", view: t.view });
+          return (
+            <button
+              key={t.view}
+              onClick={() => onSourceChange({ kind: "gecko", view: t.view })}
+              className={`${TAB_BASE} ${
+                active
+                  ? "border-[var(--color-primary)] text-[var(--color-text)]"
+                  : "border-transparent text-[var(--color-text-muted)] hover:text-[var(--color-text)]"
+              }`}
+            >
+              {t.label}
+            </button>
+          );
+        })}
+        <span className="mx-2 h-4 w-px bg-[var(--color-border)]" />
+        {GATEWAY_TABS.map((t) => {
+          const active = sameSource(source, {
+            kind: "gateway",
+            connector: t.connector,
+          });
+          return (
+            <button
+              key={t.connector}
+              onClick={() =>
+                onSourceChange({ kind: "gateway", connector: t.connector })
+              }
+              className={`${TAB_BASE} ${
+                active
+                  ? "border-[var(--color-primary)] text-[var(--color-text)]"
+                  : "border-transparent text-[var(--color-text-muted)] hover:text-[var(--color-text)]"
+              }`}
+            >
+              {t.label}
+            </button>
+          );
+        })}
+      </div>
+
+      <div className="ml-auto flex items-center gap-2 py-1.5">
+        {source.kind === "gecko" && networks.length > 0 && (
+          <select
+            value={network}
+            onChange={(e) => onNetworkChange(e.target.value)}
+            className="rounded-md border border-[var(--color-border)] bg-[var(--color-bg)] px-2 py-1 text-xs text-[var(--color-text)]"
+          >
+            {networks.map((n) => (
+              <option key={n} value={n}>
+                {n}
+              </option>
+            ))}
+          </select>
+        )}
+        {searchShown && (
+          <div className="relative">
+            <Search className="pointer-events-none absolute left-2 top-1/2 h-3 w-3 -translate-y-1/2 text-[var(--color-text-muted)]" />
+            <input
+              value={query}
+              onChange={(e) => onQueryChange(e.target.value)}
+              placeholder={searchLabel}
+              spellCheck={false}
+              className="w-64 rounded-md border border-[var(--color-border)] bg-[var(--color-bg)] py-1 pl-7 pr-2 text-xs text-[var(--color-text)] placeholder:text-[var(--color-text-muted)]"
+            />
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
diff --git a/frontend/src/components/dex/PoolStats.tsx b/frontend/src/components/dex/PoolStats.tsx
new file mode 100644
index 00000000..f82aef4d
--- /dev/null
+++ b/frontend/src/components/dex/PoolStats.tsx
@@ -0,0 +1,109 @@
+import { Check, Copy, ExternalLink } from "lucide-react";
+import { useState } from "react";
+
+import type { PoolSummary } from "@/lib/api";
+
+/** The DEX web app URL for a pool — the same mapping Telegram's /lp offers. */
+function poolUrl(pool: PoolSummary): string {
+  const dex = pool.dex_id.toLowerCase();
+  const addr = pool.address;
+  if (dex.startsWith("meteora"))
+    return `https://app.meteora.ag/dlmm/${addr}?referrer=hummingbot`;
+  if (dex.startsWith("raydium")) return `https://raydium.io/clmm/pool/${addr}`;
+  if (dex.startsWith("orca")) return `https://www.orca.so/pools/${addr}`;
+  // GeckoTerminal indexes every pool it listed, so it is the universal fallback.
+  return `https://www.geckoterminal.com/${pool.gecko_network}/pools/${addr}`;
+}
+
+function num(v: unknown): number {
+  const n = typeof v === "string" ? parseFloat(v) : (v as number);
+  return Number.isFinite(n) ? n : 0;
+}
+
+function usd(v: unknown): string {
+  const n = num(v);
+  if (!n) return "—";
+  if (n >= 1e9) return `$${(n / 1e9).toFixed(2)}B`;
+  if (n >= 1e6) return `$${(n / 1e6).toFixed(2)}M`;
+  if (n >= 1e3) return `$${(n / 1e3).toFixed(1)}K`;
+  return `$${n.toFixed(2)}`;
+}
+
+function Stat({ label, value, tone }: { label: string; value: string; tone?: string }) {
+  return (
+    <div className="flex flex-col">
+      <span className="text-[10px] uppercase tracking-wider text-[var(--color-text-muted)]">
+        {label}
+      </span>
+      <span className={`text-xs tabular-nums ${tone ?? "text-[var(--color-text)]"}`}>
+        {value}
+      </span>
+    </div>
+  );
+}
+
+/** The pool's identity and market numbers, above the chart. */
+export function PoolStats({ pool }: { pool: PoolSummary }) {
+  const [copied, setCopied] = useState(false);
+  const change = pool.price_change_24h;
+
+  const copy = () => {
+    navigator.clipboard.writeText(pool.address);
+    setCopied(true);
+    setTimeout(() => setCopied(false), 1500);
+  };
+
+  return (
+    <div className="flex flex-wrap items-center gap-x-6 gap-y-2">
+      <Stat label="DEX" value={pool.dex_id} />
+      <Stat label="TVL" value={usd(pool.reserve_usd)} />
+      <Stat label="Vol 24h" value={usd(pool.volume_24h)} />
+      <Stat
+        label="24h"
+        value={change === null || change === undefined ? "—" : `${change.toFixed(2)}%`}
+        tone={
+          change === null || change === undefined
+            ? undefined
+            : change >= 0
+              ? "text-[var(--color-green)]"
+              : "text-[var(--color-red)]"
+        }
+      />
+      {pool.apr !== null && pool.apr !== undefined && (
+        <Stat label="APR" value={`${pool.apr.toFixed(2)}%`} />
+      )}
+      {pool.bin_step !== null && pool.bin_step !== undefined && (
+        <Stat label="Bin step" value={String(pool.bin_step)} />
+      )}
+      {pool.base_fee_percentage !== null &&
+        pool.base_fee_percentage !== undefined && (
+          <Stat label="Fee" value={`${pool.base_fee_percentage}%`} />
+        )}
+
+      <div className="ml-auto flex items-center gap-1.5">
+        <span
+          className="font-mono text-[11px] text-[var(--color-text-muted)]"
+          title={pool.address}
+        >
+          {pool.address.slice(0, 6)}…{pool.address.slice(-4)}
+        </span>
+        <button
+          onClick={copy}
+          title="Copy pool address"
+          className="rounded p-0.5 text-[var(--color-text-muted)] hover:text-[var(--color-text)]"
+        >
+          {copied ? <Check className="h-3 w-3" /> : <Copy className="h-3 w-3" />}
+        </button>
+        <a
+          href={poolUrl(pool)}
+          target="_blank"
+          rel="noreferrer"
+          title="Open on the DEX"
+          className="rounded p-0.5 text-[var(--color-text-muted)] hover:text-[var(--color-text)]"
+        >
+          <ExternalLink className="h-3 w-3" />
+        </a>
+      </div>
+    </div>
+  );
+}
diff --git a/frontend/src/components/layout/AppShell.tsx b/frontend/src/components/layout/AppShell.tsx
index 0f17fc06..a454f4e8 100644
--- a/frontend/src/components/layout/AppShell.tsx
+++ b/frontend/src/components/layout/AppShell.tsx
@@ -4,6 +4,7 @@ import {
   Bot,
   Brain,
   Bug,
+  Droplets,
   Eye,
   Moon,
   Settings,
@@ -29,6 +30,7 @@ const NAV_ITEMS = [
   { to: "/", icon: Brain, label: "Agents" },
   { to: "/portfolio", icon: Wallet, label: "Portfolio" },
   { to: "/trade", icon: Swords, label: "Trade" },
+  { to: "/dex", icon: Droplets, label: "DEX" },
   { to: "/bots", icon: Bot, label: "Bots" },
   { to: "/executors", icon: Activity, label: "Executors" },
   { to: "/routines", icon: Zap, label: "Routines" },
diff --git a/frontend/src/lib/api.ts b/frontend/src/lib/api.ts
index a5bcbfbf..dc8f3696 100644
--- a/frontend/src/lib/api.ts
+++ b/frontend/src/lib/api.ts
@@ -274,6 +274,61 @@ interface WireVenue {
   clmm_lp: boolean;
 }
 
+/**
+ * One pool as the DEX browser and workspace see it: the market numbers from the
+ * upstream, plus the venue facts the server decides (`lp_supported`, `tradable`,
+ * `trading_pair`) because they depend on which connectors Condor drives, not on
+ * anything the browser can know.
+ */
+export interface PoolSummary {
+  address: string;
+  name: string;
+  source: "gecko" | "gateway";
+  dex_id: string;
+  /** Chain as the caller named it, and the Gateway network its rows link to. */
+  network: string;
+  gecko_network: string;
+  gateway_network: string;
+  base_symbol: string;
+  quote_symbol: string;
+  base_token_symbol: string;
+  quote_token_symbol: string;
+  base_token_address: string;
+  quote_token_address: string;
+  /** `<base_mint>-<quote_symbol>`, the form LP and DEX order executors carry. */
+  trading_pair: string;
+  /** An `lp_executor` provider (`meteora/clmm`), or null when the pool is not CLMM. */
+  lp_provider: string | null;
+  lp_supported: boolean;
+  /** False when GeckoTerminal indexes this chain but Gateway does not reach it. */
+  tradable: boolean;
+  has_bins: boolean;
+  reserve_usd: string | number | null;
+  volume_24h: number | null;
+  price_change_24h: number | null;
+  current_price?: number | null;
+  base_token_price_usd?: string | number | null;
+  quote_token_price_usd?: string | number | null;
+  /** Gateway CLMM only. */
+  apr?: number | null;
+  bin_step?: number | null;
+  base_fee_percentage?: number | null;
+  pool_created_at?: string | null;
+}
+
+export interface PoolQuery {
+  source: "gecko" | "gateway";
+  /** source=gecko: the chain, as a Gateway network id or a gecko chain id. */
+  network?: string;
+  /** source=gecko: trending | top | new | token. */
+  view?: string;
+  /** source=gateway: the CLMM connector. */
+  connector?: string;
+  /** source=gecko+view=token: a token address. source=gateway: free text. */
+  query?: string;
+  limit?: number;
+}
+
 export interface DexPoolInfo {
   pool_address: string | null;
   dex_id: string | null;
@@ -1253,6 +1308,25 @@ export const api = {
       `/api/v1/servers/${encodeURIComponent(server)}/market/dex-pool?connector=${encodeURIComponent(connector)}&trading_pair=${encodeURIComponent(pair)}`,
     ),
 
+  /** Pools to browse, from GeckoTerminal (by chain) or Gateway CLMM (by connector). */
+  getDexPools: (server: string, q: PoolQuery) => {
+    const params = new URLSearchParams({ source: q.source });
+    if (q.network) params.set("network", q.network);
+    if (q.view) params.set("view", q.view);
+    if (q.connector) params.set("connector", q.connector);
+    if (q.query) params.set("query", q.query);
+    params.set("limit", String(q.limit ?? 20));
+    return apiFetch<{ pools: PoolSummary[]; source: string }>(
+      `/api/v1/servers/${encodeURIComponent(server)}/dex/pools?${params}`,
+    ).then((r) => r.pools ?? []);
+  },
+
+  /** One pool by address, so /dex/{network}/{address} renders from the URL alone. */
+  getDexPoolByAddress: (server: string, address: string, network: string) =>
+    apiFetch<PoolSummary>(
+      `/api/v1/servers/${encodeURIComponent(server)}/dex/pools/${encodeURIComponent(address)}?network=${encodeURIComponent(network)}`,
+    ),
+
   getPrice: (server: string, connector: string, pair: string) =>
     apiFetch<MarketPrice>(
       `/api/v1/servers/${encodeURIComponent(server)}/market/prices?connector=${encodeURIComponent(connector)}&trading_pair=${encodeURIComponent(pair)}`,
diff --git a/frontend/src/pages/Dex.tsx b/frontend/src/pages/Dex.tsx
new file mode 100644
index 00000000..c4117448
--- /dev/null
+++ b/frontend/src/pages/Dex.tsx
@@ -0,0 +1,134 @@
+import { useQuery } from "@tanstack/react-query";
+import { useEffect, useMemo, useState } from "react";
+
+import { NoServerCard } from "@/components/NoServerCard";
+import { PoolBrowser } from "@/components/dex/PoolBrowser";
+import {
+  type PoolSource,
+  PoolSourceTabs,
+} from "@/components/dex/PoolSourceTabs";
+import { useServer } from "@/hooks/useServer";
+import { api } from "@/lib/api";
+
+/** GeckoTerminal rate-limits per IP across every viewer and every polling chart. */
+const POOL_STALE_MS = 30_000;
+const SEARCH_DEBOUNCE_MS = 400;
+
+/**
+ * Browse pools, because on Gateway the pool *is* the decision.
+ *
+ * A venue with an order book has one canonical SOL-USDC; Gateway has dozens
+ * across Meteora, Orca, Raydium and Uniswap with different fee tiers, bin steps,
+ * TVL and APR. So this page is pool-first: pick one, and the workspace behind it
+ * pins the chart, the stats and both executors to that exact pool.
+ */
+export function Dex() {
+  const { server } = useServer();
+  const [source, setSource] = useState<PoolSource>({
+    kind: "gecko",
+    view: "trending",
+  });
+  const [network, setNetwork] = useState("");
+  const [query, setQuery] = useState("");
+  const [debouncedQuery, setDebouncedQuery] = useState("");
+
+  // A browser that refetches per keystroke would exhaust the same GeckoTerminal
+  // budget the candle poll loop depends on.
+  useEffect(() => {
+    const t = setTimeout(() => setDebouncedQuery(query.trim()), SEARCH_DEBOUNCE_MS);
+    return () => clearTimeout(t);
+  }, [query]);
+
+  const { data: venues = [] } = useQuery({
+    queryKey: ["venues", server],
+    queryFn: () => api.getVenues(server!),
+    enabled: !!server,
+    staleTime: 5 * 60 * 1000,
+  });
+
+  // The chains to offer are the venues Trade does *not* take: the complement of
+  // `hummingbotMarketData`, exactly as CreateExecutor computes it. Never a
+  // hardcoded list.
+  const networks = useMemo(
+    () => venues.filter((v) => !v.hummingbotMarketData).map((v) => v.name),
+    [venues],
+  );
+
+  // Derived, not synced: venues arrive after the first render, so the selection
+  // falls back to the first chain until the user picks one that exists.
+  const activeNetwork =
+    network && networks.includes(network) ? network : (networks[0] ?? "");
+
+  const isTokenSearch = source.kind === "gecko" && source.view === "token";
+  const enabled =
+    !!server &&
+    (source.kind === "gateway" ||
+      (!!activeNetwork && (!isTokenSearch || !!debouncedQuery)));
+
+  const { data: pools = [], isFetching } = useQuery({
+    queryKey: [
+      "dex-pools",
+      server,
+      source.kind,
+      source.kind === "gecko" ? source.view : source.connector,
+      activeNetwork,
+      debouncedQuery,
+    ],
+    queryFn: () =>
+      api.getDexPools(
+        server!,
+        source.kind === "gecko"
+          ? {
+              source: "gecko",
+              network: activeNetwork,
+              view: source.view,
+              query: isTokenSearch ? debouncedQuery : undefined,
+            }
+          : {
+              source: "gateway",
+              connector: source.connector,
+              query: debouncedQuery || undefined,
+            },
+      ),
+    enabled,
+    staleTime: POOL_STALE_MS,
+  });
+
+  if (!server) {
+    return <NoServerCard message="Select a server from the sidebar to browse DEX pools." />;
+  }
+
+  const emptyMessage = isTokenSearch && !debouncedQuery
+    ? "Paste a token address to find its pools."
+    : "No pools found.";
+
+  return (
+    <div className="flex flex-col gap-4">
+      <div>
+        <h1 className="text-lg font-semibold">DEX</h1>
+        <p className="text-sm text-[var(--color-text-muted)]">
+          Pools on the networks Condor trades through Gateway. Open one to chart
+          it, swap in it and provide liquidity to it.
+        </p>
+      </div>
+
+      <div className="overflow-hidden rounded-lg border border-[var(--color-border)]">
+        <PoolSourceTabs
+          source={source}
+          onSourceChange={setSource}
+          networks={networks}
+          network={activeNetwork}
+          onNetworkChange={setNetwork}
+          query={query}
+          onQueryChange={setQuery}
+        />
+        <PoolBrowser
+          pools={pools}
+          isLoading={isFetching && !pools.length}
+          emptyMessage={emptyMessage}
+          showGatewayColumns={source.kind === "gateway"}
+        />
+      </div>
+    </div>
+  );
+}
diff --git a/frontend/src/pages/DexPool.tsx b/frontend/src/pages/DexPool.tsx
new file mode 100644
index 00000000..8e826265
--- /dev/null
+++ b/frontend/src/pages/DexPool.tsx
@@ -0,0 +1,424 @@
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { ArrowLeft, CheckCircle, Copy, X } from "lucide-react";
+import { useEffect, useMemo, useState } from "react";
+import { useNavigate, useParams } from "react-router-dom";
+
+import { NoServerCard } from "@/components/NoServerCard";
+import { PoolStats } from "@/components/dex/PoolStats";
+import {
+  LPConfigPanel,
+  useLpConfig,
+} from "@/components/executor/LPConfigPanel";
+import {
+  OrderConfigPanel,
+  useOrderConfig,
+} from "@/components/executor/OrderConfigPanel";
+import { TradeBottomPane } from "@/components/trade/TradeBottomPane";
+import { TradeChart } from "@/components/trade/TradeChart";
+import { useMainControllerData } from "@/hooks/useMainControllerData";
+import { useResizeDrag } from "@/hooks/useResizeDrag";
+import { useServer } from "@/hooks/useServer";
+import { api } from "@/lib/api";
+import { connectorCapabilities } from "@/lib/connector-capabilities";
+import { INTERVALS, LOOKBACK_OPTIONS } from "@/lib/gridExecutor";
+
+type Tab = "order" | "lp";
+
+/**
+ * One pool, and everything you can do in it.
+ *
+ * Reads the pool from the URL rather than from the browser that linked here, so
+ * a deep link or a reload renders the same workspace with no prior state. The
+ * chart, both executors and the bottom pane are all pinned to this exact pool —
+ * which is the whole point of a pool-first page: on Gateway, `SOL-USDC` names
+ * dozens of pools and which one you are in *is* the decision.
+ */
+export function DexPool() {
+  const { server } = useServer();
+  const navigate = useNavigate();
+  const queryClient = useQueryClient();
+  const { network = "", address = "" } = useParams();
+
+  const [wantedTab, setTab] = useState<Tab>("order");
+  const [interval, setIntervalValue] = useState("1m");
+  const [lookbackSeconds, setLookbackSeconds] = useState(3 * 86400);
+  const [rightPanelWidth, setRightPanelWidth] = useState(288);
+  const [bottomPaneHeight, setBottomPaneHeight] = useState(200);
+  const [selectedExecutorId, setSelectedExecutorId] = useState<string | null>(null);
+  const [successId, setSuccessId] = useState<string | null>(null);
+
+  const { onMouseDown: startHDrag } = useResizeDrag({
+    axis: "x",
+    value: rightPanelWidth,
+    onChange: setRightPanelWidth,
+    min: 260,
+    max: 500,
+    direction: "inverted",
+    cursor: "col-resize",
+  });
+  const { onMouseDown: startVDrag } = useResizeDrag({
+    axis: "y",
+    value: bottomPaneHeight,
+    onChange: setBottomPaneHeight,
+    min: 100,
+    max: 500,
+    direction: "inverted",
+    cursor: "row-resize",
+  });
+
+  const {
+    data: pool,
+    isLoading: poolLoading,
+    error: poolError,
+  } = useQuery({
+    queryKey: ["dex-pool-by-address", server, network, address],
+    queryFn: () => api.getDexPoolByAddress(server!, address, network),
+    enabled: !!server && !!network && !!address,
+    staleTime: 60 * 1000,
+  });
+
+  const { data: venues = [] } = useQuery({
+    queryKey: ["venues", server],
+    queryFn: () => api.getVenues(server!),
+    enabled: !!server,
+    staleTime: 5 * 60 * 1000,
+  });
+
+  // The same function Trade feeds; it is handed a gateway network here instead
+  // of a CLOB venue, and answers ["order"] (+ "lp" when the venue does CLMM).
+  const caps = useMemo(
+    () => connectorCapabilities(network, venues),
+    [network, venues],
+  );
+
+  const pair = pool?.trading_pair ?? "";
+  const lpAvailable = caps.supportsLp && !!pool?.lp_supported;
+
+  const orderConfig = useOrderConfig();
+  const lpConfig = useLpConfig(server ?? null, network, pair, lpAvailable);
+
+  // The user picked a pool. Auto-resolution must not second-guess it, so the
+  // opened pool is written straight into the LP config — which sets poolTouched
+  // and makes every later RESOLVED a no-op.
+  useEffect(() => {
+    if (!pool?.lp_supported || !pool.lp_provider) return;
+    lpConfig.dispatch({
+      type: "SET_FIELD",
+      field: "pool_address",
+      value: pool.address,
+    });
+    lpConfig.dispatch({
+      type: "SET_FIELD",
+      field: "lp_provider",
+      value: pool.lp_provider,
+    });
+  }, [pool?.address, pool?.lp_provider, pool?.lp_supported]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  // Derived, not synced: a pool with no CLMM provider has no LP tab to select,
+  // and the pool is only known after the fetch resolves.
+  const tab: Tab = wantedTab === "lp" && !lpAvailable ? "order" : wantedTab;
+
+  const { executors, overlays, positions, isLoadingPositions } =
+    useMainControllerData(server ?? null, network, pair);
+
+  const active = tab === "lp" ? lpConfig : orderConfig;
+  const currentPrice = pool?.current_price ?? null;
+
+  const createMutation = useMutation({
+    mutationFn: () => {
+      if (!server) throw new Error("No server");
+      const payload =
+        tab === "lp"
+          ? // No isSpot: an LP position has no leverage, and connector is the network.
+            lpConfig.buildPayload(network, pair)
+          : orderConfig.buildPayload(network, pair, true);
+      return api.createExecutor(server, payload);
+    },
+    onSuccess: (data) => {
+      active.save();
+      setSuccessId(data.executor_id);
+      queryClient.invalidateQueries({ queryKey: ["executors", server, "main", pair] });
+      queryClient.invalidateQueries({ queryKey: ["consolidated-positions", server] });
+      setSelectedExecutorId(data.executor_id);
+    },
+  });
+
+  if (!server) {
+    return <NoServerCard message="Select a server from the sidebar to open a pool." />;
+  }
+
+  if (poolLoading) {
+    return (
+      <div className="flex min-h-[60vh] items-center justify-center text-sm text-[var(--color-text-muted)]">
+        Loading pool…
+      </div>
+    );
+  }
+
+  if (poolError || !pool) {
+    return (
+      <div className="flex min-h-[60vh] flex-col items-center justify-center gap-3">
+        <p className="text-sm text-[var(--color-text-muted)]">
+          No pool at {address.slice(0, 8)}… on {network}.
+        </p>
+        <button
+          onClick={() => navigate("/dex")}
+          className="rounded-md border border-[var(--color-border)] px-3 py-1.5 text-xs text-[var(--color-text-muted)] hover:text-[var(--color-text)]"
+        >
+          Back to pools
+        </button>
+      </div>
+    );
+  }
+
+  const pairLabel =
+    pool.base_symbol !== "???" && pool.quote_symbol !== "???"
+      ? `${pool.base_symbol}-${pool.quote_symbol}`
+      : pool.name;
+
+  return (
+    <div className="-m-6 flex h-[calc(100%+3rem)] flex-col">
+      {/* Top bar */}
+      <div className="flex shrink-0 flex-wrap items-center gap-x-4 gap-y-2 border-b border-[var(--color-border)] px-3 py-2">
+        <button
+          onClick={() => navigate("/dex")}
+          className="rounded p-1 text-[var(--color-text-muted)] hover:bg-[var(--color-surface-hover)] hover:text-[var(--color-text)]"
+          title="Back to pools"
+        >
+          <ArrowLeft className="h-4 w-4" />
+        </button>
+        <div className="flex flex-col">
+          <span className="text-sm font-semibold">{pairLabel}</span>
+          <span className="text-[10px] text-[var(--color-text-muted)]">{network}</span>
+        </div>
+        <div className="min-w-0 flex-1">
+          <PoolStats pool={pool} />
+        </div>
+      </div>
+
+      {/* Interval / lookback */}
+      <div className="flex shrink-0 items-center gap-4 border-b border-[var(--color-border)] px-3 py-1.5">
+        <div className="flex items-center gap-1">
+          {INTERVALS.map((iv) => (
+            <button
+              key={iv}
+              onClick={() => setIntervalValue(iv)}
+              className={`rounded px-1.5 py-0.5 text-[11px] transition-colors ${
+                interval === iv
+                  ? "bg-[var(--color-primary)]/15 text-[var(--color-primary)]"
+                  : "text-[var(--color-text-muted)] hover:text-[var(--color-text)]"
+              }`}
+            >
+              {iv}
+            </button>
+          ))}
+        </div>
+        <div className="flex items-center gap-1">
+          {LOOKBACK_OPTIONS.map((o) => (
+            <button
+              key={o.label}
+              onClick={() => setLookbackSeconds(o.seconds)}
+              className={`rounded px-1.5 py-0.5 text-[11px] transition-colors ${
+                lookbackSeconds === o.seconds
+                  ? "bg-[var(--color-primary)]/15 text-[var(--color-primary)]"
+                  : "text-[var(--color-text-muted)] hover:text-[var(--color-text)]"
+              }`}
+            >
+              {o.label}
+            </button>
+          ))}
+        </div>
+      </div>
+
+      <div className="flex min-h-0 flex-1">
+        <div className="flex min-w-0 flex-1 flex-col">
+          <div className="min-h-0 flex-1 overflow-hidden">
+            <TradeChart
+              key={`${network}:${pool.address}:${interval}`}
+              server={server}
+              connector={network}
+              pair={pair}
+              // The pool the user opened, not the deepest pool for the pair.
+              poolAddress={pool.address}
+              interval={interval}
+              lookbackSeconds={lookbackSeconds}
+              startPrice={active.chartProps.startPrice}
+              endPrice={active.chartProps.endPrice}
+              limitPrice={active.chartProps.limitPrice}
+              side={active.chartProps.side}
+              minSpread={0}
+              activePickField={active.chartProps.activePickField}
+              onPriceSet={active.handleChartPriceSet}
+              extraLines={active.chartProps.extraLines}
+              executorOverlays={overlays}
+              positions={positions}
+              selectedExecutorId={selectedExecutorId}
+              onExecutorDeselect={() => setSelectedExecutorId(null)}
+            />
+          </div>
+
+          <div
+            className="group/hdrag relative h-1.5 shrink-0 cursor-row-resize border-y border-[var(--color-border)] bg-[var(--color-bg)] transition-colors hover:bg-[var(--color-primary)]/10 active:bg-[var(--color-primary)]/20"
+            onMouseDown={startVDrag}
+          >
+            <div className="absolute inset-x-0 top-1/2 mx-auto h-px w-12 -translate-y-1/2 rounded bg-amber-400/60 transition-colors group-hover/hdrag:bg-amber-400" />
+          </div>
+
+          <div style={{ height: bottomPaneHeight }} className="shrink-0 overflow-hidden">
+            <TradeBottomPane
+              executors={executors}
+              positions={positions}
+              isLoadingPositions={isLoadingPositions}
+              connector={network}
+              pair={pair}
+              isSpot
+              selectedExecutorId={selectedExecutorId}
+              onExecutorSelect={(ex) => setSelectedExecutorId(ex?.id ?? null)}
+            />
+          </div>
+        </div>
+
+        <div
+          className="group/vdrag relative w-1.5 shrink-0 cursor-col-resize border-x border-[var(--color-border)] bg-[var(--color-bg)] transition-colors hover:bg-[var(--color-primary)]/10 active:bg-[var(--color-primary)]/20"
+          onMouseDown={startHDrag}
+        >
+          <div className="absolute inset-y-0 left-1/2 my-auto h-12 w-px -translate-x-1/2 rounded bg-amber-400/60 transition-colors group-hover/vdrag:bg-amber-400" />
+        </div>
+
+        <div
+          className="flex shrink-0 flex-col border-l border-[var(--color-border)]"
+          style={{ width: rightPanelWidth }}
+        >
+          <div className="flex border-b border-[var(--color-border)]">
+            <button
+              onClick={() => setTab("order")}
+              className={`flex-1 px-3 py-2 text-xs font-medium transition-colors ${
+                tab === "order"
+                  ? "border-b-2 border-[var(--color-primary)] text-[var(--color-text)]"
+                  : "text-[var(--color-text-muted)] hover:text-[var(--color-text)]"
+              }`}
+            >
+              Order
+            </button>
+            {lpAvailable && (
+              <button
+                onClick={() => setTab("lp")}
+                className={`flex-1 px-3 py-2 text-xs font-medium transition-colors ${
+                  tab === "lp"
+                    ? "border-b-2 border-[var(--color-primary)] text-[var(--color-text)]"
+                    : "text-[var(--color-text-muted)] hover:text-[var(--color-text)]"
+                }`}
+              >
+                LP
+              </button>
+            )}
+          </div>
+
+          {/* A pool with no CLMM provider is a state, not an error: a router pool,
+              a plain AMM or a Uniswap v4 pool can still be swapped in. */}
+          {!lpAvailable && (
+            <p className="border-b border-[var(--color-border)] px-3 py-2 text-[10px] leading-relaxed text-[var(--color-text-muted)]">
+              No liquidity position available here —{" "}
+              {caps.supportsLp
+                ? `${pool.dex_id} is not a concentrated-liquidity venue Condor can add to.`
+                : `${network} takes no CLMM position.`}{" "}
+              Market swaps still work.
+            </p>
+          )}
+
+          <div className="flex-1 overflow-y-auto">
+            {tab === "order" ? (
+              <OrderConfigPanel
+                state={orderConfig.state}
+                dispatch={orderConfig.dispatch}
+                validation={orderConfig.validation}
+                currentPrice={currentPrice}
+                isSpot
+                pair={pairLabel}
+                strategies={caps.orderStrategies}
+              />
+            ) : (
+              <LPConfigPanel
+                state={lpConfig.state}
+                dispatch={lpConfig.dispatch}
+                validation={lpConfig.validation}
+                currentPrice={currentPrice}
+                pair={pairLabel}
+                pool={lpConfig.pool}
+                poolFetching={lpConfig.poolFetching}
+              />
+            )}
+          </div>
+
+          <div className="border-t border-[var(--color-border)] p-3">
+            {!active.validation.valid && (
+              <p className="mb-2 text-[11px] text-[var(--color-red)]">
+                {active.validation.errors[0]}
+              </p>
+            )}
+            <button
+              onClick={() => createMutation.mutate()}
+              disabled={!active.validation.valid || createMutation.isPending || !pair}
+              className="w-full rounded-lg bg-[var(--color-primary)] px-4 py-2 text-xs font-semibold text-white transition-colors hover:brightness-110 disabled:cursor-not-allowed disabled:opacity-40"
+            >
+              {createMutation.isPending
+                ? "Creating…"
+                : tab === "lp"
+                  ? "Create LP Position"
+                  : "Create Order"}
+            </button>
+          </div>
+        </div>
+      </div>
+
+      {successId && (
+        <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/50 backdrop-blur-sm">
+          <div className="relative w-[360px] rounded-xl border border-[var(--color-green)]/30 bg-[var(--color-surface)] p-6 shadow-2xl shadow-black/40">
+            <button
+              onClick={() => setSuccessId(null)}
+              className="absolute right-3 top-3 rounded p-1 text-[var(--color-text-muted)] hover:bg-[var(--color-surface-hover)] hover:text-[var(--color-text)]"
+            >
+              <X className="h-4 w-4" />
+            </button>
+            <div className="mb-4 flex justify-center">
+              <div className="flex h-12 w-12 items-center justify-center rounded-full bg-[var(--color-green)]/15">
+                <CheckCircle className="h-6 w-6 text-[var(--color-green)]" />
+              </div>
+            </div>
+            <h3 className="mb-1 text-center text-sm font-semibold">
+              {tab === "lp" ? "LP Position" : "Order"} Created
+            </h3>
+            <p className="mb-4 text-center text-[11px] text-[var(--color-text-muted)]">
+              In {pairLabel} on {pool.dex_id}
+            </p>
+            <div className="mb-4 flex items-center justify-between rounded-lg border border-[var(--color-border)] bg-[var(--color-bg)] p-3 text-[11px]">
+              <span className="text-[var(--color-text-muted)]">Executor ID</span>
+              <div className="flex items-center gap-1.5">
+                <span className="font-mono">{successId.slice(0, 12)}…</span>
+                <button
+                  onClick={() => navigator.clipboard.writeText(successId)}
+                  className="rounded p-0.5 text-[var(--color-text-muted)] hover:text-[var(--color-text)]"
+                  title="Copy full ID"
+                >
+                  <Copy className="h-3 w-3" />
+                </button>
+              </div>
+            </div>
+            <button
+              onClick={() => setSuccessId(null)}
+              className="w-full rounded-lg bg-[var(--color-primary)] px-4 py-2 text-xs font-semibold text-white transition-colors hover:brightness-110"
+            >
+              Continue
+            </button>
+          </div>
+        </div>
+      )}
+
+      {createMutation.isError && (
+        <div className="absolute bottom-16 right-4 rounded-lg border border-[var(--color-red)]/30 bg-[var(--color-red)]/10 px-4 py-2 text-sm text-[var(--color-red)]">
+          {(createMutation.error as Error).message}
+        </div>
+      )}
+    </div>
+  );
+}

From 86c27a4aefbfc2fa69d3714dcc2b829e4b0abfe0 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Thu, 13 Aug 2026 10:13:54 +0300
Subject: [PATCH 033/116] (feat) trade: CLOB-only, gateway networks go to /dex
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Trade is for venues with an order book — whether or not the venue is
decentralized, so hyperliquid and xrpl stay and solana-mainnet-beta goes.
That is one filter on `hummingbotMarketData`, a fact /market/venues
already publishes; no fifth connector predicate is invented and
connector-capabilities is untouched.

`allConnectors` stops concatenating the two halves, `dexConnectors` and
the selector's DEX group go with them, and a persisted gateway network
retires itself through the sync effect that was already there — no
migration code. A /trade URL naming a gateway network now redirects to
/dex, where its pools rather than its pairs are the thing to pick.

The LP tab disappears from Trade on its own: no CLOB venue reports
clmm_lp, so `caps.executorTypes` never offers it.
---
 .../components/market/ExchangeSelector.tsx    | 59 ++++---------------
 frontend/src/pages/CreateExecutor.tsx         | 36 +++++++----
 2 files changed, 36 insertions(+), 59 deletions(-)

diff --git a/frontend/src/components/market/ExchangeSelector.tsx b/frontend/src/components/market/ExchangeSelector.tsx
index 8d394e63..e4663af3 100644
--- a/frontend/src/components/market/ExchangeSelector.tsx
+++ b/frontend/src/components/market/ExchangeSelector.tsx
@@ -1,38 +1,19 @@
-import { useEffect, useRef, useState, type ReactNode } from "react";
+import { useEffect, useRef, useState } from "react";
 import { ChevronDown } from "lucide-react";
 
+/**
+ * Every venue this selector lists has an order book. Gateway networks live on
+ * the DEX page, where the pool — not the venue — is the unit of navigation, so
+ * there is no second group here to head.
+ */
 interface ExchangeSelectorProps {
   connectors: string[];
   value: string;
   onChange: (v: string) => void;
-  /**
-   * Venues with no Hummingbot market feed — listed under their own heading and
-   * formatted as chain ids. Fed by `!hummingbotMarketData`, not by gateway-network
-   * membership: `xrpl` is a gateway-adjacent id that trades through a real order
-   * book, so it belongs in the exchange group and reads as `Xrpl`.
-   */
-  dexConnectors?: string[];
-}
-
-/**
- * Format a gateway network id the way the Telegram surface does, so the two read
- * alike: `solana-mainnet-beta` → `Solana`, `solana-devnet` → `Solana Dev`.
- * Mirrors `utils/telegram_formatters.format_network_display`.
- */
-function formatNetwork(id: string) {
-  const parts = id.split("-");
-  const chain = parts[0].charAt(0).toUpperCase() + parts[0].slice(1);
-  if (parts.length === 1) return chain;
-  const net = parts[1];
-  if (net === "mainnet") return chain;
-  if (net === "devnet") return `${chain} Dev`;
-  if (net === "testnet") return `${chain} Test`;
-  return `${chain} ${net.slice(0, 4)}`;
 }
 
 // Format connector name for display (e.g. "binance_perpetual" -> "Binance Perp")
-function formatName(name: string, isDex = false) {
-  if (isDex) return formatNetwork(name);
+function formatName(name: string) {
   return name
     .replace(/_perpetual$/, " perp")
     .replace(/_/g, " ")
@@ -43,13 +24,9 @@ export function ExchangeSelector({
   connectors,
   value,
   onChange,
-  dexConnectors = [],
 }: ExchangeSelectorProps) {
   const [open, setOpen] = useState(false);
   const ref = useRef<HTMLDivElement>(null);
-  const dexSet = new Set(dexConnectors);
-  const cexList = connectors.filter((c) => !dexSet.has(c));
-  const dexList = connectors.filter((c) => dexSet.has(c));
 
   useEffect(() => {
     if (!open) return;
@@ -66,22 +43,16 @@ export function ExchangeSelector({
         onClick={() => setOpen(!open)}
         className="flex items-center gap-1.5 px-3 py-2.5 text-xs transition-colors hover:bg-[var(--color-surface-hover)]"
       >
-        <span className="font-medium text-[var(--color-primary)]">{formatName(value, dexSet.has(value))}</span>
+        <span className="font-medium text-[var(--color-primary)]">{formatName(value)}</span>
         <ChevronDown className={`h-3 w-3 text-[var(--color-text-muted)] transition-transform ${open ? "rotate-180" : ""}`} />
       </button>
 
       {open && (
         <div className="absolute left-0 top-full z-50 mt-px min-w-[180px] overflow-hidden rounded-b-lg border border-t-0 border-[var(--color-border)] bg-[var(--color-surface)] shadow-xl shadow-black/30">
           <div className="max-h-72 overflow-y-auto py-1">
-            {/* Headings only earn their space once there is more than one group. */}
-            {dexList.length > 0 && cexList.length > 0 && <GroupHeading>CEX</GroupHeading>}
-            {cexList.map((c) => (
+            {connectors.map((c) => (
               <ConnectorOption key={c} name={c} value={value} onSelect={onChange} onClose={() => setOpen(false)} />
             ))}
-            {dexList.length > 0 && cexList.length > 0 && <GroupHeading>DEX</GroupHeading>}
-            {dexList.map((c) => (
-              <ConnectorOption key={c} name={c} value={value} isDex onSelect={onChange} onClose={() => setOpen(false)} />
-            ))}
           </div>
         </div>
       )}
@@ -89,24 +60,14 @@ export function ExchangeSelector({
   );
 }
 
-function GroupHeading({ children }: { children: ReactNode }) {
-  return (
-    <p className="px-3 pb-0.5 pt-1.5 text-[9px] font-semibold uppercase tracking-wider text-[var(--color-text-muted)]">
-      {children}
-    </p>
-  );
-}
-
 function ConnectorOption({
   name,
   value,
-  isDex = false,
   onSelect,
   onClose,
 }: {
   name: string;
   value: string;
-  isDex?: boolean;
   onSelect: (v: string) => void;
   onClose: () => void;
 }) {
@@ -119,7 +80,7 @@ function ConnectorOption({
           : "text-[var(--color-text)] hover:bg-[var(--color-surface-hover)]"
       }`}
     >
-      {formatName(name, isDex)}
+      {formatName(name)}
     </button>
   );
 }
diff --git a/frontend/src/pages/CreateExecutor.tsx b/frontend/src/pages/CreateExecutor.tsx
index d58b41db..bf737050 100644
--- a/frontend/src/pages/CreateExecutor.tsx
+++ b/frontend/src/pages/CreateExecutor.tsx
@@ -1,5 +1,5 @@
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
-import React, { useCallback, useEffect, useMemo, useState } from "react";
+import React, { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useNavigate, useSearchParams } from "react-router-dom";
 import {
   ArrowLeft,
@@ -104,9 +104,15 @@ export function CreateExecutor() {
   const pair = gridState.pair;
   const isSpot = isSpotConnector(connector);
 
+  // The venue the URL asked for, kept after the param is stripped below: the
+  // redirect guard cannot read it from the URL any more, and it must not fire
+  // for a *persisted* gateway network (that one just resets to a CLOB venue).
+  const urlConnectorRef = useRef<string | null>(null);
+
   // Apply connector/pair from URL params (e.g. from Executors detail panel)
   useEffect(() => {
     const urlConnector = searchParams.get("connector");
+    urlConnectorRef.current = urlConnector;
     const urlPair = searchParams.get("pair");
     if (urlConnector) {
       gridDispatch({ type: "SET_CONNECTOR", value: urlConnector });
@@ -165,18 +171,15 @@ export function CreateExecutor() {
   // Order-book venues first, then swap-only ones — the grouping ExchangeSelector
   // renders, and it keeps allConnectors[0] (the reset fallback) a tradable venue
   // rather than whichever chain sorts first alphabetically.
+  // Trade is for venues with an order book — whether or not the venue is
+  // decentralized: hyperliquid and xrpl belong here, solana-mainnet-beta does
+  // not. Everything Condor trades through Gateway lives on /dex instead, where
+  // the pool rather than the pair is the unit of navigation.
   const allConnectors = useMemo(
-    () => [
-      ...venues.filter((v) => v.hummingbotMarketData).map((v) => v.name),
-      ...venues.filter((v) => !v.hummingbotMarketData).map((v) => v.name),
-    ],
+    () => venues.filter((v) => v.hummingbotMarketData).map((v) => v.name),
     [venues],
   );
 
-  const dexConnectors = useMemo(
-    () => venues.filter((v) => !v.hummingbotMarketData).map((v) => v.name),
-    [venues],
-  );
 
   const caps = useMemo(
     () => connectorCapabilities(connector, venues),
@@ -222,8 +225,22 @@ export function CreateExecutor() {
     setSelectedExecutorId(null);
   }, [connector, pair]);
 
+  // A /trade URL naming a gateway network is a link to the wrong page now: its
+  // pools, not its pairs, are the thing to pick. Send it to /dex rather than
+  // silently swapping in a CEX. Only a *known* non-CLOB venue redirects, so a
+  // typo still falls through to the reset below.
+  useEffect(() => {
+    if (!listsReady) return;
+    const wanted = urlConnectorRef.current;
+    if (wanted && venues.some((v) => v.name === wanted && !v.hummingbotMarketData)) {
+      urlConnectorRef.current = null;
+      navigate("/dex", { replace: true });
+    }
+  }, [listsReady, venues, navigate]);
+
   // Sync connector to the offered venues. A venue the server no longer reports
   // cannot stay selected, or the panel queries endpoints for a venue that is gone.
+  // A persisted solana-mainnet-beta retires itself here — no migration code.
   useEffect(() => {
     if (listsReady && allConnectors.length && !allConnectors.includes(connector)) {
       gridDispatch({ type: "SET_CONNECTOR", value: allConnectors[0] });
@@ -458,7 +475,6 @@ export function CreateExecutor() {
               connectors={allConnectors}
               value={connector}
               onChange={(v) => gridDispatch({ type: "SET_CONNECTOR", value: v })}
-              dexConnectors={dexConnectors}
             />
           </div>
         </div>

From ec93cc1857cc52905a49ccfd68faee84504f487b Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Thu, 13 Aug 2026 10:24:07 +0300
Subject: [PATCH 034/116] (feat) dex: liquidity bins over a server-scoped route
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

fetch_liquidity_bins gains an injectable client, so the web side — which
holds a server *name*, not a chat id — reaches the same fetch Telegram
uses, including the get_pool_info → get_pools fallback for pools outside
Gateway's DLMM list. With no user_data to cache in, the result is cached
process-wide at the same one-minute TTL, so every viewer of a pool shares
one Gateway call.

GET /servers/{name}/dex/pools/{address}/bins gates on can_fetch_liquidity
— the same predicate that decorates each pool row with has_bins, so the
route and the browser never disagree — and degrades to
{"available": false, "reason": ...} with a 200 for an unsupported venue,
an unreachable server or an upstream raise.
---
 condor/web/routes/dex.py               | 146 ++++++++++++
 handlers/dex/pool_data.py              |  31 ++-
 tests/test_dex_liquidity_bins_route.py | 302 +++++++++++++++++++++++++
 3 files changed, 475 insertions(+), 4 deletions(-)
 create mode 100644 tests/test_dex_liquidity_bins_route.py

diff --git a/condor/web/routes/dex.py b/condor/web/routes/dex.py
index 8ecf0615..ef7af2f7 100644
--- a/condor/web/routes/dex.py
+++ b/condor/web/routes/dex.py
@@ -124,3 +124,149 @@ async def get_pool(
     if not pool:
         raise HTTPException(status_code=404, detail="Pool not found")
     return pool
+
+
+def _no_bins(reason: str) -> dict:
+    """The unavailable state, with a 200.
+
+    A pool Condor cannot draw bins for is something to render — a one-line
+    reason where the depth column would be — not a failure the user can act on.
+    Upstream failures degrade the same way, for the same reason.
+    """
+    return {
+        "bins": [],
+        "active_price": None,
+        "bin_step": None,
+        "available": False,
+        "reason": reason,
+    }
+
+
+def _as_float(value) -> float | None:
+    try:
+        number = float(value)
+    except (TypeError, ValueError):
+        return None
+    return number if number == number else None  # NaN is not a price
+
+
+@router.get("/servers/{name}/dex/pools/{pool_address}/bins")
+async def get_pool_bins(
+    name: str,
+    pool_address: str,
+    network: str = Query(default="solana-mainnet-beta"),
+    connector: str = Query(
+        default="meteora",
+        description="The pool's Gateway CLMM connector, or the GeckoTerminal "
+        "dex_id it is derived from (meteora-dlmm → meteora).",
+    ),
+    user: WebUser = Depends(get_current_user),
+):
+    """The pool's liquidity bins, for the depth column beside its chart.
+
+    ``can_fetch_liquidity`` is the gate and is asked first — it is the same
+    predicate that decorates every pool row with ``has_bins``, so the workspace
+    already knows whether to call. It answers a *different* question from
+    ``lp_provider_for_dex``: a pool can be LP-able without Condor being able to
+    draw its bins, and the two must not be read as proxies for each other.
+
+    The ``get_pool_info`` → ``get_pools`` fallback for pools outside Gateway's
+    DLMM list stays where it already is, in ``fetch_liquidity_bins``; this
+    handler injects a client and shapes the answer.
+    """
+    cm = get_config_manager()
+    if not cm.has_server_access(user.id, name):
+        raise HTTPException(status_code=403, detail="No access")
+
+    if not _POOL_ADDRESS_RE.match(pool_address):
+        raise HTTPException(status_code=400, detail="Invalid pool_address")
+
+    from handlers.dex.pool_data import (
+        can_fetch_liquidity,
+        fetch_liquidity_bins,
+        get_connector_for_dex,
+    )
+
+    # Gated on the *dex id* as given, which is exactly what decorates each pool
+    # row with ``has_bins`` — so the route and the browser never disagree about
+    # which pools have a depth column. A Raydium AMM v4 pool is refused here for
+    # the same reason it is refused there: only ``raydium`` (CLMM) is in the set.
+    named = (connector or "").strip().lower()
+    if not named or not can_fetch_liquidity(named, network):
+        return _no_bins(
+            f"Condor reads liquidity bins from Gateway CLMM, which does not cover "
+            f"{named or 'this venue'} on {network}."
+        )
+    # The Gateway connector the gated dex id names (``meteora`` → ``meteora``).
+    resolved = get_connector_for_dex(named) or named
+
+    try:
+        client = await cm.get_client(name)
+    except Exception as e:
+        logger.warning("Gateway client unavailable for %s: %s", name, e)
+        client = None
+    if client is None:
+        return _no_bins("The API server is not reachable, so bins cannot be read.")
+
+    try:
+        bins, pool_info, error = await fetch_liquidity_bins(
+            pool_address=pool_address,
+            connector=resolved,
+            network=network,
+            client=client,
+        )
+    except Exception as e:  # fetch_liquidity_bins already swallows its own
+        logger.warning("Liquidity bins failed for %s: %s", pool_address[:12], e)
+        return _no_bins("Liquidity bins could not be read from Gateway.")
+
+    if error or not bins:
+        return _no_bins(error or "Gateway reports no liquidity bins for this pool.")
+
+    pool_info = pool_info or {}
+    base_usd = _as_float(pool_info.get("base_token_price_usd"))
+    quote_usd = _as_float(pool_info.get("quote_token_price_usd"))
+
+    rows = []
+    for raw in bins:
+        if not isinstance(raw, dict):
+            continue
+        price = _as_float(raw.get("price"))
+        if price is None:
+            continue
+        base_amount = _as_float(raw.get("base_token_amount")) or 0.0
+        quote_amount = _as_float(raw.get("quote_token_amount")) or 0.0
+        # Only when both sides can be priced: a half-priced bin would size its
+        # bar against a different unit than its neighbours.
+        liquidity_usd = (
+            base_amount * base_usd + quote_amount * quote_usd
+            if base_usd is not None and quote_usd is not None
+            else None
+        )
+        rows.append(
+            {
+                "price": price,
+                "base_amount": base_amount,
+                "quote_amount": quote_amount,
+                "liquidity_usd": liquidity_usd,
+            }
+        )
+
+    if not rows:
+        return _no_bins("Gateway reports no liquidity bins for this pool.")
+
+    active_price = _as_float(pool_info.get("price"))
+    if active_price is None:
+        active_price = _as_float(pool_info.get("current_price"))
+    bin_step = pool_info.get("bin_step")
+    try:
+        bin_step = int(bin_step) if bin_step is not None else None
+    except (TypeError, ValueError):
+        bin_step = None
+
+    return {
+        "bins": rows,
+        "active_price": active_price,
+        "bin_step": bin_step,
+        "available": True,
+        "reason": None,
+    }
diff --git a/handlers/dex/pool_data.py b/handlers/dex/pool_data.py
index 851924b1..3cb9f3fe 100644
--- a/handlers/dex/pool_data.py
+++ b/handlers/dex/pool_data.py
@@ -722,6 +722,14 @@ async def fetch_ohlcv(
         return None, f"Failed to fetch OHLCV: {str(e)}"
 
 
+# Bins for one pool, keyed ``(connector, pool_address)``. Used when no caller
+# supplies a ``user_data`` to cache in — i.e. by the web dashboard, where every
+# viewer of a pool would otherwise open its own Gateway call at the same cadence.
+# Same one-minute TTL as the per-chat cache: bins move with every swap through
+# the active bin, so a longer one would draw liquidity that has already left.
+_pool_bins_cache: Dict[Tuple[str, str], Tuple[float, Dict[str, Any]]] = {}
+
+
 async def fetch_liquidity_bins(
     pool_address: str,
     connector: str = "meteora",
@@ -729,6 +737,7 @@ async def fetch_liquidity_bins(
     user_data: dict = None,
     chat_id: int = None,
     context=None,
+    client=None,
 ) -> Tuple[Optional[List], Optional[Dict], Optional[str]]:
     """Fetch liquidity bin data for CLMM pools via gateway
 
@@ -736,8 +745,13 @@ async def fetch_liquidity_bins(
         pool_address: Pool contract address
         connector: DEX connector (meteora, raydium, orca)
         network: Network identifier
-        user_data: Optional user_data dict for caching
+        user_data: Optional user_data dict for caching. When omitted the result
+            is cached process-wide instead, so callers with no conversation of
+            their own (the web dashboard) still share one Gateway call per pool.
         chat_id: Chat ID for per-chat server selection
+        client: An already-resolved API client. The web side holds a server
+            *name* and resolves its client through the config manager, which the
+            ``get_client(chat_id)`` path below cannot express.
 
     Returns:
         Tuple of (bins_list, pool_info, error_message)
@@ -753,10 +767,15 @@ async def fetch_liquidity_bins(
         cache_key = f"pool_bins_{connector}_{pool_address}"
         if user_data is not None:
             cached = get_cached(user_data, cache_key, ttl=BINS_CACHE_TTL)
-            if cached is not None:
-                return cached.get("bins"), cached, None
+        else:
+            cached = _ttl_get(
+                _pool_bins_cache, (connector, pool_address), BINS_CACHE_TTL
+            )
+        if cached is not None:
+            return cached.get("bins"), cached, None
 
-        client = await get_client(chat_id, context=context)
+        if client is None:
+            client = await get_client(chat_id, context=context)
         if not client:
             return None, None, "Gateway client not available"
 
@@ -819,6 +838,10 @@ async def fetch_liquidity_bins(
         # Cache result
         if user_data is not None:
             set_cached(user_data, cache_key, pool_info)
+        else:
+            _ttl_put(
+                _pool_bins_cache, (connector, pool_address), pool_info, BINS_CACHE_TTL
+            )
 
         return bins, pool_info, None
 
diff --git a/tests/test_dex_liquidity_bins_route.py b/tests/test_dex_liquidity_bins_route.py
new file mode 100644
index 00000000..4935db6c
--- /dev/null
+++ b/tests/test_dex_liquidity_bins_route.py
@@ -0,0 +1,302 @@
+"""Liquidity bins for the depth column beside a pool's chart (FEAT-045).
+
+Two things are pinned here. First, that ``fetch_liquidity_bins`` can be handed a
+client — the web side holds a server *name*, not a chat id, and the
+``get_pool_info`` → ``get_pools`` fallback for pools outside Gateway's DLMM list
+must keep working through that door. Second, that the route degrades: an
+unsupported venue, an unreachable server and an upstream raise are all states the
+workspace renders, never a 502 the user cannot act on.
+"""
+
+import asyncio
+
+import pytest
+from fastapi import FastAPI
+from starlette.testclient import TestClient
+
+import condor.web.routes.dex as dex_routes
+from condor.web.auth import get_current_user
+from condor.web.models import WebUser
+from handlers.dex import pool_data
+
+POOL = "8sLbNZoA1cfnvMJLPfp98ZLAnFSYCFApfJKMbiXNLwxj"
+USER = WebUser(id=111, username="u", first_name="U", role="user")
+
+
+def run(coro):
+    return asyncio.run(coro)
+
+
+@pytest.fixture(autouse=True)
+def _clear_bins_cache():
+    pool_data._pool_bins_cache.clear()
+    yield
+    pool_data._pool_bins_cache.clear()
+
+
+def bin_row(price, base=0.0, quote=0.0):
+    return {
+        "bin_id": int(price * 100),
+        "price": price,
+        "base_token_amount": base,
+        "quote_token_amount": quote,
+    }
+
+
+def pool_info(**over):
+    info = {
+        "address": POOL,
+        "price": 150.0,
+        "bin_step": 20,
+        "active_bin_id": 15000,
+        "bins": [
+            bin_row(149.0, quote=1000.0),
+            bin_row(150.0, base=2.0, quote=300.0),
+            bin_row(151.0, base=5.0),
+        ],
+    }
+    info.update(over)
+    return info
+
+
+class FakeClmm:
+    """Gateway's CLMM namespace, recording what it was asked."""
+
+    def __init__(self, info=None, error=None, pools=None):
+        self.info = info
+        self.error = error
+        self.pools = pools
+        self.calls = []
+
+    async def get_pool_info(self, connector, network, pool_address):
+        self.calls.append(("info", connector, network, pool_address))
+        if self.error:
+            raise self.error
+        return self.info
+
+    async def get_pools(self, connector, search_term=None, limit=None, page=None):
+        self.calls.append(("pools", connector, search_term))
+        return {"pools": self.pools or []}
+
+
+class FakeClient:
+    def __init__(self, clmm):
+        self.gateway_clmm = clmm
+
+
+class FakeConfigManager:
+    def __init__(self, allowed=True, client=None, client_error=None):
+        self.allowed = allowed
+        self._client = client
+        self._client_error = client_error
+
+    def has_server_access(self, user_id, name, *a, **kw):
+        return self.allowed
+
+    async def get_client(self, name):
+        if self._client_error:
+            raise self._client_error
+        return self._client
+
+
+@pytest.fixture
+def route_client(monkeypatch):
+    def build(allowed=True, client=None, client_error=None):
+        cm = FakeConfigManager(allowed, client, client_error)
+        monkeypatch.setattr(dex_routes, "get_config_manager", lambda: cm)
+        app = FastAPI()
+        app.include_router(dex_routes.router)
+        app.dependency_overrides[get_current_user] = lambda: USER
+        return TestClient(app)
+
+    return build
+
+
+def bins_url(connector="meteora", network="solana-mainnet-beta", pool=POOL):
+    return f"/servers/srv/dex/pools/{pool}/bins?network={network}&connector={connector}"
+
+
+# ── fetch_liquidity_bins takes a client ──
+
+
+def test_an_injected_client_replaces_the_telegram_accessor(monkeypatch):
+    def boom(*a, **kw):
+        raise AssertionError("get_client must not be reached when a client is given")
+
+    monkeypatch.setattr(pool_data, "get_client", boom)
+    clmm = FakeClmm(pool_info())
+    bins, info, error = run(
+        pool_data.fetch_liquidity_bins(POOL, "meteora", client=FakeClient(clmm))
+    )
+    assert error is None
+    assert len(bins) == 3
+    assert info["bin_step"] == 20
+    assert clmm.calls[0][0] == "info"
+
+
+def test_the_telegram_path_still_resolves_its_own_client(monkeypatch):
+    clmm = FakeClmm(pool_info())
+    seen = {}
+
+    async def fake_get_client(chat_id, context=None):
+        seen["chat_id"] = chat_id
+        return FakeClient(clmm)
+
+    monkeypatch.setattr(pool_data, "get_client", fake_get_client)
+    user_data = {}
+    bins, _info, error = run(
+        pool_data.fetch_liquidity_bins(POOL, "meteora", user_data=user_data, chat_id=7)
+    )
+    assert error is None and len(bins) == 3
+    assert seen["chat_id"] == 7
+    # Still cached in the caller's conversation, not in the process-wide dict.
+    assert pool_data._pool_bins_cache == {}
+    run(pool_data.fetch_liquidity_bins(POOL, "meteora", user_data=user_data, chat_id=7))
+    assert len(clmm.calls) == 1
+
+
+def test_two_clientless_viewers_share_one_gateway_call():
+    clmm = FakeClmm(pool_info())
+    client = FakeClient(clmm)
+    first = run(pool_data.fetch_liquidity_bins(POOL, "meteora", client=client))
+    second = run(pool_data.fetch_liquidity_bins(POOL, "meteora", client=client))
+    assert first[0] == second[0]
+    assert len(clmm.calls) == 1
+
+
+def test_the_get_pools_fallback_survives_the_client_parameter():
+    clmm = FakeClmm(
+        error=ValueError("1 validation error for PoolInfo: Field required"),
+        pools=[{"trading_pair": "SOL-USDC", "bins": [bin_row(150.0, base=1.0)]}],
+    )
+    bins, info, error = run(
+        pool_data.fetch_liquidity_bins(POOL, "meteora", client=FakeClient(clmm))
+    )
+    assert error is None
+    assert info["address"] == POOL
+    assert [c[0] for c in clmm.calls] == ["info", "pools"]
+    assert len(bins) == 1
+
+
+def test_an_unsupported_connector_never_reaches_gateway():
+    clmm = FakeClmm(pool_info())
+    bins, info, error = run(
+        pool_data.fetch_liquidity_bins(POOL, "sushiswap", client=FakeClient(clmm))
+    )
+    assert (bins, info) == (None, None)
+    assert "not available" in error
+    assert clmm.calls == []
+
+
+# ── the route ──
+
+
+def test_a_supported_pool_returns_normalized_bins(route_client):
+    clmm = FakeClmm(pool_info())
+    r = route_client(client=FakeClient(clmm)).get(bins_url())
+    assert r.status_code == 200
+    body = r.json()
+    assert body["available"] is True and body["reason"] is None
+    assert body["active_price"] == 150.0
+    assert body["bin_step"] == 20
+    assert body["bins"][0] == {
+        "price": 149.0,
+        "base_amount": 0.0,
+        "quote_amount": 1000.0,
+        "liquidity_usd": None,
+    }
+    assert [b["price"] for b in body["bins"]] == [149.0, 150.0, 151.0]
+
+
+def test_liquidity_usd_is_priced_only_when_both_sides_are(route_client):
+    priced = pool_info(base_token_price_usd="150.0", quote_token_price_usd="1.0")
+    r = route_client(client=FakeClient(FakeClmm(priced))).get(bins_url())
+    body = r.json()
+    assert body["bins"][1]["liquidity_usd"] == pytest.approx(2.0 * 150.0 + 300.0)
+
+    pool_data._pool_bins_cache.clear()
+    half = pool_info(base_token_price_usd="150.0")
+    r = route_client(client=FakeClient(FakeClmm(half))).get(bins_url())
+    assert all(b["liquidity_usd"] is None for b in r.json()["bins"])
+
+
+@pytest.mark.parametrize(
+    "dex_id",
+    ["meteora", "orca", "raydium", "raydium-amm-v4", "uniswap-v3-base", "sushiswap"],
+)
+def test_the_route_gate_is_the_same_answer_as_has_bins(route_client, dex_id):
+    """A row's ``has_bins`` decoration and this route must never disagree.
+
+    The browser only asks for a depth column when the pool says it has one, so
+    a route that answered a wider set would be reachable by nothing, and a
+    narrower one would draw an empty column on a pool that promised bins.
+    """
+    network = "solana-mainnet-beta"
+    expected = pool_data.can_fetch_liquidity(dex_id, network)
+    r = route_client(client=FakeClient(FakeClmm(pool_info()))).get(
+        bins_url(connector=dex_id, network=network)
+    )
+    assert r.status_code == 200
+    assert r.json()["available"] is expected
+
+
+def test_an_unsupported_dex_is_unavailable_with_a_reason(route_client):
+    clmm = FakeClmm(pool_info())
+    r = route_client(client=FakeClient(clmm)).get(bins_url(connector="raydium-amm-v4"))
+    assert r.status_code == 200
+    body = r.json()
+    assert body["available"] is False
+    assert body["bins"] == [] and body["reason"]
+    # Gate first: an unsupported venue costs no Gateway call.
+    assert clmm.calls == []
+
+
+def test_a_supported_dex_on_the_wrong_chain_is_unavailable(route_client):
+    clmm = FakeClmm(pool_info())
+    r = route_client(client=FakeClient(clmm)).get(bins_url(network="base-mainnet"))
+    assert r.status_code == 200
+    assert r.json()["available"] is False
+    assert clmm.calls == []
+
+
+def test_an_upstream_raise_does_not_502(route_client):
+    clmm = FakeClmm(error=RuntimeError("gateway is down"))
+    r = route_client(client=FakeClient(clmm)).get(bins_url())
+    assert r.status_code == 200
+    body = r.json()
+    assert body["available"] is False and body["reason"]
+
+
+def test_an_unreachable_server_is_unavailable_not_a_502(route_client):
+    r = route_client(client_error=RuntimeError("no server")).get(bins_url())
+    assert r.status_code == 200
+    assert r.json()["available"] is False
+
+
+def test_a_pool_with_no_bins_is_unavailable(route_client):
+    r = route_client(client=FakeClient(FakeClmm(pool_info(bins=[])))).get(bins_url())
+    assert r.status_code == 200
+    body = r.json()
+    assert body["available"] is False and body["bins"] == []
+
+
+def test_bins_without_a_price_are_dropped(route_client):
+    info = pool_info(bins=[bin_row(150.0, base=1.0), {"base_token_amount": 5.0}])
+    r = route_client(client=FakeClient(FakeClmm(info))).get(bins_url())
+    body = r.json()
+    assert body["available"] is True
+    assert [b["price"] for b in body["bins"]] == [150.0]
+
+
+def test_a_non_address_is_a_400(route_client):
+    clmm = FakeClmm(pool_info())
+    r = route_client(client=FakeClient(clmm)).get(bins_url(pool="not-an-address"))
+    assert r.status_code == 400
+    assert clmm.calls == []
+
+
+def test_no_server_access_is_a_403(route_client):
+    r = route_client(allowed=False, client=FakeClient(FakeClmm(pool_info()))).get(
+        bins_url()
+    )
+    assert r.status_code == 403

From 22fb45de33dec2a447634d6dbe0246b4c4db9505 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Thu, 13 Aug 2026 10:24:16 +0300
Subject: [PATCH 035/116] (feat) chart: lend the price axis to a sibling
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

TradeChart holds the lightweight-charts series and never exposed it, so
anything drawn beside the chart had to invent its own price scale — and a
scale that disagrees with the candles is the one failure a depth column
exists to prevent. A new optional onChartReady hands out three methods
(priceToCoordinate, height, onScaleChange) once the series exists; no
chart instance leaks and every other caller omits the prop.
---
 frontend/src/components/trade/TradeChart.tsx | 48 ++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/frontend/src/components/trade/TradeChart.tsx b/frontend/src/components/trade/TradeChart.tsx
index 1ee10f3d..c5395591 100644
--- a/frontend/src/components/trade/TradeChart.tsx
+++ b/frontend/src/components/trade/TradeChart.tsx
@@ -11,6 +11,24 @@ import { escapeHtml, formatCompactUsd } from "@/lib/formatters";
 
 type PickField = "start" | "end" | "limit" | null;
 
+/**
+ * The chart's price mapping, and nothing else.
+ *
+ * A sibling drawn beside the chart — the DEX liquidity-depth column — has to put
+ * a bin at the same vertical position the candles put its price, at every zoom
+ * level. Inventing a second scale is the one failure such a column exists to
+ * prevent, so the chart lends out its own mapping instead. Three methods, no
+ * chart instance: nothing outside can mutate the chart through this.
+ */
+export interface ChartPriceAxis {
+  /** Pixel row for a price, from the pane's top. `null` when it is off-scale. */
+  priceToCoordinate(price: number): number | null;
+  /** Pane height in CSS pixels, so a sibling canvas can match it. */
+  height(): number;
+  /** Subscribe to scale changes; returns its own unsubscribe. */
+  onScaleChange(cb: () => void): () => void;
+}
+
 interface TradeChartProps {
   server: string;
   connector: string;
@@ -43,6 +61,8 @@ interface TradeChartProps {
   onRequestCandleRange?: (startTime: number) => void;
   /** Callback when user clicks chart background to deselect executor */
   onExecutorDeselect?: () => void;
+  /** Called once the series exists, with the chart's price mapping. */
+  onChartReady?: (axis: ChartPriceAxis) => void;
 }
 
 export function TradeChart({
@@ -69,6 +89,7 @@ export function TradeChart({
   convertValue,
   convertPnl,
   onExecutorDeselect,
+  onChartReady,
 }: TradeChartProps) {
   const containerRef = useRef<HTMLDivElement>(null);
   const tooltipRef = useRef<HTMLDivElement>(null);
@@ -453,6 +474,33 @@ export function TradeChart({
     };
   }, []);
 
+  // ── Lend the price mapping out, once the series exists ──
+  // Read before the series is created, priceToCoordinate answers for an empty
+  // scale — plausible pixels for the wrong prices — so this waits on chartReady
+  // rather than firing from the init effect. The callback is held in a ref so a
+  // parent that passes an inline arrow does not re-hand the axis every render.
+  const onChartReadyRef = useRef(onChartReady);
+  onChartReadyRef.current = onChartReady;
+  useEffect(() => {
+    if (!chartReady) return;
+    const notify = onChartReadyRef.current;
+    if (!notify) return;
+    notify({
+      priceToCoordinate: (price) => {
+        const coord = seriesRef.current?.priceToCoordinate(price);
+        return coord == null ? null : (coord as number);
+      },
+      height: () => containerRef.current?.clientHeight ?? 0,
+      onScaleChange: (cb) => {
+        const chart = chartRef.current;
+        if (!chart) return () => {};
+        const timeScale = chart.timeScale();
+        timeScale.subscribeVisibleLogicalRangeChange(cb);
+        return () => timeScale.unsubscribeVisibleLogicalRangeChange(cb);
+      },
+    });
+  }, [chartReady]);
+
   // ── Re-apply chart colors on theme change ──
   useEffect(() => {
     if (!chartRef.current || !chartModuleRef.current) return;

From ad92bd137a575b5fb7da7b2bc9c71a12fab9e242 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Thu, 13 Aug 2026 10:24:16 +0300
Subject: [PATCH 036/116] (feat) dex: liquidity depth beside the pool chart

A CLMM pool's workspace draws its bins as a horizontal histogram on the
chart's own price axis, so a bar sits at the pixel row the candles put its
price at and an LP range is read against the liquidity already there.
Bars are coloured by side (base above the active price, quote below),
scaled to the 90th percentile of the *visible* bins so whales cannot
flatten the rest, and redrawn on scale change, resize and new data.

The column is mounted only where the pool says has_bins, polls at the
server's one-minute TTL, collapses to a strip that is remembered in
localStorage, and renders the stated reason in place of bars when the
venue has none to give.
---
 .../components/dex/LiquidityDepthColumn.tsx   | 188 ++++++++++++++++++
 frontend/src/lib/api.ts                       |  28 +++
 frontend/src/pages/DexPool.tsx                |  75 ++++++-
 3 files changed, 288 insertions(+), 3 deletions(-)
 create mode 100644 frontend/src/components/dex/LiquidityDepthColumn.tsx

diff --git a/frontend/src/components/dex/LiquidityDepthColumn.tsx b/frontend/src/components/dex/LiquidityDepthColumn.tsx
new file mode 100644
index 00000000..c562d46f
--- /dev/null
+++ b/frontend/src/components/dex/LiquidityDepthColumn.tsx
@@ -0,0 +1,188 @@
+import { useEffect, useRef } from "react";
+
+import type { ChartPriceAxis } from "@/components/trade/TradeChart";
+import { getThemeColors } from "@/lib/theme-colors";
+
+export interface DepthBin {
+  price: number;
+  base_amount: number;
+  quote_amount: number;
+  liquidity_usd: number | null;
+}
+
+interface Props {
+  bins: DepthBin[];
+  /** The pool's active price: bins above it hold base, below it hold quote. */
+  activePrice: number | null;
+  /** The candle chart's own price mapping. Null until the chart is ready. */
+  axis: ChartPriceAxis | null;
+  width?: number;
+  /** Ignore the loudest bins when scaling bars. 90 keeps the shape readable. */
+  percentile?: number;
+}
+
+/** The value at `p` percent of a sorted-ascending array, or 0 for an empty one. */
+function percentileOf(sorted: number[], p: number): number {
+  if (!sorted.length) return 0;
+  const index = Math.min(sorted.length - 1, Math.floor(((p / 100) * (sorted.length - 1)) | 0));
+  return sorted[Math.max(0, index)];
+}
+
+/**
+ * A horizontal histogram of a CLMM pool's liquidity, drawn beside the candles on
+ * the chart's own price axis.
+ *
+ * The alignment is the feature: a bar sits at the pixel row the chart puts its
+ * price at, so an LP range drawn across the candles is read against the
+ * liquidity already sitting there. That is why this reads `priceToCoordinate`
+ * from the chart instead of deriving a scale from the bins — a second scale
+ * would look informative and quietly disagree at every zoom level.
+ *
+ * `lightweight-charts` has no price-keyed horizontal histogram (its histograms
+ * are keyed by time), so this is a hand-drawn canvas that owns its own redraw.
+ */
+export function LiquidityDepthColumn({
+  bins,
+  activePrice,
+  axis,
+  width = 72,
+  percentile = 90,
+}: Props) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const canvasRef = useRef<HTMLCanvasElement>(null);
+
+  useEffect(() => {
+    const canvas = canvasRef.current;
+    const container = containerRef.current;
+    if (!canvas || !container || !axis) return;
+
+    const draw = () => {
+      const ctx = canvas.getContext("2d");
+      if (!ctx) return;
+      const dpr = window.devicePixelRatio || 1;
+      const w = container.clientWidth;
+      const h = axis.height() || container.clientHeight;
+      if (!w || !h) return;
+      if (canvas.width !== Math.round(w * dpr) || canvas.height !== Math.round(h * dpr)) {
+        canvas.width = Math.round(w * dpr);
+        canvas.height = Math.round(h * dpr);
+        canvas.style.width = `${w}px`;
+        canvas.style.height = `${h}px`;
+      }
+      ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+      ctx.clearRect(0, 0, w, h);
+
+      const rows = bins ?? [];
+      if (!rows.length) return;
+      const active = activePrice;
+
+      // Only what the chart currently shows: scaling against off-screen whale
+      // bins would flatten the visible ones to a line as soon as you zoom in.
+      const visible: { y: number; value: number; isBase: boolean }[] = [];
+      const priced = rows.every((b) => b.liquidity_usd != null);
+      for (const bin of rows) {
+        const y = axis.priceToCoordinate(bin.price);
+        if (y == null || y < 0 || y > h) continue;
+        const isBase = active != null ? bin.price >= active : bin.base_amount >= bin.quote_amount;
+        const value = priced
+          ? (bin.liquidity_usd as number)
+          : isBase
+            ? bin.base_amount
+            : bin.quote_amount;
+        if (!(value > 0)) continue;
+        visible.push({ y, value, isBase });
+      }
+      if (!visible.length) return;
+
+      // With both sides priced in USD one scale is comparable across the whole
+      // column; with raw amounts it is not — two tokens, two units — so each
+      // side is normalized against its own bins.
+      const trim = (values: number[]) =>
+        percentileOf([...values].sort((a, b) => a - b), percentile) ||
+        Math.max(...values, 0);
+      let baseScale: number;
+      let quoteScale: number;
+      if (priced) {
+        baseScale = quoteScale = trim(visible.map((v) => v.value));
+      } else {
+        const baseValues = visible.filter((v) => v.isBase).map((v) => v.value);
+        const quoteValues = visible.filter((v) => !v.isBase).map((v) => v.value);
+        baseScale = baseValues.length ? trim(baseValues) : 1;
+        quoteScale = quoteValues.length ? trim(quoteValues) : 1;
+      }
+
+      // Bin rows crowd together as you zoom out; one pixel is the floor and the
+      // typical gap is the ceiling, so bars never overlap into a solid block.
+      const ys = visible.map((v) => v.y).sort((a, b) => a - b);
+      let gap = h;
+      for (let i = 1; i < ys.length; i++) gap = Math.min(gap, ys[i] - ys[i - 1] || gap);
+      const barHeight = Math.max(1, Math.min(6, Math.floor(gap) || 1));
+
+      const colors = getThemeColors();
+      const maxBar = w - 2;
+      for (const { y, value, isBase } of visible) {
+        const scale = isBase ? baseScale : quoteScale;
+        const len = Math.max(1, Math.min(maxBar, (value / (scale || 1)) * maxBar));
+        ctx.fillStyle = isBase ? colors.up : colors.down;
+        ctx.globalAlpha = 0.55;
+        ctx.fillRect(w - len, y - barHeight / 2, len, barHeight);
+      }
+      ctx.globalAlpha = 1;
+
+      // The active price, so the two sides are readable as sides.
+      if (active != null) {
+        const y = axis.priceToCoordinate(active);
+        if (y != null && y >= 0 && y <= h) {
+          ctx.strokeStyle = colors.text;
+          ctx.globalAlpha = 0.6;
+          ctx.beginPath();
+          ctx.moveTo(0, Math.round(y) + 0.5);
+          ctx.lineTo(w, Math.round(y) + 0.5);
+          ctx.stroke();
+          ctx.globalAlpha = 1;
+        }
+      }
+    };
+
+    draw();
+
+    const unsubscribe = axis.onScaleChange(draw);
+    const observer = new ResizeObserver(draw);
+    observer.observe(container);
+
+    // The scale-change subscription covers pan and zoom, but not a drag of the
+    // price axis or an autoscale after new candles — and a bar at a
+    // plausible-but-wrong price is worse than no bar. So the mapping itself is
+    // probed each frame (two calls, no drawing) and a redraw only follows a
+    // mapping that actually moved.
+    let frame = 0;
+    let lastProbe = "";
+    const probePrice = bins[Math.floor(bins.length / 2)]?.price;
+    const tick = () => {
+      frame = requestAnimationFrame(tick);
+      if (probePrice == null) return;
+      const probe = `${axis.priceToCoordinate(probePrice)}:${axis.height()}`;
+      if (probe === lastProbe) return;
+      lastProbe = probe;
+      draw();
+    };
+    frame = requestAnimationFrame(tick);
+
+    return () => {
+      unsubscribe();
+      observer.disconnect();
+      cancelAnimationFrame(frame);
+    };
+  }, [axis, bins, activePrice, percentile]);
+
+  return (
+    <div
+      ref={containerRef}
+      style={{ width }}
+      className="relative shrink-0 overflow-hidden border-l border-[var(--color-border)]"
+      title="Liquidity by price — base above the active price, quote below"
+    >
+      <canvas ref={canvasRef} className="absolute left-0 top-0" />
+    </div>
+  );
+}
diff --git a/frontend/src/lib/api.ts b/frontend/src/lib/api.ts
index dc8f3696..5039278f 100644
--- a/frontend/src/lib/api.ts
+++ b/frontend/src/lib/api.ts
@@ -316,6 +316,24 @@ export interface PoolSummary {
   pool_created_at?: string | null;
 }
 
+/** One CLMM bin: the liquidity sitting at one price step of a pool. */
+export interface LiquidityBin {
+  price: number;
+  base_amount: number;
+  quote_amount: number;
+  /** Null when the pool's token prices are unknown; size bars by amount then. */
+  liquidity_usd: number | null;
+}
+
+export interface PoolBins {
+  bins: LiquidityBin[];
+  active_price: number | null;
+  bin_step: number | null;
+  /** False is a state to render (with `reason`), never an error to surface. */
+  available: boolean;
+  reason: string | null;
+}
+
 export interface PoolQuery {
   source: "gecko" | "gateway";
   /** source=gecko: the chain, as a Gateway network id or a gecko chain id. */
@@ -1327,6 +1345,16 @@ export const api = {
       `/api/v1/servers/${encodeURIComponent(server)}/dex/pools/${encodeURIComponent(address)}?network=${encodeURIComponent(network)}`,
     ),
 
+  /**
+   * A pool's liquidity bins, for the depth column beside its chart. Answers
+   * `available: false` with a reason rather than failing: a venue Condor cannot
+   * read bins from is something to say, not an error to raise.
+   */
+  getPoolBins: (server: string, address: string, network: string, connector: string) =>
+    apiFetch<PoolBins>(
+      `/api/v1/servers/${encodeURIComponent(server)}/dex/pools/${encodeURIComponent(address)}/bins?network=${encodeURIComponent(network)}&connector=${encodeURIComponent(connector)}`,
+    ),
+
   getPrice: (server: string, connector: string, pair: string) =>
     apiFetch<MarketPrice>(
       `/api/v1/servers/${encodeURIComponent(server)}/market/prices?connector=${encodeURIComponent(connector)}&trading_pair=${encodeURIComponent(pair)}`,
diff --git a/frontend/src/pages/DexPool.tsx b/frontend/src/pages/DexPool.tsx
index 8e826265..f8d2a4c7 100644
--- a/frontend/src/pages/DexPool.tsx
+++ b/frontend/src/pages/DexPool.tsx
@@ -1,9 +1,10 @@
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
-import { ArrowLeft, CheckCircle, Copy, X } from "lucide-react";
+import { ArrowLeft, CheckCircle, ChevronLeft, ChevronRight, Copy, X } from "lucide-react";
 import { useEffect, useMemo, useState } from "react";
 import { useNavigate, useParams } from "react-router-dom";
 
 import { NoServerCard } from "@/components/NoServerCard";
+import { LiquidityDepthColumn } from "@/components/dex/LiquidityDepthColumn";
 import { PoolStats } from "@/components/dex/PoolStats";
 import {
   LPConfigPanel,
@@ -14,7 +15,7 @@ import {
   useOrderConfig,
 } from "@/components/executor/OrderConfigPanel";
 import { TradeBottomPane } from "@/components/trade/TradeBottomPane";
-import { TradeChart } from "@/components/trade/TradeChart";
+import { TradeChart, type ChartPriceAxis } from "@/components/trade/TradeChart";
 import { useMainControllerData } from "@/hooks/useMainControllerData";
 import { useResizeDrag } from "@/hooks/useResizeDrag";
 import { useServer } from "@/hooks/useServer";
@@ -24,6 +25,8 @@ import { INTERVALS, LOOKBACK_OPTIONS } from "@/lib/gridExecutor";
 
 type Tab = "order" | "lp";
 
+const DEPTH_KEY = "condor.dex.depth-collapsed";
+
 /**
  * One pool, and everything you can do in it.
  *
@@ -46,6 +49,23 @@ export function DexPool() {
   const [bottomPaneHeight, setBottomPaneHeight] = useState(200);
   const [selectedExecutorId, setSelectedExecutorId] = useState<string | null>(null);
   const [successId, setSuccessId] = useState<string | null>(null);
+  // The chart lends out its price mapping; the depth column draws on it.
+  const [priceAxis, setPriceAxis] = useState<ChartPriceAxis | null>(null);
+  const [depthCollapsed, setDepthCollapsed] = useState(() => {
+    try {
+      return localStorage.getItem(DEPTH_KEY) === "1";
+    } catch {
+      return false;
+    }
+  });
+
+  useEffect(() => {
+    try {
+      localStorage.setItem(DEPTH_KEY, depthCollapsed ? "1" : "0");
+    } catch {
+      /* private mode; the column just forgets */
+    }
+  }, [depthCollapsed]);
 
   const { onMouseDown: startHDrag } = useResizeDrag({
     axis: "x",
@@ -84,6 +104,18 @@ export function DexPool() {
     staleTime: 5 * 60 * 1000,
   });
 
+  // Bins move with every swap through the active bin, so the server caches them
+  // for a minute and this polls at the same cadence — every viewer of the pool
+  // shares that one Gateway call. Asked only when the pool says it has bins:
+  // `has_bins` is decided by the same predicate the route gates on.
+  const { data: depth } = useQuery({
+    queryKey: ["dex-pool-bins", server, network, address, pool?.dex_id],
+    queryFn: () => api.getPoolBins(server!, address, network, pool?.dex_id ?? ""),
+    enabled: !!server && !!address && !!pool?.has_bins,
+    staleTime: 60 * 1000,
+    refetchInterval: 60 * 1000,
+  });
+
   // The same function Trade feeds; it is handed a gateway network here instead
   // of a CLOB venue, and answers ["order"] (+ "lp" when the venue does CLMM).
   const caps = useMemo(
@@ -232,7 +264,8 @@ export function DexPool() {
 
       <div className="flex min-h-0 flex-1">
         <div className="flex min-w-0 flex-1 flex-col">
-          <div className="min-h-0 flex-1 overflow-hidden">
+          <div className="flex min-h-0 flex-1">
+            <div className="min-h-0 min-w-0 flex-1 overflow-hidden">
             <TradeChart
               key={`${network}:${pool.address}:${interval}`}
               server={server}
@@ -254,7 +287,43 @@ export function DexPool() {
               positions={positions}
               selectedExecutorId={selectedExecutorId}
               onExecutorDeselect={() => setSelectedExecutorId(null)}
+              onChartReady={setPriceAxis}
             />
+            </div>
+
+            {/* Liquidity depth, on the chart's own price axis. Only where there
+                are bins to read: a plain AMM pool has none to draw. */}
+            {pool.has_bins &&
+              (depthCollapsed ? (
+                <button
+                  onClick={() => setDepthCollapsed(false)}
+                  title="Show liquidity depth"
+                  className="flex w-5 shrink-0 items-center justify-center border-l border-[var(--color-border)] text-[var(--color-text-muted)] hover:bg-[var(--color-surface-hover)] hover:text-[var(--color-text)]"
+                >
+                  <ChevronLeft className="h-3.5 w-3.5" />
+                </button>
+              ) : (
+                <div className="relative flex shrink-0">
+                  {depth && !depth.available ? (
+                    <p className="w-[120px] shrink-0 border-l border-[var(--color-border)] px-2 py-2 text-[10px] leading-relaxed text-[var(--color-text-muted)]">
+                      {depth.reason ?? "No liquidity bins for this pool."}
+                    </p>
+                  ) : (
+                    <LiquidityDepthColumn
+                      bins={depth?.bins ?? []}
+                      activePrice={depth?.active_price ?? pool.current_price ?? null}
+                      axis={priceAxis}
+                    />
+                  )}
+                  <button
+                    onClick={() => setDepthCollapsed(true)}
+                    title="Hide liquidity depth"
+                    className="absolute right-0 top-0 z-10 rounded-bl bg-[var(--color-bg)]/80 p-0.5 text-[var(--color-text-muted)] hover:text-[var(--color-text)]"
+                  >
+                    <ChevronRight className="h-3 w-3" />
+                  </button>
+                </div>
+              ))}
           </div>
 
           <div

From 07beac44db8219182472f2381408c58353673e9e Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Thu, 13 Aug 2026 10:24:51 +0300
Subject: [PATCH 037/116] (feat) dex: draw the configured range across the
 depth column
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The point of sharing the chart's price axis is that the range you are
about to take is read against the liquidity already there — so the band
is drawn on the column too, from the same priceToCoordinate the bars use.
It cannot drift from them.
---
 .../components/dex/LiquidityDepthColumn.tsx   | 30 ++++++++++++++++++-
 frontend/src/pages/DexPool.tsx                |  2 ++
 2 files changed, 31 insertions(+), 1 deletion(-)

diff --git a/frontend/src/components/dex/LiquidityDepthColumn.tsx b/frontend/src/components/dex/LiquidityDepthColumn.tsx
index c562d46f..4ec201c9 100644
--- a/frontend/src/components/dex/LiquidityDepthColumn.tsx
+++ b/frontend/src/components/dex/LiquidityDepthColumn.tsx
@@ -16,6 +16,9 @@ interface Props {
   activePrice: number | null;
   /** The candle chart's own price mapping. Null until the chart is ready. */
   axis: ChartPriceAxis | null;
+  /** The range being configured in the panel, drawn across the bars. */
+  rangeStart?: number | null;
+  rangeEnd?: number | null;
   width?: number;
   /** Ignore the loudest bins when scaling bars. 90 keeps the shape readable. */
   percentile?: number;
@@ -45,6 +48,8 @@ export function LiquidityDepthColumn({
   bins,
   activePrice,
   axis,
+  rangeStart,
+  rangeEnd,
   width = 72,
   percentile = 90,
 }: Props) {
@@ -129,6 +134,29 @@ export function LiquidityDepthColumn({
       }
       ctx.globalAlpha = 1;
 
+      // The range being configured, so "am I inside the liquidity" is answered
+      // by looking. It shares the bars' axis, so it cannot drift from them.
+      if (rangeStart != null && rangeEnd != null && rangeStart > 0 && rangeEnd > 0) {
+        const y1 = axis.priceToCoordinate(Math.min(rangeStart, rangeEnd));
+        const y2 = axis.priceToCoordinate(Math.max(rangeStart, rangeEnd));
+        if (y1 != null && y2 != null) {
+          const top = Math.min(y1, y2);
+          const box = Math.abs(y1 - y2);
+          ctx.fillStyle = colors.yellow;
+          ctx.globalAlpha = 0.12;
+          ctx.fillRect(0, top, w, box);
+          ctx.strokeStyle = colors.yellow;
+          ctx.globalAlpha = 0.7;
+          ctx.beginPath();
+          ctx.moveTo(0, Math.round(top) + 0.5);
+          ctx.lineTo(w, Math.round(top) + 0.5);
+          ctx.moveTo(0, Math.round(top + box) + 0.5);
+          ctx.lineTo(w, Math.round(top + box) + 0.5);
+          ctx.stroke();
+          ctx.globalAlpha = 1;
+        }
+      }
+
       // The active price, so the two sides are readable as sides.
       if (active != null) {
         const y = axis.priceToCoordinate(active);
@@ -173,7 +201,7 @@ export function LiquidityDepthColumn({
       observer.disconnect();
       cancelAnimationFrame(frame);
     };
-  }, [axis, bins, activePrice, percentile]);
+  }, [axis, bins, activePrice, rangeStart, rangeEnd, percentile]);
 
   return (
     <div
diff --git a/frontend/src/pages/DexPool.tsx b/frontend/src/pages/DexPool.tsx
index f8d2a4c7..202594a0 100644
--- a/frontend/src/pages/DexPool.tsx
+++ b/frontend/src/pages/DexPool.tsx
@@ -313,6 +313,8 @@ export function DexPool() {
                       bins={depth?.bins ?? []}
                       activePrice={depth?.active_price ?? pool.current_price ?? null}
                       axis={priceAxis}
+                      rangeStart={active.chartProps.startPrice}
+                      rangeEnd={active.chartProps.endPrice}
                     />
                   )}
                   <button

From 0fd2cf9271f94eae5046c219d0cdb50bdcd5a752 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Thu, 13 Aug 2026 15:43:29 +0300
Subject: [PATCH 038/116] (feat) add support verification

---
 .../skills/verify_connector_support/SKILL.md  | 22 +++++++++++++++++++
 1 file changed, 22 insertions(+)
 create mode 100644 agents/condor/skills/verify_connector_support/SKILL.md

diff --git a/agents/condor/skills/verify_connector_support/SKILL.md b/agents/condor/skills/verify_connector_support/SKILL.md
new file mode 100644
index 00000000..db593d36
--- /dev/null
+++ b/agents/condor/skills/verify_connector_support/SKILL.md
@@ -0,0 +1,22 @@
+---
+name: verify_connector_support
+description: Check what a connector actually supports before answering capability
+  questions
+when_to_use: User asks "can I use connector X?" or "does Y support Z?" — any capability
+  question about a connector or DEX
+created: '2026-08-12T11:51:59Z'
+source: chat
+---
+
+## Verify Connector Support
+
+Never guess connector capabilities from memory. Always pull the authoritative source first.
+
+### Steps
+
+1. **LP / CLMM questions** → `manage_executors(executor_type="lp_executor")` — read the "Supported DEXs" section
+2. **AMM swap/pool-creation questions** → `manage_amm()` (no action) — read the connector list
+3. **Pool discovery questions** → `explore_dex_pools` tool description lists supported connectors
+4. **Market data / candle questions** → `get_market_data` guide or the `candles_without_a_candle_feed` skill
+
+Then answer from what the guide actually says — not from what you remember.

From f9f1cc4c0fe0c80217111cc4dd80c37502c69ac3 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Thu, 13 Aug 2026 15:43:41 +0300
Subject: [PATCH 039/116] (feat) default gateway to development

---
 condor/web/models.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/condor/web/models.py b/condor/web/models.py
index 7b69dd53..757a51a2 100644
--- a/condor/web/models.py
+++ b/condor/web/models.py
@@ -496,7 +496,7 @@ class UpdateServerRequest(BaseModel):
 class GatewayStartRequest(BaseModel):
     # The Hummingbot API always runs the Gateway secured (TLS + mTLS) and manages the
     # certificates/passphrase itself (hummingbot-api SEC-048), so only image/port are sent.
-    image: str = "hummingbot/gateway:latest"
+    image: str = "hummingbot/gateway:development"
     port: int = 15888
 
 
@@ -506,7 +506,7 @@ class CredentialInfo(BaseModel):
 
 
 class GatewayPullRequest(BaseModel):
-    image: str = "hummingbot/gateway:latest"
+    image: str = "hummingbot/gateway:development"
 
 
 class GatewayNetworkUpdateRequest(BaseModel):

From 65cca406e8209c15a3df1668bcf0d0f8b4a28f3e Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Thu, 13 Aug 2026 15:43:55 +0300
Subject: [PATCH 040/116] (feat) default gateway to development

---
 frontend/src/components/settings/GatewaySettings.tsx |  2 +-
 handlers/config/gateway/deployment.py                | 10 +++++-----
 mcp_servers/hummingbot_api/schemas.py                |  4 ++--
 3 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/frontend/src/components/settings/GatewaySettings.tsx b/frontend/src/components/settings/GatewaySettings.tsx
index 555f037c..5accf8a8 100644
--- a/frontend/src/components/settings/GatewaySettings.tsx
+++ b/frontend/src/components/settings/GatewaySettings.tsx
@@ -16,8 +16,8 @@ import { useServer } from "@/hooks/useServer";
 import { api } from "@/lib/api";
 
 const IMAGE_OPTIONS = [
-  { label: "Latest", value: "hummingbot/gateway:latest" },
   { label: "Development", value: "hummingbot/gateway:development" },
+  { label: "Latest", value: "hummingbot/gateway:latest" },
 ];
 
 function formatRelativeTime(dateStr: string): string {
diff --git a/handlers/config/gateway/deployment.py b/handlers/config/gateway/deployment.py
index b2f5733a..cc26d1ca 100644
--- a/handlers/config/gateway/deployment.py
+++ b/handlers/config/gateway/deployment.py
@@ -30,20 +30,20 @@ async def start_deploy_gateway(query, context: ContextTypes.DEFAULT_TYPE) -> Non
             message_text = (
                 header + "*Select Docker Image:*\n\n"
                 "Choose which Gateway image to deploy\\.\n"
-                "The latest stable version is recommended\\."
+                "The development version is recommended\\."
             )
 
             keyboard = [
                 [
                     InlineKeyboardButton(
-                        "hummingbot/gateway:latest (recommended)",
-                        callback_data="gateway_deploy_image_latest",
+                        "hummingbot/gateway:development (recommended)",
+                        callback_data="gateway_deploy_image_development",
                     )
                 ],
                 [
                     InlineKeyboardButton(
-                        "hummingbot/gateway:development",
-                        callback_data="gateway_deploy_image_development",
+                        "hummingbot/gateway:latest",
+                        callback_data="gateway_deploy_image_latest",
                     )
                 ],
                 [
diff --git a/mcp_servers/hummingbot_api/schemas.py b/mcp_servers/hummingbot_api/schemas.py
index 917dddba..15b35df9 100644
--- a/mcp_servers/hummingbot_api/schemas.py
+++ b/mcp_servers/hummingbot_api/schemas.py
@@ -220,11 +220,11 @@ class GatewayContainerRequest(BaseModel):
         "The Hummingbot API runs Gateway secured (TLS + mTLS) and manages the "
         "certificates/passphrase itself using its own CONFIG_PASSWORD (hummingbot-api "
         "SEC-048), so no passphrase is needed here. "
-        "Fields: image (Docker image, default: hummingbot/gateway:latest), "
+        "Fields: image (Docker image, default: hummingbot/gateway:development), "
         "port (exposed port, default: 15888).",
         examples=[
             {
-                "image": "hummingbot/gateway:latest",
+                "image": "hummingbot/gateway:development",
                 "port": 15888,
             }
         ],

From c287423ca24e861b8c085390f6243bb943538f9c Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Thu, 13 Aug 2026 15:44:00 +0300
Subject: [PATCH 041/116] (feat) fix oneway

---
 mcp_servers/hummingbot_api/server.py        |  2 +-
 mcp_servers/hummingbot_api/tools/trading.py | 11 +++++++----
 2 files changed, 8 insertions(+), 5 deletions(-)

diff --git a/mcp_servers/hummingbot_api/server.py b/mcp_servers/hummingbot_api/server.py
index 3c71eea7..d55c97de 100644
--- a/mcp_servers/hummingbot_api/server.py
+++ b/mcp_servers/hummingbot_api/server.py
@@ -239,7 +239,7 @@ async def set_account_position_mode_and_leverage(
         account_name: Account name (default: master_account)
         connector_name: Exchange connector name (e.g., 'binance_perpetual')
         trading_pair: Trading pair (e.g., ETH-USD) only required for setting leverage
-        position_mode: Position mode ('HEDGE' or 'ONE-WAY')
+        position_mode: Position mode ('HEDGE' or 'ONEWAY')
         leverage: Leverage to set (optional, required for HEDGE mode)
     """
     client = await hummingbot_client.get_client()
diff --git a/mcp_servers/hummingbot_api/tools/trading.py b/mcp_servers/hummingbot_api/tools/trading.py
index 11b9a279..6f0ee6c9 100644
--- a/mcp_servers/hummingbot_api/tools/trading.py
+++ b/mcp_servers/hummingbot_api/tools/trading.py
@@ -7,6 +7,7 @@
 For order placement and cancellation, use `manage_executors` with `order_executor` type.
 """
 
+import re
 from typing import Any, Literal
 
 from mcp_servers.hummingbot_api.formatters import (
@@ -31,7 +32,7 @@ async def set_position_mode_and_leverage(
         account_name: Account name
         connector_name: Exchange connector name
         trading_pair: Trading pair (required for leverage)
-        position_mode: Position mode ('HEDGE' or 'ONE-WAY')
+        position_mode: Position mode ('HEDGE' or 'ONEWAY')
         leverage: Leverage to set
 
     Returns:
@@ -47,9 +48,11 @@ async def set_position_mode_and_leverage(
 
     # Set position mode
     if position_mode:
-        position_mode = position_mode.upper()
-        if position_mode not in ["HEDGE", "ONE-WAY"]:
-            raise ValueError("Invalid position mode. Must be 'HEDGE' or 'ONE-WAY'")
+        # The API expects the plain enum member name ("ONEWAY"/"HEDGE"). Accept the
+        # hyphen/underscore/space spellings callers often use and normalize them.
+        position_mode = re.sub(r"[-_\s]", "", position_mode.upper())
+        if position_mode not in ["HEDGE", "ONEWAY"]:
+            raise ValueError("Invalid position mode. Must be 'HEDGE' or 'ONEWAY'")
 
         position_mode_result = await client.trading.set_position_mode(
             account_name=account_name,

From 3f71750746f951ff7ed213a93be7a6387ea4f814 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Thu, 13 Aug 2026 18:01:02 +0300
Subject: [PATCH 042/116] (feat) improve frontend

---
 condor/web/routes/dex.py                      |  91 +++-
 frontend/src/components/dex/PoolBrowser.tsx   | 407 +++++++++++-------
 .../src/components/dex/PoolSourceTabs.tsx     | 299 ++++++++++---
 frontend/src/lib/api.ts                       |  49 ++-
 frontend/src/pages/Dex.tsx                    | 186 ++++++--
 handlers/dex/pool_data.py                     | 375 ++++++++++++++--
 tests/test_dex_pool_discovery.py              | 385 ++++++++++++++++-
 7 files changed, 1466 insertions(+), 326 deletions(-)

diff --git a/condor/web/routes/dex.py b/condor/web/routes/dex.py
index ef7af2f7..2358741e 100644
--- a/condor/web/routes/dex.py
+++ b/condor/web/routes/dex.py
@@ -55,7 +55,13 @@ async def list_pools(
         description="source=gecko+view=token: the token address. "
         "source=gateway: free text matched against pool names.",
     ),
+    dexes: str | None = Query(
+        default=None,
+        description="source=gecko: comma-separated GeckoTerminal dex ids to keep "
+        "(meteora,orca,raydium-clmm). Empty means every venue.",
+    ),
     limit: int = Query(default=20, ge=1, le=100),
+    page: int = Query(default=1, ge=1, description="1-based page of `limit` rows"),
     user: WebUser = Depends(get_current_user),
 ):
     """Pools to browse, from one of the two upstreams.
@@ -68,12 +74,15 @@ async def list_pools(
     An upstream failure answers ``{"pools": []}`` with a warning, like
     ``/market/venues``: the browser's empty state is something the user can act on,
     a 502 is not.
+
+    ``has_more`` — not a total — is what the browser's Next needs, and a total is
+    something neither upstream reports.
     """
     cm = get_config_manager()
     if not cm.has_server_access(user.id, name):
         raise HTTPException(status_code=403, detail="No access")
 
-    from handlers.dex.pool_data import list_gateway_pools, list_gecko_pools
+    from handlers.dex.pool_data import list_gateway_pools, list_gecko_pools_page
 
     source = (source or "gecko").strip().lower()
 
@@ -82,9 +91,17 @@ async def list_pools(
             client = await cm.get_client(name)
         except Exception as e:
             logger.warning("Gateway pools unavailable for %s: %s", name, e)
-            return {"pools": [], "source": source}
-        pools = await list_gateway_pools(client, connector, search=query, limit=limit)
-        return {"pools": pools, "source": source}
+            return {"pools": [], "source": source, "page": page, "has_more": False}
+        pools = await list_gateway_pools(
+            client, connector, search=query, limit=limit, page=page
+        )
+        # Gateway reports no total, so a full page is the only evidence of another.
+        return {
+            "pools": pools,
+            "source": source,
+            "page": page,
+            "has_more": len(pools) >= limit,
+        }
 
     if source != "gecko":
         raise HTTPException(status_code=400, detail="Unknown source")
@@ -95,8 +112,70 @@ async def list_pools(
     if view == "token" and not _ADDRESS_RE.match(token):
         raise HTTPException(status_code=400, detail="Invalid token address")
 
-    pools = await list_gecko_pools(network, view=view, token=token, limit=limit)
-    return {"pools": pools, "source": source}
+    result = await list_gecko_pools_page(
+        network,
+        view=view,
+        token=token,
+        limit=limit,
+        page=page,
+        dexes=[d for d in (dexes or "").split(",") if d.strip()],
+    )
+    return {
+        "pools": result["pools"],
+        "source": source,
+        "page": page,
+        "has_more": result["has_more"],
+    }
+
+
+@router.get("/servers/{name}/dex/dexes")
+async def list_dexes(
+    name: str,
+    network: str = Query(default="solana-mainnet-beta"),
+    user: WebUser = Depends(get_current_user),
+):
+    """The venues on a chain, for the pool browser's dex filter.
+
+    Offered by the chain rather than hardcoded, so a venue GeckoTerminal starts
+    indexing is filterable without a deploy. Empty when the lookup fails — a filter
+    with no options is one the browser simply does not show.
+    """
+    cm = get_config_manager()
+    if not cm.has_server_access(user.id, name):
+        raise HTTPException(status_code=403, detail="No access")
+
+    from handlers.dex.pool_data import list_gecko_dexes
+
+    return {"dexes": await list_gecko_dexes(network)}
+
+
+@router.get("/servers/{name}/dex/pools-by-address")
+async def list_pools_by_address(
+    name: str,
+    addresses: str = Query(description="Comma-separated pool addresses (max 30)"),
+    network: str = Query(default="solana-mainnet-beta"),
+    user: WebUser = Depends(get_current_user),
+):
+    """Several pools by address at once, for the favourites view.
+
+    A favourite is stored as an address, not as a copy of the row, so its TVL and
+    volume have to be re-read like any other row rather than replayed from
+    whenever it was starred. An address that no longer resolves is absent from the
+    answer instead of failing the whole view — a de-indexed pool is not an error.
+
+    Declared above ``/dex/pools/{pool_address}`` deliberately: a path segment would
+    otherwise be read as an address.
+    """
+    cm = get_config_manager()
+    if not cm.has_server_access(user.id, name):
+        raise HTTPException(status_code=403, detail="No access")
+
+    from handlers.dex.pool_data import fetch_pools_by_addresses
+
+    wanted = [a.strip() for a in (addresses or "").split(",") if a.strip()][:30]
+    if not wanted:
+        return {"pools": []}
+    return {"pools": await fetch_pools_by_addresses(network, wanted)}
 
 
 @router.get("/servers/{name}/dex/pools/{pool_address}")
diff --git a/frontend/src/components/dex/PoolBrowser.tsx b/frontend/src/components/dex/PoolBrowser.tsx
index 2465a613..3c70ff0f 100644
--- a/frontend/src/components/dex/PoolBrowser.tsx
+++ b/frontend/src/components/dex/PoolBrowser.tsx
@@ -1,8 +1,15 @@
-import { ChevronDown, ChevronUp } from "lucide-react";
+import {
+  ChevronDown,
+  ChevronLeft,
+  ChevronRight,
+  ChevronUp,
+  Star,
+} from "lucide-react";
 import { useMemo, useState } from "react";
 import { useNavigate } from "react-router-dom";
 
 import type { PoolSummary } from "@/lib/api";
+import { useDexFavorites } from "@/lib/dexFavorites";
 
 type SortKey =
   | "name"
@@ -10,12 +17,20 @@ type SortKey =
   | "reserve_usd"
   | "volume_24h"
   | "price_change_24h"
-  | "apr";
+  | "apr"
+  | "apy";
 type SortDir = "asc" | "desc";
 
-function num(v: unknown): number {
-  const n = typeof v === "string" ? parseFloat(v) : (v as number);
-  return Number.isFinite(n) ? n : 0;
+/**
+ * Both upstreams answer numbers as strings (and GeckoTerminal answers pandas NaN
+ * for a missing figure). The backend settles that before it serializes, so this
+ * is the second line of defence rather than the first — but it is the one that
+ * decides whether a stray string blanks one cell or takes down the whole page.
+ */
+function num(v: unknown): number | null {
+  if (v === null || v === undefined || v === "") return null;
+  const n = typeof v === "number" ? v : parseFloat(String(v));
+  return Number.isFinite(n) ? n : null;
 }
 
 function usd(v: unknown): string {
@@ -27,8 +42,16 @@ function usd(v: unknown): string {
   return `$${n.toFixed(2)}`;
 }
 
-function pct(v: number | null | undefined): string {
-  return v === null || v === undefined ? "—" : `${v.toFixed(2)}%`;
+function pct(v: unknown): string {
+  const n = num(v);
+  if (n === null) return "—";
+  if (Math.abs(n) >= 10_000) return `${(n / 1000).toFixed(0)}K%`;
+  return `${n.toFixed(2)}%`;
+}
+
+/** Sorting compares numbers, and a missing figure sorts last in either direction. */
+function sortValue(p: PoolSummary, key: SortKey): number {
+  return num(p[key as keyof PoolSummary]) ?? -Infinity;
 }
 
 function pairLabel(p: PoolSummary): string {
@@ -45,6 +68,7 @@ function SortTh({
   sortDir,
   onSort,
   align = "left",
+  title,
 }: {
   label: string;
   col: SortKey;
@@ -52,11 +76,13 @@ function SortTh({
   sortDir: SortDir;
   onSort: (k: SortKey) => void;
   align?: "left" | "right";
+  title?: string;
 }) {
   const active = sortKey === col;
   return (
     <th
       onClick={() => onSort(col)}
+      title={title}
       className={`cursor-pointer select-none px-4 py-3 text-xs font-medium uppercase tracking-wider text-[var(--color-text-muted)] transition-colors hover:text-[var(--color-text)] ${
         align === "right" ? "text-right" : "text-left"
       }`}
@@ -81,22 +107,35 @@ interface Props {
   isLoading: boolean;
   /** Shown in place of rows when there are none — the empty state, not an error. */
   emptyMessage: string;
-  /** True when Gateway supplied the rows, so APR and bin step have values. */
+  /** True when Gateway supplied the rows, so fee/APY and bin step have values. */
   showGatewayColumns: boolean;
+  /** The chain the rows belong to, for starring a row by (network, address). */
+  network: string;
+  page: number;
+  hasMore: boolean;
+  onPageChange: (page: number) => void;
 }
 
 /**
  * The pool table. A pool Gateway cannot reach is rendered greyed with the reason
  * rather than hidden: a chain GeckoTerminal indexes but Condor does not trade on
  * is a fact worth seeing, not a row to silently drop.
+ *
+ * Sorting is page-local, because paging is the upstream's: what the columns
+ * reorder is the screenful in front of you, not the whole listing.
  */
 export function PoolBrowser({
   pools,
   isLoading,
   emptyMessage,
   showGatewayColumns,
+  network,
+  page,
+  hasMore,
+  onPageChange,
 }: Props) {
   const navigate = useNavigate();
+  const { toggle, isFavorite } = useDexFavorites();
   const [sortKey, setSortKey] = useState<SortKey>("reserve_usd");
   const [sortDir, setSortDir] = useState<SortDir>("desc");
 
@@ -114,12 +153,39 @@ export function PoolBrowser({
       let cmp: number;
       if (sortKey === "name") cmp = pairLabel(a).localeCompare(pairLabel(b));
       else if (sortKey === "dex_id") cmp = a.dex_id.localeCompare(b.dex_id);
-      else cmp = num(a[sortKey]) - num(b[sortKey]);
+      else cmp = sortValue(a, sortKey) - sortValue(b, sortKey);
       return sortDir === "asc" ? cmp : -cmp;
     });
     return rows;
   }, [pools, sortKey, sortDir]);
 
+  // Only when there is somewhere to go: a lone disabled "Page 1" is noise, and
+  // the favourites view has no pages at all.
+  const pager =
+    !hasMore && page <= 1 ? null : (
+      <div className="flex items-center justify-between border-t border-[var(--color-border)] px-4 py-2 text-xs text-[var(--color-text-muted)]">
+        <span>Page {page}</span>
+        <div className="flex items-center gap-1">
+          <button
+            onClick={() => onPageChange(page - 1)}
+            disabled={page <= 1}
+            className="flex items-center gap-1 rounded-md border border-[var(--color-border)] px-2 py-1 transition-colors hover:bg-[var(--color-surface-hover)] disabled:cursor-not-allowed disabled:opacity-40"
+          >
+            <ChevronLeft className="h-3 w-3" />
+            Prev
+          </button>
+          <button
+            onClick={() => onPageChange(page + 1)}
+            disabled={!hasMore}
+            className="flex items-center gap-1 rounded-md border border-[var(--color-border)] px-2 py-1 transition-colors hover:bg-[var(--color-surface-hover)] disabled:cursor-not-allowed disabled:opacity-40"
+          >
+            Next
+            <ChevronRight className="h-3 w-3" />
+          </button>
+        </div>
+      </div>
+    );
+
   if (isLoading) {
     return (
       <div className="px-4 py-10 text-center text-sm text-[var(--color-text-muted)]">
@@ -130,150 +196,197 @@ export function PoolBrowser({
 
   if (!sorted.length) {
     return (
-      <div className="px-4 py-10 text-center text-sm text-[var(--color-text-muted)]">
-        {emptyMessage}
-      </div>
+      <>
+        <div className="px-4 py-10 text-center text-sm text-[var(--color-text-muted)]">
+          {emptyMessage}
+        </div>
+        {page > 1 && pager}
+      </>
     );
   }
 
   return (
-    <div className="overflow-x-auto">
-      <table className="w-full text-sm">
-        <thead>
-          <tr className="border-b border-[var(--color-border)] bg-[var(--color-surface)]">
-            <SortTh
-              label="Pair"
-              col="name"
-              sortKey={sortKey}
-              sortDir={sortDir}
-              onSort={handleSort}
-            />
-            <SortTh
-              label="DEX"
-              col="dex_id"
-              sortKey={sortKey}
-              sortDir={sortDir}
-              onSort={handleSort}
-            />
-            <SortTh
-              label="TVL"
-              col="reserve_usd"
-              sortKey={sortKey}
-              sortDir={sortDir}
-              onSort={handleSort}
-              align="right"
-            />
-            <SortTh
-              label="Vol 24h"
-              col="volume_24h"
-              sortKey={sortKey}
-              sortDir={sortDir}
-              onSort={handleSort}
-              align="right"
-            />
-            <SortTh
-              label="24h"
-              col="price_change_24h"
-              sortKey={sortKey}
-              sortDir={sortDir}
-              onSort={handleSort}
-              align="right"
-            />
-            {showGatewayColumns && (
-              <>
-                <SortTh
-                  label="APR"
-                  col="apr"
-                  sortKey={sortKey}
-                  sortDir={sortDir}
-                  onSort={handleSort}
-                  align="right"
-                />
-                <th className="px-4 py-3 text-right text-xs font-medium uppercase tracking-wider text-[var(--color-text-muted)]">
-                  Bin
-                </th>
-              </>
-            )}
-            <th className="px-4 py-3 text-right text-xs font-medium uppercase tracking-wider text-[var(--color-text-muted)]">
-              LP
-            </th>
-          </tr>
-        </thead>
-        <tbody>
-          {sorted.map((p) => {
-            const change = p.price_change_24h;
-            return (
-              <tr
-                key={`${p.dex_id}:${p.address}`}
-                onClick={() =>
-                  p.tradable &&
-                  navigate(`/dex/${p.gateway_network}/${p.address}`)
-                }
-                title={
-                  p.tradable
-                    ? undefined
-                    : "Gateway has no connector for this chain"
-                }
-                className={`border-b border-[var(--color-border)] transition-colors ${
-                  p.tradable
-                    ? "cursor-pointer hover:bg-[var(--color-surface-hover)]"
-                    : "opacity-40"
-                }`}
-              >
-                <td className="px-4 py-2.5 font-medium">
-                  {pairLabel(p)}
-                  {!p.tradable && (
-                    <span className="ml-2 text-[10px] font-normal text-[var(--color-text-muted)]">
-                      not on Gateway
-                    </span>
-                  )}
-                </td>
-                <td className="px-4 py-2.5 text-[var(--color-text-muted)]">
-                  {p.dex_id}
-                </td>
-                <td className="px-4 py-2.5 text-right tabular-nums">
-                  {usd(p.reserve_usd)}
-                </td>
-                <td className="px-4 py-2.5 text-right tabular-nums">
-                  {usd(p.volume_24h)}
-                </td>
-                <td
-                  className={`px-4 py-2.5 text-right tabular-nums ${
-                    change === null || change === undefined
-                      ? "text-[var(--color-text-muted)]"
-                      : change >= 0
-                        ? "text-[var(--color-green)]"
-                        : "text-[var(--color-red)]"
+    <>
+      <div className="overflow-x-auto">
+        <table className="w-full text-sm">
+          <thead>
+            <tr className="border-b border-[var(--color-border)] bg-[var(--color-surface)]">
+              <th className="w-8 px-2 py-3" />
+              <SortTh
+                label="Pair"
+                col="name"
+                sortKey={sortKey}
+                sortDir={sortDir}
+                onSort={handleSort}
+              />
+              <SortTh
+                label="DEX"
+                col="dex_id"
+                sortKey={sortKey}
+                sortDir={sortDir}
+                onSort={handleSort}
+              />
+              <SortTh
+                label="TVL"
+                col="reserve_usd"
+                sortKey={sortKey}
+                sortDir={sortDir}
+                onSort={handleSort}
+                align="right"
+              />
+              <SortTh
+                label="Vol 24h"
+                col="volume_24h"
+                sortKey={sortKey}
+                sortDir={sortDir}
+                onSort={handleSort}
+                align="right"
+              />
+              <SortTh
+                label="24h"
+                col="price_change_24h"
+                sortKey={sortKey}
+                sortDir={sortDir}
+                onSort={handleSort}
+                align="right"
+              />
+              {showGatewayColumns && (
+                <>
+                  {/* Meteora's `apr` is the day's fees over TVL, not an annual
+                      rate — labelling it APR next to a 170% APY reads as broken. */}
+                  <SortTh
+                    label="Fee/TVL"
+                    col="apr"
+                    sortKey={sortKey}
+                    sortDir={sortDir}
+                    onSort={handleSort}
+                    align="right"
+                    title="Last 24h of fees over TVL, as the connector reports it"
+                  />
+                  <SortTh
+                    label="APY"
+                    col="apy"
+                    sortKey={sortKey}
+                    sortDir={sortDir}
+                    onSort={handleSort}
+                    align="right"
+                    title="The connector's annualized yield"
+                  />
+                  <th className="px-4 py-3 text-right text-xs font-medium uppercase tracking-wider text-[var(--color-text-muted)]">
+                    Bin
+                  </th>
+                </>
+              )}
+              <th className="px-4 py-3 text-right text-xs font-medium uppercase tracking-wider text-[var(--color-text-muted)]">
+                LP
+              </th>
+            </tr>
+          </thead>
+          <tbody>
+            {sorted.map((p) => {
+              const change = num(p.price_change_24h);
+              // A row from Gateway carries `solana`, not the Gateway network id.
+              const poolNetwork = p.gateway_network || network;
+              const starred = isFavorite({
+                network: poolNetwork,
+                address: p.address,
+              });
+              return (
+                <tr
+                  key={`${p.dex_id}:${p.address}`}
+                  onClick={() =>
+                    p.tradable && navigate(`/dex/${poolNetwork}/${p.address}`)
+                  }
+                  title={
+                    p.tradable
+                      ? undefined
+                      : "Gateway has no connector for this chain"
+                  }
+                  className={`border-b border-[var(--color-border)] transition-colors ${
+                    p.tradable
+                      ? "cursor-pointer hover:bg-[var(--color-surface-hover)]"
+                      : "opacity-40"
                   }`}
                 >
-                  {pct(change)}
-                </td>
-                {showGatewayColumns && (
-                  <>
-                    <td className="px-4 py-2.5 text-right tabular-nums">
-                      {pct(p.apr)}
-                    </td>
-                    <td className="px-4 py-2.5 text-right tabular-nums text-[var(--color-text-muted)]">
-                      {p.bin_step ?? "—"}
-                    </td>
-                  </>
-                )}
-                <td className="px-4 py-2.5 text-right">
-                  {p.lp_supported ? (
-                    <span className="rounded border border-[var(--color-primary)] px-1.5 py-0.5 text-[10px] font-medium text-[var(--color-primary)]">
-                      LP
-                    </span>
-                  ) : (
-                    <span className="text-[10px] text-[var(--color-text-muted)]">
-                      swap only
-                    </span>
+                  <td className="px-2 py-2.5">
+                    <button
+                      onClick={(e) => {
+                        e.stopPropagation();
+                        toggle({ network: poolNetwork, address: p.address });
+                      }}
+                      title={
+                        starred ? "Remove from favorites" : "Add to favorites"
+                      }
+                      className="flex items-center justify-center p-1 text-[var(--color-text-muted)] transition-colors hover:text-[var(--color-primary)]"
+                    >
+                      <Star
+                        className={`h-3.5 w-3.5 ${
+                          starred
+                            ? "fill-[var(--color-primary)] text-[var(--color-primary)]"
+                            : ""
+                        }`}
+                      />
+                    </button>
+                  </td>
+                  <td className="px-4 py-2.5 font-medium">
+                    {pairLabel(p)}
+                    {!p.tradable && (
+                      <span className="ml-2 text-[10px] font-normal text-[var(--color-text-muted)]">
+                        not on Gateway
+                      </span>
+                    )}
+                  </td>
+                  <td className="px-4 py-2.5 text-[var(--color-text-muted)]">
+                    {p.dex_id}
+                  </td>
+                  <td className="px-4 py-2.5 text-right tabular-nums">
+                    {usd(p.reserve_usd)}
+                  </td>
+                  <td className="px-4 py-2.5 text-right tabular-nums">
+                    {usd(p.volume_24h)}
+                  </td>
+                  <td
+                    className={`px-4 py-2.5 text-right tabular-nums ${
+                      change === null
+                        ? "text-[var(--color-text-muted)]"
+                        : change >= 0
+                          ? "text-[var(--color-green)]"
+                          : "text-[var(--color-red)]"
+                    }`}
+                  >
+                    {pct(p.price_change_24h)}
+                  </td>
+                  {showGatewayColumns && (
+                    <>
+                      <td className="px-4 py-2.5 text-right tabular-nums">
+                        {pct(p.apr)}
+                      </td>
+                      <td className="px-4 py-2.5 text-right tabular-nums">
+                        {pct(p.apy)}
+                      </td>
+                      <td className="px-4 py-2.5 text-right tabular-nums text-[var(--color-text-muted)]">
+                        {p.bin_step ?? "—"}
+                      </td>
+                    </>
                   )}
-                </td>
-              </tr>
-            );
-          })}
-        </tbody>
-      </table>
-    </div>
+                  <td className="px-4 py-2.5 text-right">
+                    {p.lp_supported ? (
+                      <span className="rounded border border-[var(--color-primary)] px-1.5 py-0.5 text-[10px] font-medium text-[var(--color-primary)]">
+                        LP
+                      </span>
+                    ) : (
+                      <span className="text-[10px] text-[var(--color-text-muted)]">
+                        swap only
+                      </span>
+                    )}
+                  </td>
+                </tr>
+              );
+            })}
+          </tbody>
+        </table>
+      </div>
+      {pager}
+    </>
   );
 }
diff --git a/frontend/src/components/dex/PoolSourceTabs.tsx b/frontend/src/components/dex/PoolSourceTabs.tsx
index 53e7e97e..956bc09e 100644
--- a/frontend/src/components/dex/PoolSourceTabs.tsx
+++ b/frontend/src/components/dex/PoolSourceTabs.tsx
@@ -1,20 +1,24 @@
-import { Search } from "lucide-react";
+import { Check, ChevronDown, Search, Star, X } from "lucide-react";
+import { useEffect, useMemo, useRef, useState } from "react";
+
+import type { DexVenue } from "@/lib/api";
 
 /**
- * Which pool listing to browse. The two upstreams take genuinely different
- * arguments — GeckoTerminal ranks a *chain*'s pools and searches by token
- * address, Gateway CLMM lists one *connector*'s pools and searches free text —
- * so they are separate tabs rather than one filter row with modes.
+ * Which pool listing to browse. The upstreams take genuinely different arguments
+ * — GeckoTerminal ranks a *chain*'s pools and searches by address, Gateway CLMM
+ * lists one *connector*'s pools and searches free text, favourites are a local
+ * list of addresses — so they are separate tabs rather than one filter row.
  */
 export type PoolSource =
   | { kind: "gecko"; view: "trending" | "top" | "new" | "token" }
-  | { kind: "gateway"; connector: string };
+  | { kind: "gateway"; connector: string }
+  | { kind: "favorites" };
 
 export const GECKO_TABS = [
   { view: "trending", label: "Trending" },
   { view: "top", label: "Top" },
   { view: "new", label: "New" },
-  { view: "token", label: "Token" },
+  { view: "token", label: "Search" },
 ] as const;
 
 /** The CLMM connectors Gateway can list pools for (and open positions in). */
@@ -27,94 +31,243 @@ export function sameSource(a: PoolSource, b: PoolSource): boolean {
   if (a.kind === "gecko" && b.kind === "gecko") return a.view === b.view;
   if (a.kind === "gateway" && b.kind === "gateway")
     return a.connector === b.connector;
-  return false;
+  return a.kind === "favorites" && b.kind === "favorites";
 }
 
 const TAB_BASE =
-  "px-3 py-1.5 text-xs font-medium transition-colors border-b-2 -mb-px";
+  "px-3 py-1.5 text-xs font-medium transition-colors border-b-2 -mb-px whitespace-nowrap";
+
+function tabClass(active: boolean) {
+  return `${TAB_BASE} ${
+    active
+      ? "border-[var(--color-primary)] text-[var(--color-text)]"
+      : "border-transparent text-[var(--color-text-muted)] hover:text-[var(--color-text)]"
+  }`;
+}
+
+/**
+ * The venue filter: "top pools, but only on these DEXes".
+ *
+ * Multi-select rather than a single choice because the question it answers is
+ * "which of these venues do I trade", which is rarely one — and its options come
+ * from the chain, so a venue GeckoTerminal starts indexing appears on its own.
+ */
+function DexFilter({
+  venues,
+  selected,
+  onChange,
+}: {
+  venues: DexVenue[];
+  selected: string[];
+  onChange: (next: string[]) => void;
+}) {
+  const [open, setOpen] = useState(false);
+  const [filter, setFilter] = useState("");
+  const ref = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    const handler = (e: MouseEvent) => {
+      if (ref.current && !ref.current.contains(e.target as Node))
+        setOpen(false);
+    };
+    const keyHandler = (e: KeyboardEvent) => {
+      if (e.key === "Escape") setOpen(false);
+    };
+    document.addEventListener("mousedown", handler);
+    document.addEventListener("keydown", keyHandler);
+    return () => {
+      document.removeEventListener("mousedown", handler);
+      document.removeEventListener("keydown", keyHandler);
+    };
+  }, []);
+
+  const shown = useMemo(() => {
+    const needle = filter.trim().toLowerCase();
+    const matches = needle
+      ? venues.filter(
+          (v) =>
+            v.name.toLowerCase().includes(needle) ||
+            v.id.toLowerCase().includes(needle),
+        )
+      : venues;
+    // Selected venues stay visible even when the search would hide them —
+    // otherwise unticking the last match means retyping to find it again.
+    const picked = venues.filter(
+      (v) => selected.includes(v.id) && !matches.includes(v),
+    );
+    return [...picked, ...matches];
+  }, [venues, filter, selected]);
+
+  if (!venues.length) return null;
+
+  const label =
+    selected.length === 0
+      ? "All DEXes"
+      : selected.length === 1
+        ? (venues.find((v) => v.id === selected[0])?.name ?? selected[0])
+        : `${selected.length} DEXes`;
+
+  return (
+    <div ref={ref} className="relative">
+      <button
+        onClick={() => setOpen(!open)}
+        aria-expanded={open}
+        className={`flex items-center gap-1.5 rounded-md border px-2 py-1 text-xs transition-colors ${
+          selected.length
+            ? "border-[var(--color-primary)] text-[var(--color-primary)]"
+            : "border-[var(--color-border)] text-[var(--color-text)] hover:bg-[var(--color-surface-hover)]"
+        }`}
+      >
+        {label}
+        {selected.length > 0 ? (
+          <X
+            className="h-3 w-3"
+            onClick={(e) => {
+              e.stopPropagation();
+              onChange([]);
+            }}
+          />
+        ) : (
+          <ChevronDown
+            className={`h-3 w-3 transition-transform ${open ? "rotate-180" : ""}`}
+          />
+        )}
+      </button>
+
+      {open && (
+        <div className="absolute right-0 top-full z-50 mt-1.5 w-56 rounded-lg border border-[var(--color-border)] bg-[var(--color-surface)] py-1 shadow-xl">
+          <div className="px-2 pb-1">
+            <input
+              value={filter}
+              onChange={(e) => setFilter(e.target.value)}
+              placeholder="Filter venues…"
+              autoFocus
+              spellCheck={false}
+              className="w-full rounded-md border border-[var(--color-border)] bg-[var(--color-bg)] px-2 py-1 text-xs text-[var(--color-text)] placeholder:text-[var(--color-text-muted)]"
+            />
+          </div>
+          <div className="max-h-64 overflow-y-auto">
+            {shown.map((v) => {
+              const active = selected.includes(v.id);
+              return (
+                <button
+                  key={v.id}
+                  onClick={() =>
+                    onChange(
+                      active
+                        ? selected.filter((id) => id !== v.id)
+                        : [...selected, v.id],
+                    )
+                  }
+                  className="flex w-full items-center gap-2 px-3 py-1.5 text-left text-xs transition-colors hover:bg-[var(--color-surface-hover)]"
+                >
+                  <span
+                    className={`flex h-3.5 w-3.5 shrink-0 items-center justify-center rounded border ${
+                      active
+                        ? "border-[var(--color-primary)] bg-[var(--color-primary)] text-white"
+                        : "border-[var(--color-border)]"
+                    }`}
+                  >
+                    {active && <Check className="h-2.5 w-2.5" />}
+                  </span>
+                  <span className="truncate">{v.name}</span>
+                </button>
+              );
+            })}
+            {!shown.length && (
+              <div className="px-3 py-2 text-xs text-[var(--color-text-muted)]">
+                No venue matches.
+              </div>
+            )}
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
 
 interface Props {
   source: PoolSource;
   onSourceChange: (s: PoolSource) => void;
-  /** Gateway networks from `venues` — never a hardcoded chain list. */
-  networks: string[];
-  network: string;
-  onNetworkChange: (n: string) => void;
+  /** The venues on this chain, for the filter. Empty hides it. */
+  venues: DexVenue[];
+  selectedDexes: string[];
+  onDexesChange: (next: string[]) => void;
   query: string;
   onQueryChange: (q: string) => void;
+  favoriteCount: number;
 }
 
 export function PoolSourceTabs({
   source,
   onSourceChange,
-  networks,
-  network,
-  onNetworkChange,
+  venues,
+  selectedDexes,
+  onDexesChange,
   query,
   onQueryChange,
+  favoriteCount,
 }: Props) {
+  const isSearch = source.kind === "gecko" && source.view === "token";
   const searchLabel =
     source.kind === "gateway"
       ? "Filter pools by name…"
-      : "Token address (mint or 0x…)";
-  const searchShown = source.kind === "gateway" || source.view === "token";
+      : "Paste a pool or token address…";
+  const searchShown = source.kind === "gateway" || isSearch;
 
   return (
     <div className="flex flex-wrap items-center gap-x-4 gap-y-2 border-b border-[var(--color-border)] px-4">
-      <div className="flex items-center">
-        {GECKO_TABS.map((t) => {
-          const active = sameSource(source, { kind: "gecko", view: t.view });
-          return (
-            <button
-              key={t.view}
-              onClick={() => onSourceChange({ kind: "gecko", view: t.view })}
-              className={`${TAB_BASE} ${
-                active
-                  ? "border-[var(--color-primary)] text-[var(--color-text)]"
-                  : "border-transparent text-[var(--color-text-muted)] hover:text-[var(--color-text)]"
-              }`}
-            >
-              {t.label}
-            </button>
-          );
-        })}
+      <div className="flex items-center overflow-x-auto">
+        {GECKO_TABS.map((t) => (
+          <button
+            key={t.view}
+            onClick={() => onSourceChange({ kind: "gecko", view: t.view })}
+            className={tabClass(
+              sameSource(source, { kind: "gecko", view: t.view }),
+            )}
+          >
+            {t.label}
+          </button>
+        ))}
         <span className="mx-2 h-4 w-px bg-[var(--color-border)]" />
-        {GATEWAY_TABS.map((t) => {
-          const active = sameSource(source, {
-            kind: "gateway",
-            connector: t.connector,
-          });
-          return (
-            <button
-              key={t.connector}
-              onClick={() =>
-                onSourceChange({ kind: "gateway", connector: t.connector })
-              }
-              className={`${TAB_BASE} ${
-                active
-                  ? "border-[var(--color-primary)] text-[var(--color-text)]"
-                  : "border-transparent text-[var(--color-text-muted)] hover:text-[var(--color-text)]"
-              }`}
-            >
-              {t.label}
-            </button>
-          );
-        })}
+        {GATEWAY_TABS.map((t) => (
+          <button
+            key={t.connector}
+            onClick={() =>
+              onSourceChange({ kind: "gateway", connector: t.connector })
+            }
+            className={tabClass(
+              sameSource(source, { kind: "gateway", connector: t.connector }),
+            )}
+          >
+            {t.label}
+          </button>
+        ))}
+        <span className="mx-2 h-4 w-px bg-[var(--color-border)]" />
+        <button
+          onClick={() => onSourceChange({ kind: "favorites" })}
+          className={`${tabClass(source.kind === "favorites")} flex items-center gap-1`}
+          title="Pools you starred"
+        >
+          <Star
+            className={`h-3 w-3 ${source.kind === "favorites" ? "fill-[var(--color-primary)] text-[var(--color-primary)]" : ""}`}
+          />
+          Favorites
+          {favoriteCount > 0 && (
+            <span className="text-[10px] text-[var(--color-text-muted)]">
+              {favoriteCount}
+            </span>
+          )}
+        </button>
       </div>
 
       <div className="ml-auto flex items-center gap-2 py-1.5">
-        {source.kind === "gecko" && networks.length > 0 && (
-          <select
-            value={network}
-            onChange={(e) => onNetworkChange(e.target.value)}
-            className="rounded-md border border-[var(--color-border)] bg-[var(--color-bg)] px-2 py-1 text-xs text-[var(--color-text)]"
-          >
-            {networks.map((n) => (
-              <option key={n} value={n}>
-                {n}
-              </option>
-            ))}
-          </select>
+        {source.kind === "gecko" && (
+          <DexFilter
+            venues={venues}
+            selected={selectedDexes}
+            onChange={onDexesChange}
+          />
         )}
         {searchShown && (
           <div className="relative">
@@ -124,8 +277,16 @@ export function PoolSourceTabs({
               onChange={(e) => onQueryChange(e.target.value)}
               placeholder={searchLabel}
               spellCheck={false}
-              className="w-64 rounded-md border border-[var(--color-border)] bg-[var(--color-bg)] py-1 pl-7 pr-2 text-xs text-[var(--color-text)] placeholder:text-[var(--color-text-muted)]"
+              className="w-64 rounded-md border border-[var(--color-border)] bg-[var(--color-bg)] py-1 pl-7 pr-6 text-xs text-[var(--color-text)] placeholder:text-[var(--color-text-muted)]"
             />
+            {query && (
+              <button
+                onClick={() => onQueryChange("")}
+                className="absolute right-1.5 top-1/2 -translate-y-1/2 text-[var(--color-text-muted)] hover:text-[var(--color-text)]"
+              >
+                <X className="h-3 w-3" />
+              </button>
+            )}
           </div>
         )}
       </div>
diff --git a/frontend/src/lib/api.ts b/frontend/src/lib/api.ts
index 5039278f..3201d8cf 100644
--- a/frontend/src/lib/api.ts
+++ b/frontend/src/lib/api.ts
@@ -303,14 +303,15 @@ export interface PoolSummary {
   /** False when GeckoTerminal indexes this chain but Gateway does not reach it. */
   tradable: boolean;
   has_bins: boolean;
-  reserve_usd: string | number | null;
+  reserve_usd: number | null;
   volume_24h: number | null;
   price_change_24h: number | null;
   current_price?: number | null;
-  base_token_price_usd?: string | number | null;
-  quote_token_price_usd?: string | number | null;
-  /** Gateway CLMM only. */
+  base_token_price_usd?: number | null;
+  quote_token_price_usd?: number | null;
+  /** Gateway CLMM only: Meteora reports `apr` as 24h fee/TVL, `apy` annualized. */
   apr?: number | null;
+  apy?: number | null;
   bin_step?: number | null;
   base_fee_percentage?: number | null;
   pool_created_at?: string | null;
@@ -344,7 +345,23 @@ export interface PoolQuery {
   connector?: string;
   /** source=gecko+view=token: a token address. source=gateway: free text. */
   query?: string;
+  /** source=gecko: GeckoTerminal dex ids to keep. Empty means every venue. */
+  dexes?: string[];
   limit?: number;
+  /** 1-based. Both upstreams page; neither reports a total. */
+  page?: number;
+}
+
+/** A page of pools. `has_more`, not a count — no upstream reports a total. */
+export interface PoolPage {
+  pools: PoolSummary[];
+  has_more: boolean;
+}
+
+/** One venue GeckoTerminal indexes on a chain, for the browser's dex filter. */
+export interface DexVenue {
+  id: string;
+  name: string;
 }
 
 export interface DexPoolInfo {
@@ -1327,18 +1344,36 @@ export const api = {
     ),
 
   /** Pools to browse, from GeckoTerminal (by chain) or Gateway CLMM (by connector). */
-  getDexPools: (server: string, q: PoolQuery) => {
+  getDexPools: (server: string, q: PoolQuery): Promise<PoolPage> => {
     const params = new URLSearchParams({ source: q.source });
     if (q.network) params.set("network", q.network);
     if (q.view) params.set("view", q.view);
     if (q.connector) params.set("connector", q.connector);
     if (q.query) params.set("query", q.query);
+    if (q.dexes?.length) params.set("dexes", q.dexes.join(","));
     params.set("limit", String(q.limit ?? 20));
-    return apiFetch<{ pools: PoolSummary[]; source: string }>(
+    params.set("page", String(q.page ?? 1));
+    return apiFetch<{ pools: PoolSummary[]; has_more?: boolean }>(
       `/api/v1/servers/${encodeURIComponent(server)}/dex/pools?${params}`,
-    ).then((r) => r.pools ?? []);
+    ).then((r) => ({ pools: r.pools ?? [], has_more: !!r.has_more }));
   },
 
+  /** The venues a chain has, so the dex filter offers what exists, not a guess. */
+  getDexVenues: (server: string, network: string) =>
+    apiFetch<{ dexes: DexVenue[] }>(
+      `/api/v1/servers/${encodeURIComponent(server)}/dex/dexes?network=${encodeURIComponent(network)}`,
+    ).then((r) => r.dexes ?? []),
+
+  /**
+   * Several pools by address, for the favourites view. A favourite is a saved
+   * address, so its TVL and volume are re-read rather than replayed from
+   * whenever it was starred.
+   */
+  getDexPoolsByAddress: (server: string, network: string, addresses: string[]) =>
+    apiFetch<{ pools: PoolSummary[] }>(
+      `/api/v1/servers/${encodeURIComponent(server)}/dex/pools-by-address?network=${encodeURIComponent(network)}&addresses=${encodeURIComponent(addresses.join(","))}`,
+    ).then((r) => r.pools ?? []),
+
   /** One pool by address, so /dex/{network}/{address} renders from the URL alone. */
   getDexPoolByAddress: (server: string, address: string, network: string) =>
     apiFetch<PoolSummary>(
diff --git a/frontend/src/pages/Dex.tsx b/frontend/src/pages/Dex.tsx
index c4117448..9aff0cea 100644
--- a/frontend/src/pages/Dex.tsx
+++ b/frontend/src/pages/Dex.tsx
@@ -1,5 +1,7 @@
 import { useQuery } from "@tanstack/react-query";
+import { ArrowRight } from "lucide-react";
 import { useEffect, useMemo, useState } from "react";
+import { useNavigate } from "react-router-dom";
 
 import { NoServerCard } from "@/components/NoServerCard";
 import { PoolBrowser } from "@/components/dex/PoolBrowser";
@@ -8,11 +10,27 @@ import {
   PoolSourceTabs,
 } from "@/components/dex/PoolSourceTabs";
 import { useServer } from "@/hooks/useServer";
-import { api } from "@/lib/api";
+import { api, type PoolSummary } from "@/lib/api";
+import { useDexFavorites } from "@/lib/dexFavorites";
 
 /** GeckoTerminal rate-limits per IP across every viewer and every polling chart. */
 const POOL_STALE_MS = 30_000;
 const SEARCH_DEBOUNCE_MS = 400;
+const PAGE_SIZE = 20;
+
+/**
+ * The one chain the browser offers, deliberately.
+ *
+ * Every other Gateway network is reachable by URL (`/dex/{network}/{address}`
+ * still renders), but the venues Condor can actually LP in — Meteora, Orca —
+ * are Solana's, so a chain picker offering chains with no CLMM connector behind
+ * them sells a workspace that cannot open a position. One constant, so widening
+ * this later is a list, not a rewrite.
+ */
+const NETWORK = "solana-mainnet-beta";
+
+/** An EVM address or a Solana pubkey — the same guard the backend applies. */
+const ADDRESS_RE = /^(0x[0-9a-fA-F]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$/;
 
 /**
  * Browse pools, because on Gateway the pool *is* the decision.
@@ -24,91 +42,141 @@ const SEARCH_DEBOUNCE_MS = 400;
  */
 export function Dex() {
   const { server } = useServer();
+  const navigate = useNavigate();
+  const { favorites } = useDexFavorites();
   const [source, setSource] = useState<PoolSource>({
     kind: "gecko",
     view: "trending",
   });
-  const [network, setNetwork] = useState("");
+  const [dexes, setDexes] = useState<string[]>([]);
   const [query, setQuery] = useState("");
   const [debouncedQuery, setDebouncedQuery] = useState("");
+  const [page, setPage] = useState(1);
 
   // A browser that refetches per keystroke would exhaust the same GeckoTerminal
   // budget the candle poll loop depends on.
   useEffect(() => {
-    const t = setTimeout(() => setDebouncedQuery(query.trim()), SEARCH_DEBOUNCE_MS);
+    const t = setTimeout(
+      () => setDebouncedQuery(query.trim()),
+      SEARCH_DEBOUNCE_MS,
+    );
     return () => clearTimeout(t);
   }, [query]);
 
+  // Page 4 of Trending is not page 4 of anything else, and a stale page number
+  // would land the user on an empty table.
+  useEffect(() => {
+    setPage(1);
+  }, [source, debouncedQuery, dexes]);
+
   const { data: venues = [] } = useQuery({
-    queryKey: ["venues", server],
-    queryFn: () => api.getVenues(server!),
+    queryKey: ["dex-venues", server, NETWORK],
+    queryFn: () => api.getDexVenues(server!, NETWORK),
     enabled: !!server,
-    staleTime: 5 * 60 * 1000,
+    staleTime: 6 * 60 * 60 * 1000,
   });
 
-  // The chains to offer are the venues Trade does *not* take: the complement of
-  // `hummingbotMarketData`, exactly as CreateExecutor computes it. Never a
-  // hardcoded list.
-  const networks = useMemo(
-    () => venues.filter((v) => !v.hummingbotMarketData).map((v) => v.name),
-    [venues],
-  );
-
-  // Derived, not synced: venues arrive after the first render, so the selection
-  // falls back to the first chain until the user picks one that exists.
-  const activeNetwork =
-    network && networks.includes(network) ? network : (networks[0] ?? "");
-
-  const isTokenSearch = source.kind === "gecko" && source.view === "token";
+  const isSearch = source.kind === "gecko" && source.view === "token";
+  const isAddress = ADDRESS_RE.test(debouncedQuery);
   const enabled =
     !!server &&
-    (source.kind === "gateway" ||
-      (!!activeNetwork && (!isTokenSearch || !!debouncedQuery)));
+    source.kind !== "favorites" &&
+    (source.kind === "gateway" || !isSearch || isAddress);
 
-  const { data: pools = [], isFetching } = useQuery({
+  const { data: pagedPools, isFetching } = useQuery({
     queryKey: [
       "dex-pools",
       server,
       source.kind,
-      source.kind === "gecko" ? source.view : source.connector,
-      activeNetwork,
+      source.kind === "gecko"
+        ? source.view
+        : source.kind === "gateway"
+          ? source.connector
+          : "favorites",
       debouncedQuery,
+      dexes.join(","),
+      page,
     ],
     queryFn: () =>
       api.getDexPools(
         server!,
-        source.kind === "gecko"
+        source.kind === "gateway"
           ? {
-              source: "gecko",
-              network: activeNetwork,
-              view: source.view,
-              query: isTokenSearch ? debouncedQuery : undefined,
-            }
-          : {
               source: "gateway",
               connector: source.connector,
               query: debouncedQuery || undefined,
+              limit: PAGE_SIZE,
+              page,
+            }
+          : {
+              source: "gecko",
+              network: NETWORK,
+              view: source.kind === "gecko" ? source.view : "trending",
+              query: isSearch ? debouncedQuery : undefined,
+              dexes,
+              limit: PAGE_SIZE,
+              page,
             },
       ),
     enabled,
     staleTime: POOL_STALE_MS,
+    placeholderData: (prev) => prev,
+  });
+
+  // The pasted address may be a *pool*, not a token. Both are 44 base58
+  // characters and nothing distinguishes them by shape, so the pool lookup runs
+  // alongside the token search and whichever resolves is what the user meant.
+  const { data: pastedPool } = useQuery({
+    queryKey: ["dex-pool-by-address", server, NETWORK, debouncedQuery],
+    queryFn: () =>
+      api
+        .getDexPoolByAddress(server!, debouncedQuery, NETWORK)
+        .catch(() => null as PoolSummary | null),
+    enabled: !!server && isSearch && isAddress,
+    staleTime: POOL_STALE_MS,
+  });
+
+  const favoriteAddresses = useMemo(
+    () => favorites.filter((f) => f.network === NETWORK).map((f) => f.address),
+    [favorites],
+  );
+
+  const { data: favoritePools = [], isFetching: favoritesFetching } = useQuery({
+    queryKey: ["dex-favorites", server, NETWORK, favoriteAddresses.join(",")],
+    queryFn: () =>
+      api.getDexPoolsByAddress(server!, NETWORK, favoriteAddresses),
+    enabled:
+      !!server && source.kind === "favorites" && !!favoriteAddresses.length,
+    staleTime: POOL_STALE_MS,
   });
 
   if (!server) {
-    return <NoServerCard message="Select a server from the sidebar to browse DEX pools." />;
+    return (
+      <NoServerCard message="Select a server from the sidebar to browse DEX pools." />
+    );
   }
 
-  const emptyMessage = isTokenSearch && !debouncedQuery
-    ? "Paste a token address to find its pools."
-    : "No pools found.";
+  const isFavorites = source.kind === "favorites";
+  const pools = isFavorites ? favoritePools : (pagedPools?.pools ?? []);
+  const loading = isFavorites
+    ? favoritesFetching && !favoritePools.length
+    : isFetching && !pagedPools;
+
+  const emptyMessage = isFavorites
+    ? "No favorites yet — star a pool to keep it here."
+    : isSearch && !isAddress
+      ? debouncedQuery
+        ? "That is not a pool or token address."
+        : "Paste a pool or token address to find it."
+      : "No pools found.";
 
   return (
     <div className="flex flex-col gap-4">
       <div>
         <h1 className="text-lg font-semibold">DEX</h1>
         <p className="text-sm text-[var(--color-text-muted)]">
-          Pools on the networks Condor trades through Gateway. Open one to chart
-          it, swap in it and provide liquidity to it.
+          Solana pools Condor trades through Gateway. Open one to chart it, swap
+          in it and provide liquidity to it.
         </p>
       </div>
 
@@ -116,17 +184,51 @@ export function Dex() {
         <PoolSourceTabs
           source={source}
           onSourceChange={setSource}
-          networks={networks}
-          network={activeNetwork}
-          onNetworkChange={setNetwork}
+          venues={venues}
+          selectedDexes={dexes}
+          onDexesChange={setDexes}
           query={query}
           onQueryChange={setQuery}
+          favoriteCount={favoriteAddresses.length}
         />
+
+        {/* A pasted pool address is an answer, not a search result: it goes above
+            the table with one obvious thing to do to it. */}
+        {pastedPool && (
+          <button
+            onClick={() =>
+              navigate(
+                `/dex/${pastedPool.gateway_network || NETWORK}/${pastedPool.address}`,
+              )
+            }
+            className="flex w-full items-center justify-between border-b border-[var(--color-border)] bg-[var(--color-surface)] px-4 py-2.5 text-left transition-colors hover:bg-[var(--color-surface-hover)]"
+          >
+            <span className="flex items-center gap-2 text-sm">
+              <span className="font-medium">
+                {pastedPool.base_symbol && pastedPool.base_symbol !== "???"
+                  ? `${pastedPool.base_symbol}-${pastedPool.quote_symbol}`
+                  : pastedPool.name}
+              </span>
+              <span className="text-xs text-[var(--color-text-muted)]">
+                {pastedPool.dex_id}
+              </span>
+            </span>
+            <span className="flex items-center gap-1 text-xs text-[var(--color-primary)]">
+              Open pool
+              <ArrowRight className="h-3 w-3" />
+            </span>
+          </button>
+        )}
+
         <PoolBrowser
           pools={pools}
-          isLoading={isFetching && !pools.length}
+          isLoading={loading}
           emptyMessage={emptyMessage}
           showGatewayColumns={source.kind === "gateway"}
+          network={NETWORK}
+          page={isFavorites ? 1 : page}
+          hasMore={isFavorites ? false : !!pagedPools?.has_more}
+          onPageChange={setPage}
         />
       </div>
     </div>
diff --git a/handlers/dex/pool_data.py b/handlers/dex/pool_data.py
index 3cb9f3fe..370e1d89 100644
--- a/handlers/dex/pool_data.py
+++ b/handlers/dex/pool_data.py
@@ -19,6 +19,8 @@
 from typing import Any, Dict, List, Optional, Tuple
 
 from geckoterminal_py import GeckoTerminalAsyncClient
+from geckoterminal_py import constants as GECKO_CONSTANTS
+from glom import glom
 
 from config_manager import get_client
 
@@ -1034,7 +1036,32 @@ def extract_pair_from_name(name: str) -> Tuple[str, str]:
 
 GECKO_POOL_VIEWS = ("trending", "top", "new", "token")
 
-_gecko_pool_list_cache: Dict[Tuple, Tuple[float, List[Dict[str, Any]]]] = {}
+# GeckoTerminal serves every pool list in fixed pages of 20 and answers 401 past
+# page 10, so those two numbers — not a preference of ours — bound what the pool
+# browser can page through.
+GECKO_PAGE_SIZE = 20
+GECKO_MAX_PAGE = 10
+# With a dex filter on, matching rows are scattered across upstream pages and have
+# to be walked for. Capped because the walk costs one rate-limited request per
+# page and the browser is asking for a screenful, not a census.
+_GECKO_FILTER_WALK_PAGES = 3
+# Merging several venues' own listings costs one request per venue per page, so
+# the fan-out is bounded: past this, the chain-wide walk is used instead.
+_GECKO_SCOPED_MAX_REQUESTS = 8
+
+# The list endpoint behind each view. The library exposes one method per view but
+# none of them take ``page``, so the paths are used directly.
+_GECKO_VIEW_PATHS = {
+    "trending": GECKO_CONSTANTS.GET_TRENDING_POOLS_BY_NETWORK_PATH,
+    "top": GECKO_CONSTANTS.GET_TOP_POOLS_BY_NETWORK_PATH,
+    "new": GECKO_CONSTANTS.GET_NEW_POOLS_BY_NETWORK_PATH,
+}
+
+# A chain's venues change on the order of weeks; the filter dropdown reads this.
+GECKO_DEXES_TTL = 6 * 3600
+
+_gecko_page_cache: Dict[Tuple, Tuple[float, List[Dict[str, Any]]]] = {}
+_gecko_dexes_cache: Dict[Tuple, Tuple[float, List[Dict[str, str]]]] = {}
 _gateway_pool_list_cache: Dict[Tuple, Tuple[float, List[Dict[str, Any]]]] = {}
 _pool_by_address_cache: Dict[Tuple[str, str], Tuple[float, Dict[str, Any]]] = {}
 
@@ -1075,6 +1102,53 @@ def _coerce_pool_rows(result: Any, limit: int = 20) -> List[Dict[str, Any]]:
     return [r for r in rows if isinstance(r, dict)][:limit]
 
 
+# Every numeric a pool row carries, and the two upstreams disagree on the type of
+# nearly all of them: GeckoTerminal answers strings (``"12500000.0"``) *and*
+# pandas ``NaN`` for a missing figure, Gateway answers strings for APR and TVL.
+# A NaN is not JSON (FastAPI refuses to encode one, and the whole listing 500s),
+# and a string has no ``.toFixed``, so the browser crashes formatting it. Both are
+# settled here, once, rather than in every consumer.
+_POOL_NUMERIC_FIELDS = (
+    "reserve_usd",
+    "volume_24h",
+    "volume_6h",
+    "volume_1h",
+    "price_change_24h",
+    "price_change_6h",
+    "price_change_1h",
+    "fdv_usd",
+    "market_cap_usd",
+    "current_price",
+    "base_token_price_usd",
+    "quote_token_price_usd",
+    "apr",
+    "apy",
+    "base_fee_percentage",
+)
+
+
+def _finite(value: Any) -> Optional[float]:
+    """``value`` as a float, or None when it is missing, unparseable or NaN."""
+    if value is None or isinstance(value, bool):
+        return None
+    try:
+        number = float(value)
+    except (TypeError, ValueError):
+        return None
+    return number if math.isfinite(number) else None
+
+
+def coerce_pool_numbers(info: Dict[str, Any]) -> Dict[str, Any]:
+    """Make every numeric on a pool row a finite float (or None), in place."""
+    for field in _POOL_NUMERIC_FIELDS:
+        if field in info:
+            info[field] = _finite(info[field])
+    if "bin_step" in info:
+        step = _finite(info.get("bin_step"))
+        info["bin_step"] = int(step) if step is not None else None
+    return info
+
+
 def decorate_pool(info: Dict[str, Any], network: str) -> Dict[str, Any]:
     """Add the venue facts a pool-first UI cannot derive on its own, in place.
 
@@ -1123,7 +1197,7 @@ def _symbol(side: str) -> str:
     base = base_symbol if uses_symbol_pairs(network) else info.get("base_token_address")
     base = str(base or "")
     info["trading_pair"] = f"{base}-{quote_symbol}" if base and quote_symbol else ""
-    return info
+    return coerce_pool_numbers(info)
 
 
 def _normalize_gecko_pool(row: Dict[str, Any], network: str) -> Dict[str, Any]:
@@ -1141,21 +1215,131 @@ def _clamp_pool_limit(limit: Any) -> int:
     return max(1, min(value, _POOL_LIST_MAX))
 
 
-async def list_gecko_pools(
+async def _gecko_page_rows(
+    gnet: str, view: str, token: str, page: int, dex: Optional[str] = None
+) -> Optional[List[Dict[str, Any]]]:
+    """One raw upstream page of pool rows, or None when the fetch failed.
+
+    Raw rather than normalized, because normalization depends on the *caller's*
+    network id (``solana-mainnet-beta`` and ``solana`` are one gecko chain but two
+    Gateway networks) while this cache is keyed by the gecko chain alone.
+
+    None and ``[]`` mean different things and are cached differently: an empty page
+    really is the end of the list, a failure is not, and caching a rate-limit reply
+    for a minute would turn one throttled request into a minute of empty browsers.
+    """
+    key = (gnet, view, token, page, dex or "")
+    cached = _ttl_get(_gecko_page_cache, key, POOL_LIST_TTL)
+    if cached is not None:
+        return [dict(row) for row in cached]
+
+    if dex:
+        path = GECKO_CONSTANTS.GET_TOP_POOLS_BY_NETWORK_DEX_PATH.format(gnet, dex)
+    elif view == "token":
+        path = GECKO_CONSTANTS.GET_TOP_POOLS_BY_NETWORK_TOKEN_PATH.format(gnet, token)
+    else:
+        path = _GECKO_VIEW_PATHS[view].format(gnet)
+
+    try:
+        payload = await _gecko_client().api_request("GET", path, params={"page": page})
+        rows = [
+            row
+            for row in glom(payload, GECKO_CONSTANTS.POOL_SPEC)
+            if isinstance(row, dict)
+        ]
+    except Exception as e:
+        # Every rate-limit reply, and the 401 gecko answers past page 10.
+        logger.warning(
+            "gecko pool page failed net=%s view=%s dex=%s page=%s: %s",
+            gnet,
+            view,
+            dex or "-",
+            page,
+            e,
+        )
+        return None
+
+    _ttl_put(_gecko_page_cache, key, rows, POOL_LIST_TTL)
+    return [dict(row) for row in rows]
+
+
+def _normalized_gecko_rows(
+    rows: List[Dict[str, Any]], network: str, dexes: set
+) -> List[Dict[str, Any]]:
+    """Raw upstream rows → decorated pools, keeping only the venues asked for."""
+    pools: List[Dict[str, Any]] = []
+    for row in rows:
+        try:
+            pool = _normalize_gecko_pool(row, network)
+        except Exception as e:
+            logger.info("gecko pool row skipped net=%s: %s", network, e)
+            continue
+        if not pool.get("address"):
+            continue
+        if dexes and str(pool.get("dex_id") or "").strip().lower() not in dexes:
+            continue
+        pools.append(pool)
+    return pools
+
+
+async def _scoped_top_page(
+    gnet: str, network: str, venues: List[str], limit: int, page: int
+) -> Dict[str, Any]:
+    """Top pools across several venues, from each venue's own listing.
+
+    Filtering the chain-wide list instead would answer almost nothing: Solana's
+    top hundred pools are overwhelmingly one venue's, so "Top, on Meteora and
+    Orca" scanned that way finds a handful of rows and calls it the answer. Each
+    venue's own listing is already the top *of that venue*, so they are merged
+    and re-ranked by volume — which is what the chain-wide list ranks by too.
+
+    Bounded by ``_GECKO_SCOPED_MAX_REQUESTS`` because the fan-out is one request
+    per venue per page, and every one of them shares the chart loop's budget.
+    """
+    skip = (page - 1) * limit
+    pages_each = min(-(-(skip + limit) // GECKO_PAGE_SIZE), GECKO_MAX_PAGE)
+    budget = _GECKO_SCOPED_MAX_REQUESTS
+
+    rows: List[Dict[str, Any]] = []
+    for venue in venues:
+        for upstream in range(1, pages_each + 1):
+            if budget <= 0:
+                break
+            budget -= 1
+            got = await _gecko_page_rows(gnet, "top", "", upstream, dex=venue)
+            if got is None:
+                break  # this venue is as far as it goes; the others still count
+            rows.extend(got)
+            if len(got) < GECKO_PAGE_SIZE:
+                break
+
+    pools = _normalized_gecko_rows(rows, network, set())
+    pools.sort(key=lambda p: p.get("volume_24h") or 0.0, reverse=True)
+    return {
+        "pools": pools[skip : skip + limit],
+        "has_more": len(pools) > skip + limit,
+    }
+
+
+async def list_gecko_pools_page(
     network: str,
     view: str = "trending",
     token: Optional[str] = None,
     limit: int = 20,
-) -> List[Dict[str, Any]]:
-    """GeckoTerminal pools for a chain: ``trending``, ``top``, ``new`` or by token.
-
-    ``network`` may be a Gateway network id or a gecko chain id — ``get_gecko_network``
-    normalizes either. ``view="token"`` needs ``token`` to be a real address; a
-    ticker would be pasted straight into a URL path segment, so it is refused here.
-
-    An upstream failure answers ``[]`` (and is not cached), because the caller's
-    honest rendering of "no pools" is more useful than an error the user cannot act
-    on. A successful empty answer *is* cached — that chain really has no such list.
+    page: int = 1,
+    dexes: Optional[List[str]] = None,
+) -> Dict[str, Any]:
+    """One page of GeckoTerminal pools, optionally narrowed to given venues.
+
+    ``page`` is the browser's page, which is not the upstream's: gecko pages are a
+    fixed 20 rows, the browser picks its own size, and with a dex filter on the
+    matching rows are scattered across upstream pages. So the window
+    ``[(page-1)*limit, page*limit)`` is cut out of a walk over upstream pages —
+    started at the page that can hold it when unfiltered, and at the first page
+    when filtering, since only then do we know how many rows matched before it.
+
+    ``has_more`` is answered from what the walk saw, not guessed from a full page:
+    a Next that lands on nothing is worse than no Next at all.
     """
     from condor.dex_candles import ADDRESS_RE
 
@@ -1165,42 +1349,151 @@ async def list_gecko_pools(
         view = "trending"
     token = (token or "").strip()
     if view == "token" and not ADDRESS_RE.match(token):
-        return []
+        return {"pools": [], "has_more": False}
     limit = _clamp_pool_limit(limit)
+    try:
+        page = max(1, int(page))
+    except (TypeError, ValueError):
+        page = 1
+    wanted = {d.strip().lower() for d in (dexes or []) if str(d).strip()}
+
+    # One venue's *top* pools is a listing GeckoTerminal serves directly, already
+    # scoped and already paged — so that case costs one request instead of a walk,
+    # and pages as deep as the venue goes rather than as deep as we cared to scan.
+    # Trending and New have no venue-scoped form, so those still walk.
+    if view == "top" and len(wanted) > 1:
+        return await _scoped_top_page(gnet, network, sorted(wanted), limit, page)
+    scope = next(iter(wanted)) if view == "top" and len(wanted) == 1 else None
+    if scope:
+        wanted = set()
+
+    skip = (page - 1) * limit
+    # With nothing to filter out, row N is on a known upstream page, so the walk
+    # starts there rather than re-fetching everything before it.
+    upstream = 1 if wanted else skip // GECKO_PAGE_SIZE + 1
+    local_skip = skip if wanted else skip % GECKO_PAGE_SIZE
+    last_page = (
+        min(GECKO_MAX_PAGE, upstream + _GECKO_FILTER_WALK_PAGES - 1)
+        if wanted
+        else GECKO_MAX_PAGE
+    )
+
+    collected: List[Dict[str, Any]] = []
+    has_more = False
+    while upstream <= last_page:
+        rows = await _gecko_page_rows(gnet, view, token, upstream, dex=scope)
+        if rows is None:
+            # An upstream failure is not an empty chain: say nothing rather than
+            # claiming this view has no pools, and never cache the claim. Mid-walk
+            # though, the rows already in hand are a screenful the user can use —
+            # a rate limit hit on page 3 must not blank pages 1 and 2.
+            if not collected:
+                return {"pools": [], "has_more": False}
+            break
+        collected.extend(_normalized_gecko_rows(rows, network, wanted))
+        if len(collected) > local_skip + limit:
+            has_more = True
+            break
+        if len(rows) < GECKO_PAGE_SIZE:
+            break  # upstream has no more rows behind this page
+        upstream += 1
+        if len(collected) >= local_skip + limit:
+            has_more = upstream <= last_page
+            break
+
+    pools = collected[local_skip : local_skip + limit]
+    return {"pools": pools, "has_more": has_more and len(pools) == limit}
+
+
+async def list_gecko_pools(
+    network: str,
+    view: str = "trending",
+    token: Optional[str] = None,
+    limit: int = 20,
+) -> List[Dict[str, Any]]:
+    """The first page of :func:`list_gecko_pools_page`, for callers with no paging."""
+    result = await list_gecko_pools_page(
+        network, view=view, token=token, limit=limit, page=1
+    )
+    return result["pools"]
 
-    key = (gnet, view, token, limit)
-    cached = _ttl_get(_gecko_pool_list_cache, key, POOL_LIST_TTL)
+
+async def list_gecko_dexes(network: str) -> List[Dict[str, str]]:
+    """The venues GeckoTerminal indexes on a chain, for the browser's dex filter.
+
+    The filter offers what the chain actually has rather than a hardcoded list, so
+    a new venue shows up without a deploy. An upstream failure answers ``[]``: a
+    filter that cannot be populated is a filter the user simply does not see.
+    """
+    gnet = get_gecko_network(network)
+    cached = _ttl_get(_gecko_dexes_cache, (gnet,), GECKO_DEXES_TTL)
     if cached is not None:
         return [dict(row) for row in cached]
 
-    client = _gecko_client()
     try:
-        if view == "trending":
-            result = await client.get_trending_pools_by_network(gnet)
-        elif view == "top":
-            result = await client.get_top_pools_by_network(gnet)
-        elif view == "new":
-            result = await client.get_new_pools_by_network(gnet)
-        else:
-            result = await client.get_top_pools_by_network_token(gnet, token)
+        payload = await _gecko_client().api_request(
+            "GET", GECKO_CONSTANTS.GET_DEXES_BY_NETWORK_PATH.format(gnet)
+        )
+        rows = glom(payload, GECKO_CONSTANTS.DEXES_BY_NETWORK_SPEC)
     except Exception as e:
-        # Includes the KeyError geckoterminal_py raises post-processing an empty
-        # result set, and every rate-limit response.
-        logger.warning("gecko pool list failed net=%s view=%s: %s", gnet, view, e)
+        logger.warning("gecko dex list failed net=%s: %s", gnet, e)
+        return []
+
+    dexes = [
+        {"id": str(row["id"]), "name": str(row.get("name") or row["id"])}
+        for row in rows
+        if isinstance(row, dict) and row.get("id")
+    ]
+    _ttl_put(_gecko_dexes_cache, (gnet,), dexes, GECKO_DEXES_TTL)
+    return [dict(row) for row in dexes]
+
+
+# GeckoTerminal's multi-pool endpoint takes at most 30 addresses in one path.
+_GECKO_MULTI_MAX = 30
+
+
+async def fetch_pools_by_addresses(
+    network: str, addresses: List[str]
+) -> List[Dict[str, Any]]:
+    """Several pools by address in one request, for the favourites view.
+
+    Favourites are stored as addresses, not as copies of the rows: a saved pool is
+    a pointer, and its TVL, volume and price have to be as live as any other row in
+    the table. Addresses that resolve to nothing are simply absent from the answer
+    — a pool that has since been dropped from the index is not an error.
+    """
+    from condor.dex_candles import ADDRESS_RE
+
+    gnet = get_gecko_network(network)
+    seen: List[str] = []
+    for address in addresses:
+        address = str(address or "").strip()
+        if address and ADDRESS_RE.match(address) and address not in seen:
+            seen.append(address)
+    if not seen:
         return []
 
     pools: List[Dict[str, Any]] = []
-    for row in _coerce_pool_rows(result, limit):
+    for start in range(0, len(seen), _GECKO_MULTI_MAX):
+        batch = seen[start : start + _GECKO_MULTI_MAX]
         try:
-            pool = _normalize_gecko_pool(row, network)
+            result = await _gecko_client().get_multiple_pools_by_network(gnet, batch)
         except Exception as e:
-            logger.info("gecko pool row skipped net=%s: %s", gnet, e)
+            logger.warning("gecko multi-pool failed net=%s: %s", gnet, e)
             continue
-        if pool.get("address"):
-            pools.append(pool)
+        for row in _coerce_pool_rows(result, len(batch)):
+            try:
+                pool = _normalize_gecko_pool(row, network)
+            except Exception as e:
+                logger.info("gecko pool row skipped net=%s: %s", gnet, e)
+                continue
+            if pool.get("address"):
+                pools.append(pool)
 
-    _ttl_put(_gecko_pool_list_cache, key, pools, POOL_LIST_TTL)
-    return [dict(row) for row in pools]
+    # In the order the caller saved them, not the order gecko answers in.
+    rank = {address: i for i, address in enumerate(seen)}
+    pools.sort(key=lambda p: rank.get(str(p.get("address")), len(rank)))
+    return pools
 
 
 def gateway_connector_network(connector: str) -> str:
@@ -1213,6 +1506,7 @@ async def list_gateway_pools(
     connector: str,
     search: Optional[str] = None,
     limit: int = 20,
+    page: int = 1,
 ) -> List[Dict[str, Any]]:
     """Gateway CLMM pools for a connector, optionally filtered by free text.
 
@@ -1220,14 +1514,21 @@ async def list_gateway_pools(
     client) and searches *within* a connector by name rather than by token address
     — which is why the route keeps the two behind a ``source`` discriminator
     instead of one parameter set with meaningless combinations.
+
+    ``page`` is 1-based like every other page in the browser; Gateway counts from
+    zero, and that translation stays here rather than in the route.
     """
     connector = (connector or "").strip().lower()
     if not connector:
         return []
     search = (search or "").strip() or None
     limit = _clamp_pool_limit(limit)
+    try:
+        page = max(1, int(page))
+    except (TypeError, ValueError):
+        page = 1
 
-    key = (connector, search or "", limit)
+    key = (connector, search or "", limit, page)
     cached = _ttl_get(_gateway_pool_list_cache, key, GATEWAY_POOL_LIST_TTL)
     if cached is not None:
         return [dict(row) for row in cached]
@@ -1238,7 +1539,7 @@ async def list_gateway_pools(
 
     try:
         result = await client.gateway_clmm.get_pools(
-            connector=connector, page=0, limit=limit, search_term=search
+            connector=connector, page=page - 1, limit=limit, search_term=search
         )
     except Exception as e:
         logger.warning("gateway pool list failed connector=%s: %s", connector, e)
diff --git a/tests/test_dex_pool_discovery.py b/tests/test_dex_pool_discovery.py
index 63c71ba4..c7275a1d 100644
--- a/tests/test_dex_pool_discovery.py
+++ b/tests/test_dex_pool_discovery.py
@@ -31,7 +31,8 @@ def run(coro):
 @pytest.fixture(autouse=True)
 def _clear_caches():
     for cache in (
-        pool_data._gecko_pool_list_cache,
+        pool_data._gecko_page_cache,
+        pool_data._gecko_dexes_cache,
         pool_data._gateway_pool_list_cache,
         pool_data._pool_by_address_cache,
     ):
@@ -81,34 +82,106 @@ def gateway_row(**over):
     return row
 
 
+def api_row(row=None, **over):
+    """One row in the shape the *API* returns, which ``glom`` reads.
+
+    ``gecko_row`` is the flat DataFrame shape the library hands back; the paged
+    listing talks to the endpoint directly, so the fake has to answer the nested
+    JSON the flat shape is derived from.
+    """
+    flat = dict(row or gecko_row())
+    flat.update(over)
+    return {
+        "id": flat.get("id", ""),
+        "type": "pool",
+        "attributes": {
+            "address": flat.get("address", ""),
+            "name": flat.get("name", ""),
+            "base_token_price_usd": flat.get("base_token_price_usd"),
+            "base_token_price_native_currency": None,
+            "quote_token_price_usd": flat.get("quote_token_price_usd"),
+            "quote_token_price_native_currency": None,
+            "reserve_in_usd": flat.get("reserve_in_usd"),
+            "pool_created_at": flat.get("pool_created_at"),
+            "fdv_usd": flat.get("fdv_usd"),
+            "market_cap_usd": flat.get("market_cap_usd"),
+            "price_change_percentage": {
+                "h1": flat.get("price_change_percentage_h1"),
+                "h24": flat.get("price_change_percentage_h24"),
+            },
+            "transactions": {
+                "h1": {"buys": 0, "sells": 0},
+                "h24": {"buys": 0, "sells": 0},
+            },
+            "volume_usd": {"h24": flat.get("volume_usd_h24")},
+        },
+        "relationships": {
+            "dex": {"data": {"id": flat.get("dex_id", "meteora")}},
+            "base_token": {"data": {"id": flat.get("base_token_id", "")}},
+            "quote_token": {"data": {"id": flat.get("quote_token_id", "")}},
+        },
+    }
+
+
+_VIEW_BY_SUFFIX = {"trending_pools": "trending", "new_pools": "new", "pools": "top"}
+
+
 class FakeGecko:
-    """Stands in for the shared GeckoTerminalAsyncClient."""
+    """Stands in for the shared GeckoTerminalAsyncClient.
+
+    The pool listings go through ``api_request`` (the library exposes no ``page``),
+    so that is the surface faked; ``frame`` is served as upstream page 1 and every
+    page behind it is empty, which is how a real list ends.
+    """
 
     def __init__(self, frame=None, error=None):
         self.frame = frame
         self.error = error
         self.calls: list[tuple] = []
-
-    async def _answer(self, *args):
-        self.calls.append(args)
+        self.pages: list[int] = []
+
+    def _rows(self):
+        if self.frame is None:
+            return []
+        rows = (
+            self.frame.to_dict("records")
+            if hasattr(self.frame, "to_dict")
+            else list(self.frame)
+        )
+        return [api_row(r) for r in rows]
+
+    async def api_request(self, method, path, params=None):
+        parts = path.split("/")
+        network = parts[1]
+        if parts[-1] == "dexes":
+            self.calls.append(("dexes", network))
+        elif parts[-2] == "tokens" or (len(parts) > 3 and parts[2] == "tokens"):
+            self.calls.append(("token", network, parts[3]))
+        else:
+            self.calls.append((_VIEW_BY_SUFFIX.get(parts[-1], parts[-1]), network))
+        page = int((params or {}).get("page", 1))
+        self.pages.append(page)
+        if self.error:
+            raise self.error
+        if parts[-1] == "dexes":
+            return {
+                "data": [
+                    {"id": "meteora", "type": "dex", "attributes": {"name": "Meteora"}}
+                ]
+            }
+        return {"data": self._rows() if page == 1 else []}
+
+    async def get_multiple_pools_by_network(self, n, addresses):
+        self.calls.append(("multi", n, tuple(addresses)))
         if self.error:
             raise self.error
         return self.frame
 
-    async def get_trending_pools_by_network(self, n):
-        return await self._answer("trending", n)
-
-    async def get_top_pools_by_network(self, n):
-        return await self._answer("top", n)
-
-    async def get_new_pools_by_network(self, n):
-        return await self._answer("new", n)
-
-    async def get_top_pools_by_network_token(self, n, t):
-        return await self._answer("token", n, t)
-
     async def get_pool_by_network_address(self, n, a):
-        return await self._answer("address", n, a)
+        self.calls.append(("address", n, a))
+        if self.error:
+            raise self.error
+        return self.frame
 
 
 @pytest.fixture
@@ -326,6 +399,7 @@ def test_rows_with_no_address_are_dropped(fake_gecko):
 def test_limit_is_clamped(fake_gecko):
     fake_gecko(pd.DataFrame([gecko_row(address=POOL)] * 60))
     assert len(run(pool_data.list_gecko_pools("solana", limit=5))) == 5
+    # Clamped to _POOL_LIST_MAX, so the whole 60 rows the upstream has come back.
     assert len(run(pool_data.list_gecko_pools("solana", limit=10_000))) == 60
 
 
@@ -541,3 +615,278 @@ def test_pool_by_address_rejects_a_non_address(route_client, fake_gecko):
 def test_unknown_pool_is_a_404(route_client, fake_gecko):
     fake_gecko(pd.DataFrame())
     assert route_client().get(f"/servers/srv/dex/pools/{POOL}").status_code == 404
+
+
+# ── paging, dex filter and favourites ──
+
+
+@pytest.fixture
+def paged_gecko(monkeypatch):
+    """Install a fake whose upstream pages differ, and take it away again."""
+
+    def install(pages):
+        client = PagedGecko(pages)
+        monkeypatch.setattr(pool_data, "_gecko_client", lambda: client)
+        return client
+
+    return install
+
+
+class PagedGecko(FakeGecko):
+    """A fake whose upstream pages differ, so a window can be told from a repeat."""
+
+    def __init__(self, pages):
+        super().__init__()
+        self.by_page = pages
+        self.scopes: list = []
+        # From this upstream page on, the fake answers like a rate limit.
+        self.fail_from = None
+
+    def _rows(self):
+        return []
+
+    async def api_request(self, method, path, params=None):
+        page = int((params or {}).get("page", 1))
+        parts = path.split("/")
+        self.scopes.append(parts[3] if len(parts) > 3 and parts[2] == "dexes" else None)
+        self.pages.append(page)
+        self.calls.append(("page", page))
+        if self.fail_from is not None and page >= self.fail_from:
+            raise RuntimeError("429 rate limited")
+        rows = self.by_page.get(page, [])
+        return {"data": [api_row(r) for r in rows]}
+
+
+# Base58 has no 0, O, I or l, and the address guard knows it — so a synthetic
+# address has to be built out of the real alphabet, not zero-padded.
+_B58 = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
+
+
+def addr(i):
+    """A distinct, valid pool address, so a page's identity is checkable."""
+    return POOL[:-2] + _B58[i // 58] + _B58[i % 58]
+
+
+def _rows(count, dex_id="meteora", start=0):
+    return [gecko_row(dex_id=dex_id, address=addr(i + start)) for i in range(count)]
+
+
+def test_a_page_of_20_maps_onto_the_upstream_page_that_holds_it(paged_gecko):
+    """Gecko pages are a fixed 20, so page 3 must not re-walk pages 1 and 2."""
+    client = paged_gecko({3: _rows(20, start=40)})
+    result = run(pool_data.list_gecko_pools_page("solana", limit=20, page=3))
+    assert client.pages == [3], "an unfiltered page is one upstream request"
+    assert len(result["pools"]) == 20
+
+
+def test_paging_cuts_the_window_out_of_the_upstream_pages(paged_gecko):
+    client = paged_gecko({1: _rows(20, start=0), 2: _rows(20, start=20)})
+    # 10 rows a page: the second half of upstream page 1.
+    second = run(pool_data.list_gecko_pools_page("solana", limit=10, page=2))
+    assert [p["address"] for p in second["pools"]] == [addr(i) for i in range(10, 20)]
+    assert second["has_more"] is True
+
+
+def test_has_more_is_false_at_the_end_of_the_list(paged_gecko):
+    client = paged_gecko({1: _rows(5)})
+    result = run(pool_data.list_gecko_pools_page("solana", limit=20, page=1))
+    assert len(result["pools"]) == 5 and result["has_more"] is False
+
+
+def test_the_dex_filter_keeps_only_the_venues_asked_for(paged_gecko):
+    client = paged_gecko(
+        {1: _rows(10, dex_id="meteora") + _rows(10, dex_id="pumpswap", start=50)}
+    )
+    result = run(
+        pool_data.list_gecko_pools_page("solana", limit=20, page=1, dexes=["meteora"])
+    )
+    assert {p["dex_id"] for p in result["pools"]} == {"meteora"}
+    assert len(result["pools"]) == 10
+
+
+def test_the_dex_filter_walks_pages_to_fill_one_screen(paged_gecko):
+    """Matching rows are scattered upstream, so a filtered page is a walk."""
+    client = paged_gecko(
+        {
+            1: _rows(19, dex_id="pumpswap") + _rows(1, dex_id="meteora", start=90),
+            2: _rows(19, dex_id="pumpswap", start=20) + _rows(1, "meteora", start=91),
+        }
+    )
+    result = run(
+        pool_data.list_gecko_pools_page("solana", limit=2, page=1, dexes=["meteora"])
+    )
+    assert len(result["pools"]) == 2
+    assert client.pages == [1, 2]
+
+
+def test_an_empty_dex_filter_is_no_filter(fake_gecko):
+    client = fake_gecko(pd.DataFrame([gecko_row(dex_id="pumpswap")]))
+    result = run(pool_data.list_gecko_pools_page("solana", dexes=["", "  "]))
+    assert len(result["pools"]) == 1
+
+
+def test_a_nan_never_reaches_the_wire(route_client, fake_gecko):
+    """pandas answers NaN for a missing figure, and NaN is not JSON.
+
+    FastAPI refuses to encode one and the whole listing 500s, which is exactly how
+    the trending view broke — so it is settled in decoration, not left to the route.
+    """
+    row = gecko_row()
+    row["market_cap_usd"] = float("nan")
+    row["reserve_in_usd"] = float("nan")
+    fake_gecko(pd.DataFrame([row]))
+    r = route_client().get("/servers/srv/dex/pools")
+    assert r.status_code == 200
+    pool = r.json()["pools"][0]
+    assert pool["market_cap_usd"] is None and pool["reserve_usd"] is None
+
+
+def test_gateway_numbers_arrive_as_numbers_not_strings():
+    """Gateway answers APR and TVL as strings; a string has no ``.toFixed``."""
+    clmm = FakeClmm(
+        {"pools": [gateway_row(apr="0.2724", liquidity="861007.27", bin_step="4")]}
+    )
+    pool = run(pool_data.list_gateway_pools(FakeClient(clmm), "meteora"))[0]
+    assert pool["apr"] == pytest.approx(0.2724)
+    assert pool["reserve_usd"] == pytest.approx(861007.27)
+    assert pool["bin_step"] == 4
+
+
+def test_gateway_paging_is_zero_based_upstream():
+    clmm = FakeClmm({"pools": []})
+    run(pool_data.list_gateway_pools(FakeClient(clmm), "meteora", page=3))
+    assert clmm.calls[0]["page"] == 2
+
+
+def test_gateway_pages_are_cached_separately():
+    clmm = FakeClmm({"pools": [gateway_row()]})
+    client = FakeClient(clmm)
+    run(pool_data.list_gateway_pools(client, "meteora", page=1))
+    run(pool_data.list_gateway_pools(client, "meteora", page=1))
+    assert len(clmm.calls) == 1
+    run(pool_data.list_gateway_pools(client, "meteora", page=2))
+    assert len(clmm.calls) == 2
+
+
+def test_favourites_are_fetched_by_address_in_the_saved_order(fake_gecko):
+    a, b = addr(1), addr(2)
+    client = fake_gecko(pd.DataFrame([gecko_row(address=b), gecko_row(address=a)]))
+    pools = run(pool_data.fetch_pools_by_addresses("solana-mainnet-beta", [a, b]))
+    assert [p["address"] for p in pools] == [a, b]
+    assert client.calls[0][0] == "multi"
+
+
+def test_favourites_ignore_junk_addresses(fake_gecko):
+    client = fake_gecko(pd.DataFrame([gecko_row()]))
+    assert run(pool_data.fetch_pools_by_addresses("solana", ["", "nope!"])) == []
+    assert client.calls == []
+
+
+def test_the_dex_filter_options_come_from_the_chain(route_client, fake_gecko):
+    fake_gecko(pd.DataFrame([gecko_row()]))
+    r = route_client().get("/servers/srv/dex/dexes?network=solana-mainnet-beta")
+    assert r.status_code == 200
+    assert r.json()["dexes"] == [{"id": "meteora", "name": "Meteora"}]
+
+
+def test_favourites_route_answers_the_saved_pools(route_client, fake_gecko):
+    fake_gecko(pd.DataFrame([gecko_row()]))
+    r = route_client().get(f"/servers/srv/dex/pools-by-address?addresses={POOL}")
+    assert r.status_code == 200
+    assert r.json()["pools"][0]["address"] == POOL
+
+
+def test_favourites_route_is_not_read_as_a_pool_address(route_client, fake_gecko):
+    """It is declared above ``/dex/pools/{pool_address}`` for exactly this reason."""
+    fake_gecko(pd.DataFrame())
+    r = route_client().get("/servers/srv/dex/pools-by-address?addresses=")
+    assert r.status_code == 200 and r.json()["pools"] == []
+
+
+def test_one_venues_top_pools_use_the_venue_endpoint(paged_gecko):
+    """A scoped listing is one request, not a walk over the whole chain."""
+    client = paged_gecko({1: _rows(20, dex_id="meteora")})
+    result = run(
+        pool_data.list_gecko_pools_page("solana", view="top", dexes=["meteora"])
+    )
+    assert len(result["pools"]) == 20
+    assert client.pages == [1], "the venue's own listing is already scoped"
+    assert client.scopes == ["meteora"]
+
+
+def test_several_venues_top_pools_are_merged_from_each_venues_listing(paged_gecko):
+    """Filtering the chain-wide list would answer almost nothing — one venue
+    dominates it — so each venue's own top listing is read and merged."""
+    client = paged_gecko({1: _rows(5, dex_id="meteora")})
+    result = run(
+        pool_data.list_gecko_pools_page("solana", view="top", dexes=["meteora", "orca"])
+    )
+    assert client.scopes == ["meteora", "orca"]
+    assert len(result["pools"]) == 10  # both venues' rows, not an intersection
+
+
+def test_a_merged_venue_listing_is_ranked_by_volume(paged_gecko):
+    quiet = gecko_row(dex_id="meteora", address=addr(1))
+    quiet["volume_usd_h24"] = "1000.0"
+    busy = gecko_row(dex_id="orca", address=addr(2))
+    busy["volume_usd_h24"] = "9000000.0"
+    client = paged_gecko({})
+    client.by_page = {1: [quiet]}
+
+    async def scoped(method, path, params=None):
+        parts = path.split("/")
+        venue = parts[3]
+        client.scopes.append(venue)
+        return {"data": [api_row(busy if venue == "orca" else quiet)]}
+
+    client.api_request = scoped
+    result = run(
+        pool_data.list_gecko_pools_page("solana", view="top", dexes=["meteora", "orca"])
+    )
+    assert [p["dex_id"] for p in result["pools"]] == ["orca", "meteora"]
+
+
+def test_a_venue_whose_listing_fails_does_not_take_the_others_with_it(paged_gecko):
+    client = paged_gecko({})
+
+    async def half_broken(method, path, params=None):
+        venue = path.split("/")[3]
+        client.scopes.append(venue)
+        if venue == "orca":
+            raise RuntimeError("429 rate limited")
+        return {"data": [api_row(gecko_row(dex_id="meteora"))]}
+
+    client.api_request = half_broken
+    result = run(
+        pool_data.list_gecko_pools_page("solana", view="top", dexes=["meteora", "orca"])
+    )
+    assert [p["dex_id"] for p in result["pools"]] == ["meteora"]
+
+
+def test_trending_never_uses_the_venue_endpoint(paged_gecko):
+    """There is no venue-scoped *trending*, and silently serving Top instead lies."""
+    client = paged_gecko({1: _rows(20, dex_id="meteora")})
+    run(pool_data.list_gecko_pools_page("solana", view="trending", dexes=["meteora"]))
+    assert client.scopes[0] is None
+
+
+def test_a_mid_walk_failure_keeps_what_was_already_found(paged_gecko):
+    """A rate limit on page 3 must not blank the rows pages 1 and 2 produced."""
+    client = paged_gecko({1: _rows(20, dex_id="meteora")})
+    client.fail_from = 2
+    # 30 a page, so one upstream page is not enough and the walk goes on to fail.
+    result = run(
+        pool_data.list_gecko_pools_page(
+            "solana", view="trending", limit=30, dexes=["meteora"]
+        )
+    )
+    assert client.pages == [1, 2]
+    assert len(result["pools"]) == 20
+    assert result["has_more"] is False
+
+
+def test_a_first_page_failure_is_still_empty(paged_gecko):
+    client = paged_gecko({})
+    client.fail_from = 1
+    result = run(pool_data.list_gecko_pools_page("solana", dexes=["meteora"]))
+    assert result == {"pools": [], "has_more": False}

From 7bc76e7fbfbcdf5fa538c21fd97444e21524811d Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Thu, 13 Aug 2026 18:33:31 +0300
Subject: [PATCH 043/116] (feat) fix default wallet

---
 condor/web/routes/settings.py | 60 ++++++++++++++++++++++++++++++++---
 frontend/src/lib/api.ts       |  2 +-
 2 files changed, 56 insertions(+), 6 deletions(-)

diff --git a/condor/web/routes/settings.py b/condor/web/routes/settings.py
index 43f70454..7edada08 100644
--- a/condor/web/routes/settings.py
+++ b/condor/web/routes/settings.py
@@ -299,7 +299,9 @@ async def gateway_networks(
     client = await _get_client(cm, server)
     try:
         result = await client.gateway.list_networks()
-        networks = result.get("networks", result) if isinstance(result, dict) else result
+        networks = (
+            result.get("networks", result) if isinstance(result, dict) else result
+        )
         return {"networks": networks}
     except Exception as e:
         logger.exception("Failed to list gateway networks from '%s'", server)
@@ -367,6 +369,21 @@ async def gateway_wallets(
         raise upstream_error("Failed to list gateway wallets", e)
 
 
+async def _gateway_default_address(client, chain: str) -> str | None:
+    """Current default wallet address for a chain, or None if there is none."""
+    try:
+        groups = await client.accounts.list_gateway_wallets()
+    except Exception:
+        logger.warning(
+            "Could not read gateway wallets to preserve default for '%s'", chain
+        )
+        return None
+    for group in groups or []:
+        if isinstance(group, dict) and group.get("chain") == chain:
+            return group.get("default_address") or None
+    return None
+
+
 @router.post("/gateway/wallets")
 async def gateway_wallet_add(
     req: GatewayWalletAddRequest,
@@ -377,16 +394,39 @@ async def gateway_wallet_add(
     if not cm.has_server_access(user.id, server):
         raise HTTPException(status_code=403, detail="No access")
     client = await _get_client(cm, server)
+    # Gateway's add-wallet always promotes the new key to the chain default, so when the user
+    # opted out we capture the existing default first and restore it after the import.
+    previous_default = (
+        None if req.set_default else await _gateway_default_address(client, req.chain)
+    )
     try:
         result = await client.accounts.add_gateway_wallet(
             chain=req.chain, private_key=req.private_key
         )
         address = result.get("address") if isinstance(result, dict) else None
+        is_default = True
         if req.set_default and address:
             await client.accounts.set_default_gateway_wallet(
                 chain=req.chain, address=address
             )
-        return {"added": True, "chain": req.chain, "address": address}
+        elif previous_default and previous_default != address:
+            try:
+                await client.accounts.set_default_gateway_wallet(
+                    chain=req.chain, address=previous_default
+                )
+                is_default = False
+            except Exception:
+                logger.exception(
+                    "Imported wallet on '%s' but failed to restore previous default on chain '%s'",
+                    server,
+                    req.chain,
+                )
+        return {
+            "added": True,
+            "chain": req.chain,
+            "address": address,
+            "is_default": is_default,
+        }
     except Exception as e:
         # Never include the request payload here — it carries the private key.
         logger.exception(
@@ -409,7 +449,12 @@ async def gateway_wallet_set_default(
         result = await client.accounts.set_default_gateway_wallet(
             chain=req.chain, address=req.address
         )
-        return {"default": True, "chain": req.chain, "address": req.address, "result": result}
+        return {
+            "default": True,
+            "chain": req.chain,
+            "address": req.address,
+            "result": result,
+        }
     except Exception as e:
         logger.exception(
             "Failed to set default gateway wallet on '%s' via '%s'", req.chain, server
@@ -429,11 +474,16 @@ async def gateway_wallet_remove(
         raise HTTPException(status_code=403, detail="No access")
     client = await _get_client(cm, server)
     try:
-        result = await client.accounts.remove_gateway_wallet(chain=chain, address=address)
+        result = await client.accounts.remove_gateway_wallet(
+            chain=chain, address=address
+        )
         return {"removed": True, "chain": chain, "address": address, "result": result}
     except Exception as e:
         logger.exception(
-            "Failed to remove gateway wallet %s on '%s' via '%s'", address, chain, server
+            "Failed to remove gateway wallet %s on '%s' via '%s'",
+            address,
+            chain,
+            server,
         )
         raise upstream_error("Failed to remove wallet", e)
 
diff --git a/frontend/src/lib/api.ts b/frontend/src/lib/api.ts
index 3201d8cf..976c16ba 100644
--- a/frontend/src/lib/api.ts
+++ b/frontend/src/lib/api.ts
@@ -1930,7 +1930,7 @@ export const api = {
     server: string,
     data: { chain: string; private_key: string; set_default?: boolean },
   ) =>
-    apiFetch<{ added: boolean; chain: string; address: string | null }>(
+    apiFetch<{ added: boolean; chain: string; address: string | null; is_default: boolean }>(
       `/api/v1/settings/gateway/wallets?server=${encodeURIComponent(server)}`,
       { method: "POST", body: JSON.stringify(data) },
     ),

From 49547896446ff0d4ca75857d2113011b905dfc2f Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Thu, 13 Aug 2026 18:57:32 +0300
Subject: [PATCH 044/116] (feat) add fav tab

---
 frontend/src/lib/dexFavorites.ts | 78 ++++++++++++++++++++++++++++++++
 1 file changed, 78 insertions(+)
 create mode 100644 frontend/src/lib/dexFavorites.ts

diff --git a/frontend/src/lib/dexFavorites.ts b/frontend/src/lib/dexFavorites.ts
new file mode 100644
index 00000000..1df61623
--- /dev/null
+++ b/frontend/src/lib/dexFavorites.ts
@@ -0,0 +1,78 @@
+import { useCallback, useEffect, useState } from "react";
+
+/**
+ * Starred pools, kept in localStorage.
+ *
+ * A favourite is stored as `{network, address}` and nothing else: the row's TVL,
+ * volume and price have to be as live as any other row in the table, so the
+ * favourites view re-reads them by address rather than replaying a copy taken
+ * whenever the star was clicked.
+ *
+ * Per browser rather than per account, like the theme and the display currency —
+ * the pools you are watching are a workspace preference, not server state.
+ */
+const STORAGE_KEY = "condor_dex_favorites";
+
+export interface FavoritePool {
+  network: string;
+  address: string;
+}
+
+/** Same pool: the address alone is ambiguous across chains. */
+function same(a: FavoritePool, b: FavoritePool): boolean {
+  return a.address === b.address && a.network === b.network;
+}
+
+function read(): FavoritePool[] {
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY);
+    if (!raw) return [];
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter(
+      (f): f is FavoritePool =>
+        !!f && typeof f.address === "string" && typeof f.network === "string",
+    );
+  } catch {
+    // A hand-edited or half-written entry is not worth failing the page over.
+    return [];
+  }
+}
+
+function write(favorites: FavoritePool[]) {
+  localStorage.setItem(STORAGE_KEY, JSON.stringify(favorites));
+  // Same-tab listeners: `storage` only fires in the *other* tabs.
+  window.dispatchEvent(new Event(EVENT));
+}
+
+const EVENT = "condor:dex-favorites";
+
+/** The starred pools, and a toggle — shared by every component that reads them. */
+export function useDexFavorites() {
+  const [favorites, setFavorites] = useState<FavoritePool[]>(read);
+
+  useEffect(() => {
+    const sync = () => setFavorites(read());
+    window.addEventListener(EVENT, sync);
+    window.addEventListener("storage", sync);
+    return () => {
+      window.removeEventListener(EVENT, sync);
+      window.removeEventListener("storage", sync);
+    };
+  }, []);
+
+  const toggle = useCallback((pool: FavoritePool) => {
+    const current = read();
+    const next = current.some((f) => same(f, pool))
+      ? current.filter((f) => !same(f, pool))
+      : [...current, { network: pool.network, address: pool.address }];
+    write(next);
+  }, []);
+
+  const isFavorite = useCallback(
+    (pool: FavoritePool) => favorites.some((f) => same(f, pool)),
+    [favorites],
+  );
+
+  return { favorites, toggle, isFavorite };
+}

From 9836002c43d7a2bb5d8499baa082cf0269391416 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Thu, 13 Aug 2026 19:04:02 +0300
Subject: [PATCH 045/116] (feat) improve dex view

---
 condor/web/routes/dex.py                      |  87 ++++++++
 .../src/components/dex/PoolSourceTabs.tsx     | 160 ++++++++++++--
 frontend/src/lib/api.ts                       |  17 ++
 frontend/src/pages/Dex.tsx                    |  91 ++++++--
 frontend/src/pages/DexPool.tsx                |  20 ++
 handlers/dex/pool_data.py                     | 207 ++++++++++++++++--
 tests/test_dex_pool_discovery.py              | 186 ++++++++++++++++
 7 files changed, 707 insertions(+), 61 deletions(-)

diff --git a/condor/web/routes/dex.py b/condor/web/routes/dex.py
index 2358741e..ccaadc04 100644
--- a/condor/web/routes/dex.py
+++ b/condor/web/routes/dex.py
@@ -13,6 +13,7 @@
 from __future__ import annotations
 
 import logging
+import re
 
 from fastapi import APIRouter, Depends, HTTPException, Query
 
@@ -31,6 +32,36 @@
 _ADDRESS_RE = dex_candles.ADDRESS_RE
 _POOL_ADDRESS_RE = _ADDRESS_RE
 
+# The chain the browser opens on, and the one it falls back to when Gateway cannot
+# be reached: Solana is where Condor's CLMM connectors (Meteora, Orca) live.
+DEFAULT_NETWORK = "solana-mainnet-beta"
+
+_TESTNET_RE = re.compile(r"(testnet|devnet|sepolia|goerli)", re.IGNORECASE)
+
+# Gateway names a network `chain-network`; the browser wants the part that varies.
+_CHAIN_LABELS = {
+    "solana-mainnet-beta": "Solana",
+    "ethereum-mainnet": "Ethereum",
+    "ethereum-base": "Base",
+    "ethereum-robinhoodchain": "Robinhood",
+    "ethereum-unichain": "Unichain",
+    "ethereum-arbitrum": "Arbitrum",
+    "ethereum-avalanche": "Avalanche",
+    "ethereum-bsc": "BNB Chain",
+    "ethereum-celo": "Celo",
+    "ethereum-optimism": "Optimism",
+    "ethereum-polygon": "Polygon",
+}
+
+
+def _chain_label(network_id: str, item: dict) -> str:
+    if network_id in _CHAIN_LABELS:
+        return _CHAIN_LABELS[network_id]
+    # An unmapped network is still perfectly browsable; title-case its own name
+    # rather than showing a raw id or dropping it.
+    name = str(item.get("network") or network_id).replace("-", " ").strip()
+    return name.title() or network_id
+
 
 @router.get("/servers/{name}/dex/pools")
 async def list_pools(
@@ -149,6 +180,62 @@ async def list_dexes(
     return {"dexes": await list_gecko_dexes(network)}
 
 
+@router.get("/servers/{name}/dex/chains")
+async def list_chains(
+    name: str,
+    user: WebUser = Depends(get_current_user),
+):
+    """The chains the pool browser can offer, from Gateway rather than a constant.
+
+    A chain qualifies only if it is both something *this* Gateway is configured for
+    and something GeckoTerminal indexes — a network Gateway reaches but Gecko does
+    not has no pools to browse, and one Gecko indexes but Gateway cannot reach
+    routes to a workspace that cannot trade. Testnets are dropped for the same
+    reason: there is nothing to discover on them.
+
+    Falls back to Solana alone when Gateway is unreachable, so the browser always
+    has at least the chain it defaults to.
+    """
+    cm = get_config_manager()
+    if not cm.has_server_access(user.id, name):
+        raise HTTPException(status_code=403, detail="No access")
+
+    from handlers.dex.pool_data import NETWORK_TO_GECKO
+
+    fallback = [{"network_id": DEFAULT_NETWORK, "chain": "solana", "label": "Solana"}]
+    try:
+        client = await cm.get_client(name)
+        result = await client.gateway.list_networks()
+    except Exception as e:
+        logger.warning("Gateway networks unavailable for %s: %s", name, e)
+        return {"chains": fallback}
+
+    raw = result.get("networks", result) if isinstance(result, dict) else result
+    chains = []
+    for item in raw if isinstance(raw, list) else []:
+        if not isinstance(item, dict):
+            continue
+        network_id = str(item.get("network_id") or "").strip()
+        if not network_id or network_id not in NETWORK_TO_GECKO:
+            continue
+        if _TESTNET_RE.search(network_id):
+            continue
+        chains.append(
+            {
+                "network_id": network_id,
+                "chain": str(item.get("chain") or ""),
+                "label": _chain_label(network_id, item),
+            }
+        )
+
+    if not chains:
+        return {"chains": fallback}
+    # Solana first — it is the default and the only chain with CLMM connectors
+    # behind it — then alphabetically, so the order does not shift with Gateway's.
+    chains.sort(key=lambda c: (c["network_id"] != DEFAULT_NETWORK, c["label"].lower()))
+    return {"chains": chains}
+
+
 @router.get("/servers/{name}/dex/pools-by-address")
 async def list_pools_by_address(
     name: str,
diff --git a/frontend/src/components/dex/PoolSourceTabs.tsx b/frontend/src/components/dex/PoolSourceTabs.tsx
index 956bc09e..33a05841 100644
--- a/frontend/src/components/dex/PoolSourceTabs.tsx
+++ b/frontend/src/components/dex/PoolSourceTabs.tsx
@@ -1,7 +1,7 @@
 import { Check, ChevronDown, Search, Star, X } from "lucide-react";
 import { useEffect, useMemo, useRef, useState } from "react";
 
-import type { DexVenue } from "@/lib/api";
+import type { DexChain, DexVenue } from "@/lib/api";
 
 /**
  * Which pool listing to browse. The upstreams take genuinely different arguments
@@ -21,12 +21,20 @@ export const GECKO_TABS = [
   { view: "token", label: "Search" },
 ] as const;
 
-/** The CLMM connectors Gateway can list pools for (and open positions in). */
+/**
+ * The CLMM connectors Gateway can list pools for (and open positions in).
+ *
+ * Both are Solana venues, so these tabs are hidden on any other chain: a Meteora
+ * tab on Base lists nothing and offers no position to open, which is worse than
+ * not offering it. GeckoTerminal browsing works on every chain either way.
+ */
 export const GATEWAY_TABS = [
   { connector: "meteora", label: "Meteora" },
   { connector: "orca", label: "Orca" },
 ] as const;
 
+export const GATEWAY_TAB_CHAIN = "solana";
+
 export function sameSource(a: PoolSource, b: PoolSource): boolean {
   if (a.kind === "gecko" && b.kind === "gecko") return a.view === b.view;
   if (a.kind === "gateway" && b.kind === "gateway")
@@ -34,17 +42,102 @@ export function sameSource(a: PoolSource, b: PoolSource): boolean {
   return a.kind === "favorites" && b.kind === "favorites";
 }
 
+/**
+ * Pills rather than underlined tabs, because there are seven of them and they no
+ * longer sit on one baseline: a wrapped underline reads as two broken rules across
+ * the header, while a pill is legible on whatever row it lands on.
+ */
 const TAB_BASE =
-  "px-3 py-1.5 text-xs font-medium transition-colors border-b-2 -mb-px whitespace-nowrap";
+  "rounded-md px-2.5 py-1 text-xs font-medium transition-colors whitespace-nowrap";
 
 function tabClass(active: boolean) {
   return `${TAB_BASE} ${
     active
-      ? "border-[var(--color-primary)] text-[var(--color-text)]"
-      : "border-transparent text-[var(--color-text-muted)] hover:text-[var(--color-text)]"
+      ? "bg-[var(--color-primary)]/15 text-[var(--color-primary)]"
+      : "text-[var(--color-text-muted)] hover:bg-[var(--color-surface-hover)] hover:text-[var(--color-text)]"
   }`;
 }
 
+/**
+ * The chain the browser is pointed at.
+ *
+ * Single-select, unlike the venue filter: a pool lives on exactly one chain, and
+ * every row's address, chart and executor is scoped to it, so "Solana and Base at
+ * once" is not a view the workspace behind a row could honour.
+ */
+function ChainSelect({
+  chains,
+  network,
+  onChange,
+}: {
+  chains: DexChain[];
+  network: string;
+  onChange: (next: string) => void;
+}) {
+  const [open, setOpen] = useState(false);
+  const ref = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    const handler = (e: MouseEvent) => {
+      if (ref.current && !ref.current.contains(e.target as Node)) setOpen(false);
+    };
+    const keyHandler = (e: KeyboardEvent) => {
+      if (e.key === "Escape") setOpen(false);
+    };
+    document.addEventListener("mousedown", handler);
+    document.addEventListener("keydown", keyHandler);
+    return () => {
+      document.removeEventListener("mousedown", handler);
+      document.removeEventListener("keydown", keyHandler);
+    };
+  }, []);
+
+  // One chain is not a choice — render it as a label rather than a dead dropdown.
+  if (chains.length <= 1) return null;
+
+  const current = chains.find((c) => c.network_id === network);
+
+  return (
+    <div ref={ref} className="relative">
+      <button
+        onClick={() => setOpen(!open)}
+        aria-expanded={open}
+        title="Chain to browse pools on"
+        className="flex items-center gap-1.5 rounded-md border border-[var(--color-border)] px-2 py-1 text-xs text-[var(--color-text)] transition-colors hover:bg-[var(--color-surface-hover)]"
+      >
+        {current?.label ?? network}
+        <ChevronDown
+          className={`h-3 w-3 transition-transform ${open ? "rotate-180" : ""}`}
+        />
+      </button>
+
+      {open && (
+        <div className="absolute left-0 top-full z-50 mt-1.5 w-44 rounded-lg border border-[var(--color-border)] bg-[var(--color-surface)] py-1 shadow-xl">
+          {chains.map((c) => (
+            <button
+              key={c.network_id}
+              onClick={() => {
+                onChange(c.network_id);
+                setOpen(false);
+              }}
+              className="flex w-full items-center gap-2 px-3 py-1.5 text-left text-xs transition-colors hover:bg-[var(--color-surface-hover)]"
+            >
+              <span
+                className={`h-1.5 w-1.5 shrink-0 rounded-full ${
+                  c.network_id === network
+                    ? "bg-[var(--color-primary)]"
+                    : "bg-transparent"
+                }`}
+              />
+              <span className="truncate">{c.label}</span>
+            </button>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+
 /**
  * The venue filter: "top pools, but only on these DEXes".
  *
@@ -189,6 +282,10 @@ function DexFilter({
 interface Props {
   source: PoolSource;
   onSourceChange: (s: PoolSource) => void;
+  /** The chains this Gateway can browse. One or none hides the selector. */
+  chains: DexChain[];
+  network: string;
+  onNetworkChange: (next: string) => void;
   /** The venues on this chain, for the filter. Empty hides it. */
   venues: DexVenue[];
   selectedDexes: string[];
@@ -201,6 +298,9 @@ interface Props {
 export function PoolSourceTabs({
   source,
   onSourceChange,
+  chains,
+  network,
+  onNetworkChange,
   venues,
   selectedDexes,
   onDexesChange,
@@ -214,10 +314,20 @@ export function PoolSourceTabs({
       ? "Filter pools by name…"
       : "Paste a pool or token address…";
   const searchShown = source.kind === "gateway" || isSearch;
+  const showGatewayTabs = network.startsWith(GATEWAY_TAB_CHAIN);
 
   return (
-    <div className="flex flex-wrap items-center gap-x-4 gap-y-2 border-b border-[var(--color-border)] px-4">
-      <div className="flex items-center overflow-x-auto">
+    <div className="flex flex-wrap items-center gap-x-4 gap-y-2 border-b border-[var(--color-border)] px-4 py-2">
+      {/* Wraps rather than scrolls. Seven short labels fit one row on any desktop
+          width, and on a phone a second row is reachable where a horizontal
+          scroller inside a vertically-scrolling page is largely not. */}
+      <ChainSelect
+        chains={chains}
+        network={network}
+        onChange={onNetworkChange}
+      />
+
+      <div className="flex flex-wrap items-center gap-0.5">
         {GECKO_TABS.map((t) => (
           <button
             key={t.view}
@@ -229,21 +339,25 @@ export function PoolSourceTabs({
             {t.label}
           </button>
         ))}
-        <span className="mx-2 h-4 w-px bg-[var(--color-border)]" />
-        {GATEWAY_TABS.map((t) => (
-          <button
-            key={t.connector}
-            onClick={() =>
-              onSourceChange({ kind: "gateway", connector: t.connector })
-            }
-            className={tabClass(
-              sameSource(source, { kind: "gateway", connector: t.connector }),
-            )}
-          >
-            {t.label}
-          </button>
-        ))}
-        <span className="mx-2 h-4 w-px bg-[var(--color-border)]" />
+        {showGatewayTabs && (
+          <>
+            <span className="mx-1.5 h-4 w-px bg-[var(--color-border)]" />
+            {GATEWAY_TABS.map((t) => (
+              <button
+                key={t.connector}
+                onClick={() =>
+                  onSourceChange({ kind: "gateway", connector: t.connector })
+                }
+                className={tabClass(
+                  sameSource(source, { kind: "gateway", connector: t.connector }),
+                )}
+              >
+                {t.label}
+              </button>
+            ))}
+          </>
+        )}
+        <span className="mx-1.5 h-4 w-px bg-[var(--color-border)]" />
         <button
           onClick={() => onSourceChange({ kind: "favorites" })}
           className={`${tabClass(source.kind === "favorites")} flex items-center gap-1`}
@@ -261,7 +375,7 @@ export function PoolSourceTabs({
         </button>
       </div>
 
-      <div className="ml-auto flex items-center gap-2 py-1.5">
+      <div className="ml-auto flex items-center gap-2">
         {source.kind === "gecko" && (
           <DexFilter
             venues={venues}
diff --git a/frontend/src/lib/api.ts b/frontend/src/lib/api.ts
index 976c16ba..c725a081 100644
--- a/frontend/src/lib/api.ts
+++ b/frontend/src/lib/api.ts
@@ -364,6 +364,13 @@ export interface DexVenue {
   name: string;
 }
 
+/** A chain the pool browser can browse, as Gateway names it. */
+export interface DexChain {
+  network_id: string;
+  chain: string;
+  label: string;
+}
+
 export interface DexPoolInfo {
   pool_address: string | null;
   dex_id: string | null;
@@ -1358,6 +1365,16 @@ export const api = {
     ).then((r) => ({ pools: r.pools ?? [], has_more: !!r.has_more }));
   },
 
+  /**
+   * The chains the pool browser can offer: the intersection of what this Gateway
+   * is configured for and what GeckoTerminal indexes. Asked of the server rather
+   * than hardcoded, so a chain the operator adds to Gateway shows up on its own.
+   */
+  getDexChains: (server: string) =>
+    apiFetch<{ chains: DexChain[] }>(
+      `/api/v1/servers/${encodeURIComponent(server)}/dex/chains`,
+    ).then((r) => r.chains ?? []),
+
   /** The venues a chain has, so the dex filter offers what exists, not a guess. */
   getDexVenues: (server: string, network: string) =>
     apiFetch<{ dexes: DexVenue[] }>(
diff --git a/frontend/src/pages/Dex.tsx b/frontend/src/pages/Dex.tsx
index 9aff0cea..6cfc8f00 100644
--- a/frontend/src/pages/Dex.tsx
+++ b/frontend/src/pages/Dex.tsx
@@ -19,15 +19,18 @@ const SEARCH_DEBOUNCE_MS = 400;
 const PAGE_SIZE = 20;
 
 /**
- * The one chain the browser offers, deliberately.
+ * The chain the browser opens on.
  *
- * Every other Gateway network is reachable by URL (`/dex/{network}/{address}`
- * still renders), but the venues Condor can actually LP in — Meteora, Orca —
- * are Solana's, so a chain picker offering chains with no CLMM connector behind
- * them sells a workspace that cannot open a position. One constant, so widening
- * this later is a list, not a rewrite.
+ * Solana rather than "whatever Gateway lists first", because it is the only chain
+ * with CLMM connectors (Meteora, Orca) behind it — so it is the one chain where a
+ * row leads all the way to an open position. The rest of the list comes from
+ * `/dex/chains`: Gateway's own networks, intersected with what GeckoTerminal
+ * indexes, since a chain missing from either has no pools to browse.
  */
-const NETWORK = "solana-mainnet-beta";
+const DEFAULT_NETWORK = "solana-mainnet-beta";
+
+/** Survives a reload, so the chain you browse is not re-picked on every visit. */
+const NETWORK_KEY = "condor.dex.network";
 
 /** An EVM address or a Solana pubkey — the same guard the backend applies. */
 const ADDRESS_RE = /^(0x[0-9a-fA-F]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$/;
@@ -48,6 +51,9 @@ export function Dex() {
     kind: "gecko",
     view: "trending",
   });
+  const [network, setNetwork] = useState<string>(
+    () => localStorage.getItem(NETWORK_KEY) || DEFAULT_NETWORK,
+  );
   const [dexes, setDexes] = useState<string[]>([]);
   const [query, setQuery] = useState("");
   const [debouncedQuery, setDebouncedQuery] = useState("");
@@ -64,14 +70,51 @@ export function Dex() {
   }, [query]);
 
   // Page 4 of Trending is not page 4 of anything else, and a stale page number
-  // would land the user on an empty table.
+  // would land the user on an empty table. Chain belongs here too: page 4 of
+  // Solana's trending is not page 4 of Base's.
   useEffect(() => {
     setPage(1);
-  }, [source, debouncedQuery, dexes]);
+  }, [source, debouncedQuery, dexes, network]);
+
+  useEffect(() => {
+    localStorage.setItem(NETWORK_KEY, network);
+  }, [network]);
+
+  const { data: chains = [] } = useQuery({
+    queryKey: ["dex-chains", server],
+    queryFn: () => api.getDexChains(server!),
+    enabled: !!server,
+    staleTime: 6 * 60 * 60 * 1000,
+  });
+
+  // A venue filter is a set of dex ids from the chain that was showing when it was
+  // picked, and those ids do not exist on the next one — carried over, it filters
+  // every row away and the chain looks empty.
+  const onNetworkChange = (next: string) => {
+    if (next === network) return;
+    setNetwork(next);
+    setDexes([]);
+    // Meteora and Orca are Solana connectors; their tabs disappear off Solana, and
+    // a selection left pointing at a hidden tab shows a table with no active tab.
+    if (!next.startsWith("solana")) {
+      setSource((s) => (s.kind === "gateway" ? { kind: "gecko", view: "trending" } : s));
+    }
+  };
+
+  // A chain that vanished from Gateway (or was never there — a stale localStorage
+  // value from another server) must not strand the browser on a chain the backend
+  // will not serve.
+  useEffect(() => {
+    if (!chains.length) return;
+    if (!chains.some((c) => c.network_id === network)) {
+      onNetworkChange(chains[0]?.network_id ?? DEFAULT_NETWORK);
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [chains, network]);
 
   const { data: venues = [] } = useQuery({
-    queryKey: ["dex-venues", server, NETWORK],
-    queryFn: () => api.getDexVenues(server!, NETWORK),
+    queryKey: ["dex-venues", server, network],
+    queryFn: () => api.getDexVenues(server!, network),
     enabled: !!server,
     staleTime: 6 * 60 * 60 * 1000,
   });
@@ -93,6 +136,7 @@ export function Dex() {
         : source.kind === "gateway"
           ? source.connector
           : "favorites",
+      network,
       debouncedQuery,
       dexes.join(","),
       page,
@@ -110,7 +154,7 @@ export function Dex() {
             }
           : {
               source: "gecko",
-              network: NETWORK,
+              network,
               view: source.kind === "gecko" ? source.view : "trending",
               query: isSearch ? debouncedQuery : undefined,
               dexes,
@@ -127,24 +171,24 @@ export function Dex() {
   // characters and nothing distinguishes them by shape, so the pool lookup runs
   // alongside the token search and whichever resolves is what the user meant.
   const { data: pastedPool } = useQuery({
-    queryKey: ["dex-pool-by-address", server, NETWORK, debouncedQuery],
+    queryKey: ["dex-pool-by-address", server, network, debouncedQuery],
     queryFn: () =>
       api
-        .getDexPoolByAddress(server!, debouncedQuery, NETWORK)
+        .getDexPoolByAddress(server!, debouncedQuery, network)
         .catch(() => null as PoolSummary | null),
     enabled: !!server && isSearch && isAddress,
     staleTime: POOL_STALE_MS,
   });
 
   const favoriteAddresses = useMemo(
-    () => favorites.filter((f) => f.network === NETWORK).map((f) => f.address),
-    [favorites],
+    () => favorites.filter((f) => f.network === network).map((f) => f.address),
+    [favorites, network],
   );
 
   const { data: favoritePools = [], isFetching: favoritesFetching } = useQuery({
-    queryKey: ["dex-favorites", server, NETWORK, favoriteAddresses.join(",")],
+    queryKey: ["dex-favorites", server, network, favoriteAddresses.join(",")],
     queryFn: () =>
-      api.getDexPoolsByAddress(server!, NETWORK, favoriteAddresses),
+      api.getDexPoolsByAddress(server!, network, favoriteAddresses),
     enabled:
       !!server && source.kind === "favorites" && !!favoriteAddresses.length,
     staleTime: POOL_STALE_MS,
@@ -175,8 +219,8 @@ export function Dex() {
       <div>
         <h1 className="text-lg font-semibold">DEX</h1>
         <p className="text-sm text-[var(--color-text-muted)]">
-          Solana pools Condor trades through Gateway. Open one to chart it, swap
-          in it and provide liquidity to it.
+          Pools Condor trades through Gateway. Open one to chart it, swap in it
+          and provide liquidity to it.
         </p>
       </div>
 
@@ -184,6 +228,9 @@ export function Dex() {
         <PoolSourceTabs
           source={source}
           onSourceChange={setSource}
+          chains={chains}
+          network={network}
+          onNetworkChange={onNetworkChange}
           venues={venues}
           selectedDexes={dexes}
           onDexesChange={setDexes}
@@ -198,7 +245,7 @@ export function Dex() {
           <button
             onClick={() =>
               navigate(
-                `/dex/${pastedPool.gateway_network || NETWORK}/${pastedPool.address}`,
+                `/dex/${pastedPool.gateway_network || network}/${pastedPool.address}`,
               )
             }
             className="flex w-full items-center justify-between border-b border-[var(--color-border)] bg-[var(--color-surface)] px-4 py-2.5 text-left transition-colors hover:bg-[var(--color-surface-hover)]"
@@ -225,7 +272,7 @@ export function Dex() {
           isLoading={loading}
           emptyMessage={emptyMessage}
           showGatewayColumns={source.kind === "gateway"}
-          network={NETWORK}
+          network={network}
           page={isFavorites ? 1 : page}
           hasMore={isFavorites ? false : !!pagedPools?.has_more}
           onPageChange={setPage}
diff --git a/frontend/src/pages/DexPool.tsx b/frontend/src/pages/DexPool.tsx
index 202594a0..287ed703 100644
--- a/frontend/src/pages/DexPool.tsx
+++ b/frontend/src/pages/DexPool.tsx
@@ -156,6 +156,25 @@ export function DexPool() {
   const active = tab === "lp" ? lpConfig : orderConfig;
   const currentPrice = pool?.current_price ?? null;
 
+  /**
+   * How many decimals the price axis shows.
+   *
+   * A CEX pair gets this from its trading rules, but a DEX pool has none — so it
+   * comes from the price itself. Without it lightweight-charts falls back to 2
+   * decimals, which renders a memecoin at 0.000312032 as a flat "0.00" axis with
+   * every candle stacked on one line.
+   *
+   * Held to ~5 significant digits: enough to separate ticks at any magnitude,
+   * short enough that a $150 pair does not get an axis of trailing zeros.
+   */
+  const pricePrecision = useMemo(() => {
+    if (!currentPrice || !Number.isFinite(currentPrice) || currentPrice <= 0) {
+      return undefined;
+    }
+    const leadingZeros = Math.ceil(-Math.log10(currentPrice));
+    return Math.min(12, Math.max(2, leadingZeros + 4));
+  }, [currentPrice]);
+
   const createMutation = useMutation({
     mutationFn: () => {
       if (!server) throw new Error("No server");
@@ -275,6 +294,7 @@ export function DexPool() {
               poolAddress={pool.address}
               interval={interval}
               lookbackSeconds={lookbackSeconds}
+              pricePrecision={pricePrecision}
               startPrice={active.chartProps.startPrice}
               endPrice={active.chartProps.endPrice}
               limitPrice={active.chartProps.limitPrice}
diff --git a/handlers/dex/pool_data.py b/handlers/dex/pool_data.py
index 370e1d89..d86d2f87 100644
--- a/handlers/dex/pool_data.py
+++ b/handlers/dex/pool_data.py
@@ -12,12 +12,14 @@
 functions rather than building GeckoTerminal URLs themselves.
 """
 
+import asyncio
 import logging
 import math
 import re
 import time
 from typing import Any, Dict, List, Optional, Tuple
 
+import httpx
 from geckoterminal_py import GeckoTerminalAsyncClient
 from geckoterminal_py import constants as GECKO_CONSTANTS
 from glom import glom
@@ -70,12 +72,31 @@
     "pancakeswap": "bsc",
 }
 
-# GeckoTerminal network mapping
+# GeckoTerminal network mapping.
+#
+# The keys are the network ids Gateway actually reports from ``/gateway/networks``
+# — ``chain-network``, so every EVM chain is ``ethereum-<network>``. That is not
+# cosmetic: the ids this table used to carry (``base-mainnet``, ``arbitrum-one``,
+# ``polygon-mainnet``) are ones Gateway never emits, so every EVM pool fell through
+# to "no gecko chain" and rendered as untradable. The older spellings are kept as
+# aliases because persisted preferences and Telegram flows still hold them.
 NETWORK_TO_GECKO = {
+    # Solana
     "solana": "solana",
     "solana-mainnet-beta": "solana",
+    # EVM, as Gateway names them
     "ethereum": "eth",
     "ethereum-mainnet": "eth",
+    "ethereum-arbitrum": "arbitrum",
+    "ethereum-avalanche": "avax",
+    "ethereum-base": "base",
+    "ethereum-bsc": "bsc",
+    "ethereum-celo": "celo",
+    "ethereum-optimism": "optimism",
+    "ethereum-polygon": "polygon_pos",
+    "ethereum-robinhoodchain": "robinhood",
+    "ethereum-unichain": "unichain",
+    # Legacy spellings still held by persisted preferences and Telegram flows.
     "arbitrum": "arbitrum",
     "arbitrum-one": "arbitrum",
     "base": "base",
@@ -84,7 +105,10 @@
     "binance-smart-chain": "bsc",
     "polygon": "polygon_pos",
     "polygon-mainnet": "polygon_pos",
-    "avalanche": "avalanche",
+    # Gecko's id for Avalanche is `avax`, not `avalanche` — the old value here
+    # matched no chain at all.
+    "avalanche": "avax",
+    "avalanche-mainnet": "avax",
     "optimism": "optimism",
     # Not a Gateway network: `xrpl` is a first-class Hummingbot connector (orders,
     # balances, order book) that CandlesFactory simply has no feed for. Its AMM
@@ -97,15 +121,22 @@
 # Telegram handler that used to own it because the pool browser's rows are routed
 # by it (``/dex/{gateway_network}/{address}``), and a gecko chain with no entry is
 # one Gateway cannot reach — a state to render, not an error.
+#
+# Every value must be a key of NETWORK_TO_GECKO, because `decorate_pool` decides
+# `tradable` by looking the result up there; a value that round-trips to nothing
+# marks a perfectly reachable chain untradable.
 GECKO_TO_GATEWAY_NETWORK = {
     "solana": "solana-mainnet-beta",
     "eth": "ethereum-mainnet",
-    "base": "base-mainnet",
-    "arbitrum": "arbitrum-one",
-    "bsc": "bsc-mainnet",
-    "polygon_pos": "polygon-mainnet",
-    "avalanche": "avalanche-mainnet",
-    "optimism": "optimism-mainnet",
+    "arbitrum": "ethereum-arbitrum",
+    "avax": "ethereum-avalanche",
+    "base": "ethereum-base",
+    "bsc": "ethereum-bsc",
+    "celo": "ethereum-celo",
+    "optimism": "ethereum-optimism",
+    "polygon_pos": "ethereum-polygon",
+    "robinhood": "ethereum-robinhoodchain",
+    "unichain": "ethereum-unichain",
 }
 
 # Networks whose venues quote *tickers* rather than token addresses. An XRPL token
@@ -220,9 +251,74 @@ def _gecko_client() -> GeckoTerminalAsyncClient:
     global _gecko_client_instance
     if _gecko_client_instance is None:
         _gecko_client_instance = GeckoTerminalAsyncClient()
+        # geckoterminal_py builds its httpx client with no timeout override, so a
+        # slow chain listing blocks for httpx's 5s default and then fails outright.
+        # A read timeout well above that is worth more than a fast empty table.
+        try:
+            _gecko_client_instance._client.timeout = httpx.Timeout(
+                _GECKO_TIMEOUT, connect=5.0
+            )
+        except Exception:  # pragma: no cover - a library layout change, not an error
+            logger.debug("could not set gecko client timeout", exc_info=True)
     return _gecko_client_instance
 
 
+# GeckoTerminal's free tier is ~30 requests/minute *per IP*, and that budget is
+# shared by every dashboard viewer, the candle poll loop and the pool browser at
+# once. Left unbounded, a single page load with a dex filter fans out to eight
+# concurrent requests and throttles the whole process; the semaphore turns that
+# burst into a queue.
+_GECKO_MAX_CONCURRENCY = 4
+_GECKO_TIMEOUT = 15.0
+_GECKO_RETRIES = 2
+_gecko_semaphore: Optional[asyncio.Semaphore] = None
+
+
+def _gecko_gate() -> asyncio.Semaphore:
+    """The concurrency gate, built lazily so it binds to the running loop."""
+    global _gecko_semaphore
+    if _gecko_semaphore is None:
+        _gecko_semaphore = asyncio.Semaphore(_GECKO_MAX_CONCURRENCY)
+    return _gecko_semaphore
+
+
+def _is_rate_limited(exc: BaseException) -> bool:
+    resp = getattr(exc, "response", None)
+    if resp is not None and getattr(resp, "status_code", None) == 429:
+        return True
+    return "429" in str(exc) or "rate limit" in str(exc).lower()
+
+
+async def gecko_request(method: str, path: str, **kwargs) -> Any:
+    """One GeckoTerminal call, gated and retried where retrying can help.
+
+    Only timeouts and transport errors are retried. A 429 is deliberately *not*:
+    gecko's limit is a per-minute window, so no backoff short enough to sit inside
+    a web request will clear it, and a retry only spends more of the very budget
+    that is exhausted — while making every other caller wait behind it. The answer
+    to a 429 is the stale cache the callers fall back to, and the semaphore above,
+    which stops the burst that causes it. A 404, or the 401 gecko answers past page
+    10, is a final answer and is raised on the first attempt.
+    """
+    for attempt in range(_GECKO_RETRIES + 1):
+        try:
+            async with _gecko_gate():
+                return await _gecko_client().api_request(method, path, **kwargs)
+        except Exception as e:  # noqa: BLE001 - re-raised below when not retryable
+            retryable = not _is_rate_limited(e) and isinstance(
+                e, (httpx.TimeoutException, httpx.TransportError)
+            )
+            if not retryable or attempt == _GECKO_RETRIES:
+                raise
+            await asyncio.sleep(_GECKO_BACKOFF[attempt])
+    raise RuntimeError("unreachable")
+
+
+# Backoff between retries of a *timeout*, which is a slow chain listing rather than
+# a throttled one — short, because a web request is waiting on it.
+_GECKO_BACKOFF = (0.4, 1.0)
+
+
 # ── Small TTL caches for token lookups ──
 # These answers are process-wide (not per-user) and tiny, so they live here rather
 # than in a caller's user_data. Capped so an unbounded stream of distinct mints
@@ -255,6 +351,36 @@ def _ttl_put(cache: dict, key: tuple, value: Any, ttl: float) -> None:
         cache.pop(next(iter(cache)))
 
 
+# ── Stale-tolerant cache, for upstreams that fail more often than they change ──
+# The rule everywhere else — never cache a failure — is right, but on its own it
+# turns every rate-limited request into an empty table: the browser asks, gecko
+# says 429, and the user sees "No pools found" for a chain with thousands. Pool
+# listings are ranked-by-volume snapshots, so a two-minute-old copy is a far better
+# answer than no answer, and these two helpers exist so a failed refresh can fall
+# back to one.
+#
+# Separate from _ttl_put because that one *sweeps* expired entries on every write,
+# which would throw away the very copies this fallback depends on.
+_STALE_MAX_AGE = 15 * 60
+
+
+def _stale_put(cache: dict, key: tuple, value: Any) -> None:
+    cache[key] = (time.time(), value)
+    now = time.time()
+    for k in [k for k, (ts, _) in cache.items() if now - ts >= _STALE_MAX_AGE]:
+        cache.pop(k, None)
+    while len(cache) > _TOKEN_CACHE_MAX:
+        cache.pop(next(iter(cache)))
+
+
+def _stale_get(cache: dict, key: tuple) -> Tuple[Optional[Any], float]:
+    """The cached value regardless of freshness, with its age in seconds."""
+    entry = cache.get(key)
+    if not entry:
+        return None, 0.0
+    return entry[1], time.time() - entry[0]
+
+
 async def fetch_token_symbol(mint: str, network: str) -> str:
     """Resolve a token mint/contract address to its ticker (e.g. ``Bonk``).
 
@@ -1063,6 +1189,7 @@ def extract_pair_from_name(name: str) -> Tuple[str, str]:
 _gecko_page_cache: Dict[Tuple, Tuple[float, List[Dict[str, Any]]]] = {}
 _gecko_dexes_cache: Dict[Tuple, Tuple[float, List[Dict[str, str]]]] = {}
 _gateway_pool_list_cache: Dict[Tuple, Tuple[float, List[Dict[str, Any]]]] = {}
+_multi_pool_cache: Dict[Tuple[str, str], Tuple[float, List[Dict[str, Any]]]] = {}
 _pool_by_address_cache: Dict[Tuple[str, str], Tuple[float, Dict[str, Any]]] = {}
 
 # A pool list is a browser page, not a report: cap what an upstream can be asked
@@ -1241,7 +1368,7 @@ async def _gecko_page_rows(
         path = _GECKO_VIEW_PATHS[view].format(gnet)
 
     try:
-        payload = await _gecko_client().api_request("GET", path, params={"page": page})
+        payload = await gecko_request("GET", path, params={"page": page})
         rows = [
             row
             for row in glom(payload, GECKO_CONSTANTS.POOL_SPEC)
@@ -1249,17 +1376,26 @@ async def _gecko_page_rows(
         ]
     except Exception as e:
         # Every rate-limit reply, and the 401 gecko answers past page 10.
+        # A stale copy beats an empty table: this listing is a ranked snapshot, so
+        # rows from a few minutes ago are still the answer to "what should I look
+        # at", while "No pools found" reads as a fact about the chain. The stale
+        # entry is returned but *not* refreshed, so the next request past the TTL
+        # tries upstream again rather than settling into serving old rows forever.
+        stale, age = _stale_get(_gecko_page_cache, key)
         logger.warning(
-            "gecko pool page failed net=%s view=%s dex=%s page=%s: %s",
+            "gecko pool page failed net=%s view=%s dex=%s page=%s: %s%s",
             gnet,
             view,
             dex or "-",
             page,
             e,
+            f" (serving {age:.0f}s-old cache)" if stale is not None else "",
         )
+        if stale is not None:
+            return [dict(row) for row in stale]
         return None
 
-    _ttl_put(_gecko_page_cache, key, rows, POOL_LIST_TTL)
+    _stale_put(_gecko_page_cache, key, rows)
     return [dict(row) for row in rows]
 
 
@@ -1402,6 +1538,17 @@ async def list_gecko_pools_page(
             break
 
     pools = collected[local_skip : local_skip + limit]
+
+    # Trending and New have no venue-scoped form upstream, so a dex filter on them
+    # is a scan of the chain-wide list — and a venue that simply has nothing
+    # trending right now then reads as a venue with no pools at all. It has pools;
+    # they are just not in *this* ranking. So ask the venue's own top listing
+    # instead of answering "none", which is the query the user meant by picking it.
+    if not pools and wanted:
+        scoped = await _scoped_top_page(gnet, network, sorted(wanted), limit, page)
+        if scoped["pools"]:
+            return scoped
+
     return {"pools": pools, "has_more": has_more and len(pools) == limit}
 
 
@@ -1431,13 +1578,21 @@ async def list_gecko_dexes(network: str) -> List[Dict[str, str]]:
         return [dict(row) for row in cached]
 
     try:
-        payload = await _gecko_client().api_request(
+        payload = await gecko_request(
             "GET", GECKO_CONSTANTS.GET_DEXES_BY_NETWORK_PATH.format(gnet)
         )
         rows = glom(payload, GECKO_CONSTANTS.DEXES_BY_NETWORK_SPEC)
     except Exception as e:
-        logger.warning("gecko dex list failed net=%s: %s", gnet, e)
-        return []
+        # A chain's venue list changes about never, so a stale copy is as good as a
+        # fresh one — and losing it makes the filter vanish from the browser.
+        stale, age = _stale_get(_gecko_dexes_cache, (gnet,))
+        logger.warning(
+            "gecko dex list failed net=%s: %s%s",
+            gnet,
+            e,
+            f" (serving {age:.0f}s-old cache)" if stale is not None else "",
+        )
+        return [dict(row) for row in stale] if stale is not None else []
 
     dexes = [
         {"id": str(row["id"]), "name": str(row.get("name") or row["id"])}
@@ -1473,14 +1628,32 @@ async def fetch_pools_by_addresses(
     if not seen:
         return []
 
+    # The favourites view re-reads every starred pool on every visit, and this was
+    # the one listing with no cache at all — a tab switch back and forth spent the
+    # chain listing's rate-limit budget. Keyed by the batch, so it collides with
+    # itself the way the other pool caches do.
     pools: List[Dict[str, Any]] = []
     for start in range(0, len(seen), _GECKO_MULTI_MAX):
         batch = seen[start : start + _GECKO_MULTI_MAX]
+        batch_key = (gnet, ",".join(batch))
+        cached = _ttl_get(_multi_pool_cache, batch_key, POOL_LIST_TTL)
+        if cached is not None:
+            pools.extend(dict(row) for row in cached)
+            continue
         try:
             result = await _gecko_client().get_multiple_pools_by_network(gnet, batch)
         except Exception as e:
-            logger.warning("gecko multi-pool failed net=%s: %s", gnet, e)
+            stale, age = _stale_get(_multi_pool_cache, batch_key)
+            logger.warning(
+                "gecko multi-pool failed net=%s: %s%s",
+                gnet,
+                e,
+                f" (serving {age:.0f}s-old cache)" if stale is not None else "",
+            )
+            if stale is not None:
+                pools.extend(dict(row) for row in stale)
             continue
+        batch_pools: List[Dict[str, Any]] = []
         for row in _coerce_pool_rows(result, len(batch)):
             try:
                 pool = _normalize_gecko_pool(row, network)
@@ -1488,7 +1661,9 @@ async def fetch_pools_by_addresses(
                 logger.info("gecko pool row skipped net=%s: %s", gnet, e)
                 continue
             if pool.get("address"):
-                pools.append(pool)
+                batch_pools.append(pool)
+        _stale_put(_multi_pool_cache, batch_key, batch_pools)
+        pools.extend(dict(row) for row in batch_pools)
 
     # In the order the caller saved them, not the order gecko answers in.
     rank = {address: i for i, address in enumerate(seen)}
diff --git a/tests/test_dex_pool_discovery.py b/tests/test_dex_pool_discovery.py
index c7275a1d..7e610ddf 100644
--- a/tests/test_dex_pool_discovery.py
+++ b/tests/test_dex_pool_discovery.py
@@ -35,6 +35,7 @@ def _clear_caches():
         pool_data._gecko_dexes_cache,
         pool_data._gateway_pool_list_cache,
         pool_data._pool_by_address_cache,
+        pool_data._multi_pool_cache,
     ):
         cache.clear()
     yield
@@ -890,3 +891,188 @@ def test_a_first_page_failure_is_still_empty(paged_gecko):
     client.fail_from = 1
     result = run(pool_data.list_gecko_pools_page("solana", dexes=["meteora"]))
     assert result == {"pools": [], "has_more": False}
+
+
+# ── surviving a throttled upstream ──
+#
+# GeckoTerminal's free tier is ~30 requests a minute per IP, shared by every viewer,
+# the candle poll loop and this browser at once — so a 429 is a routine event, not
+# an exceptional one. What it must never produce is "No pools found", which reads as
+# a fact about the chain rather than about the request.
+
+
+def test_a_throttled_refresh_serves_the_last_good_rows(paged_gecko):
+    """A 429 falls back to the cached copy instead of emptying the table."""
+    client = paged_gecko({1: _rows(20)})
+    first = run(pool_data.list_gecko_pools_page("solana", limit=20, page=1))
+    assert len(first["pools"]) == 20
+
+    # Past the TTL, so the next call really does go upstream — and is throttled.
+    for key in list(pool_data._gecko_page_cache):
+        rows = pool_data._gecko_page_cache[key][1]
+        pool_data._gecko_page_cache[key] = (0.0, rows)
+    client.fail_from = 1
+
+    again = run(pool_data.list_gecko_pools_page("solana", limit=20, page=1))
+    assert [p["address"] for p in again["pools"]] == [
+        p["address"] for p in first["pools"]
+    ], "a throttled refresh must answer with the stale rows, not an empty table"
+
+
+def test_a_throttled_first_request_is_still_empty(paged_gecko):
+    """With nothing cached there is nothing to fall back to — and no invention."""
+    client = paged_gecko({1: _rows(20)})
+    client.fail_from = 1
+    result = run(pool_data.list_gecko_pools_page("solana", limit=20, page=1))
+    assert result == {"pools": [], "has_more": False}
+
+
+def test_a_rate_limit_is_not_retried(paged_gecko):
+    """Backoff cannot clear a per-minute window; retrying only spends more of it."""
+    client = paged_gecko({1: _rows(20)})
+    client.fail_from = 1
+    run(pool_data.list_gecko_pools_page("solana", limit=20, page=1))
+    assert client.pages == [1], "a 429 is a final answer, not something to retry"
+
+
+def test_a_venue_with_nothing_trending_falls_back_to_its_own_listing(paged_gecko):
+    """Filtering Trending by a venue that is not in it must not answer 'no pools'.
+
+    The venue has pools; they are simply not in *this* ranking. The scoped listing
+    is the query the user meant by picking it.
+    """
+    client = paged_gecko({1: _rows(20, dex_id="pumpswap")})
+    result = run(
+        pool_data.list_gecko_pools_page(
+            "solana", view="trending", limit=20, dexes=["orca"]
+        )
+    )
+    assert result["pools"], "a venue-scoped retry should have found rows"
+    assert "orca" in client.scopes, "the fallback must ask for the venue's own listing"
+
+
+# ── the network ids Gateway actually reports ──
+
+
+@pytest.mark.parametrize(
+    "gateway_network, gecko_chain",
+    [
+        ("solana-mainnet-beta", "solana"),
+        ("ethereum-mainnet", "eth"),
+        ("ethereum-base", "base"),
+        ("ethereum-robinhoodchain", "robinhood"),
+        ("ethereum-unichain", "unichain"),
+        ("ethereum-avalanche", "avax"),
+        ("ethereum-polygon", "polygon_pos"),
+    ],
+)
+def test_gateway_network_ids_map_to_a_gecko_chain(gateway_network, gecko_chain):
+    """Gateway names networks `chain-network`; this table has to speak that.
+
+    It previously held ids Gateway never emits (``base-mainnet``, ``arbitrum-one``),
+    so every EVM pool fell through to "no gecko chain" and rendered untradable.
+    """
+    assert pool_data.get_gecko_network(gateway_network) == gecko_chain
+
+
+def test_every_discovered_chain_round_trips_back_to_a_known_network():
+    """`decorate_pool` marks a pool tradable by looking its network up again.
+
+    A value that does not round-trip marks a perfectly reachable chain untradable —
+    which is what used to happen to BSC, Avalanche and Optimism.
+    """
+    for chain, network in pool_data.GECKO_TO_GATEWAY_NETWORK.items():
+        assert (
+            network in pool_data.NETWORK_TO_GECKO
+        ), f"{chain} -> {network} is a dead end"
+        assert pool_data.NETWORK_TO_GECKO[network] == chain
+
+
+# ── the chains the browser may offer ──
+
+
+class FakeGatewayNetworks:
+    """Gateway's `/gateway/networks`, which names networks `chain-network`."""
+
+    def __init__(self, networks=None, error=None):
+        self._networks = networks
+        self._error = error
+
+    async def list_networks(self):
+        if self._error:
+            raise self._error
+        return {"networks": self._networks}
+
+
+class FakeNetworkClient:
+    def __init__(self, gateway):
+        self.gateway = gateway
+
+
+def _net(network_id, chain, network):
+    return {"network_id": network_id, "chain": chain, "network": network}
+
+
+def _chains_client(route_client, networks=None, error=None):
+    gateway = FakeGatewayNetworks(networks, error)
+    return route_client(client=FakeNetworkClient(gateway))
+
+
+def test_chains_offers_what_gateway_has_and_gecko_indexes(route_client):
+    client = _chains_client(
+        route_client,
+        [
+            _net("solana-mainnet-beta", "solana", "mainnet-beta"),
+            _net("ethereum-base", "ethereum", "base"),
+            _net("ethereum-robinhoodchain", "ethereum", "robinhoodchain"),
+        ],
+    )
+    chains = client.get("/servers/srv/dex/chains").json()["chains"]
+    assert [c["network_id"] for c in chains] == [
+        "solana-mainnet-beta",
+        "ethereum-base",
+        "ethereum-robinhoodchain",
+    ], "Solana leads because it is the default; the rest sort by label"
+    assert [c["label"] for c in chains] == ["Solana", "Base", "Robinhood"]
+
+
+def test_chains_drops_testnets(route_client):
+    """There is nothing to discover on a testnet — Gecko does not index one."""
+    client = _chains_client(
+        route_client,
+        [
+            _net("solana-mainnet-beta", "solana", "mainnet-beta"),
+            _net("solana-devnet", "solana", "devnet"),
+            _net("ethereum-sepolia", "ethereum", "sepolia"),
+            _net(
+                "ethereum-robinhoodchain-testnet", "ethereum", "robinhoodchain-testnet"
+            ),
+        ],
+    )
+    chains = client.get("/servers/srv/dex/chains").json()["chains"]
+    assert [c["network_id"] for c in chains] == ["solana-mainnet-beta"]
+
+
+def test_chains_drops_networks_gecko_cannot_index(route_client):
+    client = _chains_client(
+        route_client,
+        [
+            _net("solana-mainnet-beta", "solana", "mainnet-beta"),
+            _net("ethereum-madeupchain", "ethereum", "madeupchain"),
+        ],
+    )
+    chains = client.get("/servers/srv/dex/chains").json()["chains"]
+    assert [c["network_id"] for c in chains] == ["solana-mainnet-beta"]
+
+
+def test_chains_falls_back_to_solana_when_gateway_is_down(route_client):
+    """The browser must always have at least the chain it defaults to."""
+    client = _chains_client(route_client, error=RuntimeError("gateway is down"))
+    r = client.get("/servers/srv/dex/chains")
+    assert r.status_code == 200
+    assert [c["network_id"] for c in r.json()["chains"]] == ["solana-mainnet-beta"]
+
+
+def test_chains_needs_server_access(route_client):
+    client = route_client(allowed=False)
+    assert client.get("/servers/srv/dex/chains").status_code == 403

From f3528e6aca8d0e1c132987761beaef1497c15487 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Thu, 13 Aug 2026 19:18:55 +0300
Subject: [PATCH 046/116] (feat) render ```chart fences as interactive charts
 in the webchat
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The chat bubble already renders GFM through react-markdown, which is the only
reason tables work there. A ```chart fence now goes through the same door: a
`pre` override hands its JSON to a recharts ComposedChart, so streaming, WS
frames, durable conversations and history replay never learn charts exist —
the chart is just text.

Every failure path degrades to the code block a consumer without the renderer
would have shown: unparseable while streaming shows a quiet placeholder,
unparseable after the turn shows the raw fence, and a recharts crash is caught
by a local boundary instead of taking down the message list.

Series colors are new --chart-series-1..4 tokens, one set per theme, validated
for CVD separation, lightness band and contrast against each surface — so a
theme switch recolors live with no chart code involved. A chart-bearing bubble
claims the whole chat column: a plot squeezed into the width of the sentence
above it is unreadable.
---
 frontend/src/components/chat/ChartBlock.tsx  | 351 +++++++++++++++++++
 frontend/src/components/chat/ChatMessage.tsx |  61 +++-
 frontend/src/index.css                       |  21 ++
 3 files changed, 427 insertions(+), 6 deletions(-)
 create mode 100644 frontend/src/components/chat/ChartBlock.tsx

diff --git a/frontend/src/components/chat/ChartBlock.tsx b/frontend/src/components/chat/ChartBlock.tsx
new file mode 100644
index 00000000..45f3395c
--- /dev/null
+++ b/frontend/src/components/chat/ChartBlock.tsx
@@ -0,0 +1,351 @@
+// ── Interactive charts inside a chat bubble ──
+//
+// The agent draws by writing a ```chart fence with a small JSON spec, exactly
+// the way it writes a table: the chart rides the ordinary text channel, so
+// streaming, persistence and history replay never learn it exists. Anything
+// that cannot render the fence (Telegram, transcript views) still shows a
+// readable code block, which is why every failure path here degrades to <pre>
+// rather than to nothing.
+
+import { Component, type ReactNode } from "react";
+import { Loader2 } from "lucide-react";
+import {
+  Area,
+  Bar,
+  CartesianGrid,
+  ComposedChart,
+  Legend,
+  Line,
+  ResponsiveContainer,
+  Tooltip,
+  XAxis,
+  YAxis,
+} from "recharts";
+
+// ── Spec ──
+
+const CHART_TYPES = ["line", "area", "bar"] as const;
+type ChartType = (typeof CHART_TYPES)[number];
+
+/** Tolerant caps: a spec over them is sliced, never rejected. */
+const MAX_ROWS = 200;
+const MAX_SERIES = 4;
+
+interface ChartSeries {
+  key: string;
+  name: string;
+  color: string;
+}
+
+interface ChartSpec {
+  type: ChartType;
+  title: string;
+  x: string;
+  series: ChartSeries[];
+  data: Record<string, unknown>[];
+}
+
+// Named colors the agent may ask for by meaning rather than by hex. Everything
+// else falls through to the fixed categorical order, which is the only way a
+// series keeps its color when a chart gains or loses one.
+const NAMED_COLORS: Record<string, string> = {
+  up: "var(--chart-up)",
+  down: "var(--chart-down)",
+  green: "var(--color-green)",
+  red: "var(--color-red)",
+  yellow: "var(--color-yellow)",
+  accent: "var(--color-accent)",
+};
+
+const SERIES_PALETTE = [
+  "var(--chart-series-1)",
+  "var(--chart-series-2)",
+  "var(--chart-series-3)",
+  "var(--chart-series-4)",
+];
+
+function seriesColor(raw: unknown, index: number): string {
+  if (typeof raw === "string" && raw.trim()) {
+    const named = NAMED_COLORS[raw.trim().toLowerCase()];
+    if (named) return named;
+    // A literal CSS color the model wrote itself. Kept, but only if it cannot
+    // smuggle anything into the style attribute.
+    if (/^(#[0-9a-f]{3,8}|[a-z]+)$/i.test(raw.trim())) return raw.trim();
+  }
+  return SERIES_PALETTE[index % SERIES_PALETTE.length];
+}
+
+/**
+ * Read a spec out of a fence body, or null if it is not one (yet).
+ *
+ * Null is the honest answer for both a half-streamed fence and a malformed
+ * one; the caller decides which of the two it is from `live`.
+ */
+function parseChartSpec(raw: string): ChartSpec | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+
+  const spec = parsed as Record<string, unknown>;
+  const type = String(spec.type ?? "line").toLowerCase() as ChartType;
+  if (!CHART_TYPES.includes(type)) return null;
+
+  const x = typeof spec.x === "string" ? spec.x : "";
+  if (!x) return null;
+
+  if (!Array.isArray(spec.series) || !Array.isArray(spec.data)) return null;
+
+  const series: ChartSeries[] = [];
+  for (const entry of spec.series) {
+    if (!entry || typeof entry !== "object") continue;
+    const s = entry as Record<string, unknown>;
+    const key = typeof s.key === "string" ? s.key : "";
+    if (!key) continue;
+    series.push({
+      key,
+      name: typeof s.name === "string" && s.name ? s.name : key,
+      color: seriesColor(s.color, series.length),
+    });
+    if (series.length === MAX_SERIES) break;
+  }
+  if (series.length === 0) return null;
+
+  const data = spec.data
+    .filter((row): row is Record<string, unknown> => !!row && typeof row === "object")
+    .slice(0, MAX_ROWS);
+  if (data.length === 0) return null;
+
+  return {
+    type,
+    title: typeof spec.title === "string" ? spec.title : "",
+    x,
+    series,
+    data,
+  };
+}
+
+// ── Rendering ──
+
+/** Axis ticks: enough digits to be read, few enough to fit a chat bubble. */
+function formatTick(value: unknown): string {
+  if (typeof value !== "number" || !Number.isFinite(value)) return String(value ?? "");
+  const abs = Math.abs(value);
+  if (abs >= 1_000_000) return `${(value / 1_000_000).toFixed(1)}M`;
+  if (abs >= 1_000) return `${(value / 1_000).toFixed(1)}K`;
+  if (abs >= 100) return value.toFixed(0);
+  if (abs >= 1) return value.toFixed(2);
+  return value.toPrecision(3);
+}
+
+function formatValue(value: unknown): string {
+  if (typeof value !== "number" || !Number.isFinite(value)) return String(value ?? "—");
+  const abs = Math.abs(value);
+  const decimals = abs >= 1000 ? 2 : abs >= 1 ? 4 : 6;
+  return value.toLocaleString(undefined, { maximumFractionDigits: decimals });
+}
+
+interface TooltipEntry {
+  dataKey?: string | number;
+  name?: string | number;
+  value?: unknown;
+  color?: string;
+}
+
+function ChartTooltip({
+  active,
+  payload,
+  label,
+}: {
+  active?: boolean;
+  payload?: TooltipEntry[];
+  label?: unknown;
+}) {
+  if (!active || !payload?.length) return null;
+  return (
+    <div className="rounded-md border border-[var(--color-border)] bg-[var(--color-bg)]/95 px-2.5 py-2 text-[11px] leading-relaxed shadow-lg backdrop-blur-sm">
+      <div className="mb-1 text-[10px] text-[var(--color-text-muted)]">{String(label ?? "")}</div>
+      {payload.map((entry, i) => (
+        <div key={i} className="flex items-center justify-between gap-3">
+          <span className="flex items-center gap-1.5 text-[var(--color-text-muted)]">
+            <span
+              className="h-1.5 w-1.5 shrink-0 rounded-full"
+              style={{ background: entry.color }}
+            />
+            {String(entry.name ?? entry.dataKey ?? "")}
+          </span>
+          <span className="font-medium tabular-nums text-[var(--color-text)]">
+            {formatValue(entry.value)}
+          </span>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+/** The unparseable fence, rendered as what it textually is. */
+function RawFence({ raw }: { raw: string }) {
+  return (
+    <pre>
+      <code className="language-chart">{raw}</code>
+    </pre>
+  );
+}
+
+function Chart({ spec }: { spec: ChartSpec }) {
+  const { type, series } = spec;
+
+  return (
+    <div className="my-2 overflow-hidden rounded-lg border border-[var(--color-border)] bg-[var(--color-surface)]">
+      {spec.title && (
+        <div className="border-b border-[var(--color-border)] bg-[var(--color-bg)] px-3 py-1.5">
+          <p className="text-[10px] font-bold uppercase tracking-widest text-[var(--color-text-muted)]">
+            {spec.title}
+          </p>
+        </div>
+      )}
+      <div className="px-1 py-1">
+        <ResponsiveContainer width="100%" height={240}>
+          <ComposedChart
+            data={spec.data}
+            margin={{ top: 12, right: 12, left: 0, bottom: 0 }}
+            barCategoryGap="20%"
+          >
+            <defs>
+              {series.map((s, i) => (
+                <linearGradient key={s.key} id={`chartGrad-${i}`} x1="0" y1="0" x2="0" y2="1">
+                  <stop offset="5%" stopColor={s.color} stopOpacity={0.25} />
+                  <stop offset="95%" stopColor={s.color} stopOpacity={0.02} />
+                </linearGradient>
+              ))}
+            </defs>
+            <CartesianGrid strokeDasharray="3 3" stroke="var(--color-border)" strokeOpacity={0.5} />
+            <XAxis
+              dataKey={spec.x}
+              tick={{ fontSize: 10, fill: "var(--color-text-muted)" }}
+              stroke="var(--color-border)"
+              tickLine={false}
+              minTickGap={24}
+            />
+            <YAxis
+              // A bar is read against zero, so its axis has to start there. A
+              // price or PnL line is read for its shape, and anchoring that at
+              // zero is what flattens a day of trading into a straight line.
+              domain={type === "bar" ? [0, "auto"] : ["auto", "auto"]}
+              tickFormatter={formatTick}
+              tick={{ fontSize: 10, fill: "var(--color-text-muted)" }}
+              stroke="var(--color-border)"
+              tickLine={false}
+              axisLine={false}
+              width={52}
+            />
+            <Tooltip content={<ChartTooltip />} cursor={{ stroke: "var(--color-border)" }} />
+            {series.map((s, i) =>
+              type === "bar" ? (
+                <Bar
+                  key={s.key}
+                  dataKey={s.key}
+                  name={s.name}
+                  fill={s.color}
+                  radius={[4, 4, 0, 0]}
+                  maxBarSize={48}
+                />
+              ) : type === "area" ? (
+                <Area
+                  key={s.key}
+                  type="monotone"
+                  dataKey={s.key}
+                  name={s.name}
+                  stroke={s.color}
+                  strokeWidth={2}
+                  fill={`url(#chartGrad-${i})`}
+                  dot={false}
+                />
+              ) : (
+                <Line
+                  key={s.key}
+                  type="monotone"
+                  dataKey={s.key}
+                  name={s.name}
+                  stroke={s.color}
+                  strokeWidth={2}
+                  dot={false}
+                />
+              )
+            )}
+            {/* One series is named by the title and the axis; a legend box
+                would only repeat it. Two or more must never be told apart by
+                color alone. */}
+            {series.length > 1 && (
+              <Legend
+                verticalAlign="top"
+                align="right"
+                iconType={type === "bar" ? "square" : "plainline"}
+                wrapperStyle={{ fontSize: 10, paddingBottom: 4 }}
+                formatter={(value: string) => (
+                  <span className="text-[10px] text-[var(--color-text-muted)]">{value}</span>
+                )}
+              />
+            )}
+          </ComposedChart>
+        </ResponsiveContainer>
+      </div>
+    </div>
+  );
+}
+
+/**
+ * A recharts crash is a rendering detail of one bubble, never a reason for the
+ * message list to disappear. The fallback is the same code block a consumer
+ * without this component would have shown.
+ */
+class ChartErrorBoundary extends Component<{ raw: string; children: ReactNode }, { failed: boolean }> {
+  state = { failed: false };
+
+  static getDerivedStateFromError() {
+    return { failed: true };
+  }
+
+  componentDidCatch(error: Error) {
+    console.error("[ChartBlock]", error);
+  }
+
+  render() {
+    if (this.state.failed) return <RawFence raw={this.props.raw} />;
+    return this.props.children;
+  }
+}
+
+/**
+ * The ```chart fence, rendered.
+ *
+ * While the answer is still streaming, an unparseable body is simply a fence
+ * whose JSON has not finished arriving — showing raw braces that flash and
+ * rearrange for a second is worse than a quiet placeholder. Once the turn is
+ * over the same failure is a real malformed spec, and then the honest render
+ * is the text the model actually wrote.
+ */
+export function ChartBlock({ raw, live }: { raw: string; live: boolean }) {
+  const spec = parseChartSpec(raw);
+
+  if (!spec) {
+    if (live) {
+      return (
+        <div className="my-2 flex items-center gap-1.5 rounded-lg border border-dashed border-[var(--color-border)] px-3 py-2 text-xs text-[var(--color-text-muted)]">
+          <Loader2 className="h-3 w-3 animate-spin" />
+          Rendering chart...
+        </div>
+      );
+    }
+    return <RawFence raw={raw} />;
+  }
+
+  return (
+    <ChartErrorBoundary raw={raw}>
+      <Chart spec={spec} />
+    </ChartErrorBoundary>
+  );
+}
diff --git a/frontend/src/components/chat/ChatMessage.tsx b/frontend/src/components/chat/ChatMessage.tsx
index e1541b5e..acb2176f 100644
--- a/frontend/src/components/chat/ChatMessage.tsx
+++ b/frontend/src/components/chat/ChatMessage.tsx
@@ -1,11 +1,48 @@
-import { memo } from "react";
-import ReactMarkdown from "react-markdown";
+import { isValidElement, memo, type ReactNode } from "react";
+import ReactMarkdown, { type Components } from "react-markdown";
 import remarkGfm from "remark-gfm";
 import { ChevronDown, ChevronRight, Loader2, Square, User, Bot } from "lucide-react";
 import type { ChatMessage as ChatMessageType } from "@/hooks/useChatSocket";
 import { useLiveDisclosure } from "@/hooks/useLiveDisclosure";
+import { ChartBlock } from "./ChartBlock";
 import { ToolCallStatus } from "./ToolCallStatus";
 
+/** Flatten a fence's children back into the source text it was parsed from. */
+function fenceText(children: ReactNode): string {
+  if (typeof children === "string") return children;
+  if (Array.isArray(children)) return children.map(fenceText).join("");
+  return "";
+}
+
+/**
+ * What the markdown pipeline can render, beyond markdown.
+ *
+ * A ```chart fence becomes a real chart; every other fence stays the code
+ * block it already was. The override sits on `pre` rather than on `code`
+ * because react-markdown v10 dropped the `inline` prop and still wraps fences
+ * in a <pre> — replacing the wrapper is what keeps the chart out of a
+ * whitespace-preserving box it was never meant to live in.
+ */
+function markdownComponents(live: boolean): Components {
+  return {
+    pre({ children, ...props }) {
+      const child = Array.isArray(children) ? children[0] : children;
+      if (isValidElement<{ className?: string; children?: ReactNode }>(child)) {
+        const className = child.props.className ?? "";
+        if (className.split(" ").includes("language-chart")) {
+          return <ChartBlock raw={fenceText(child.props.children)} live={live} />;
+        }
+      }
+      return <pre {...props}>{children}</pre>;
+    },
+  };
+}
+
+// Both variants are built once: a fresh `components` object per render would
+// remount every block in the bubble on each streamed chunk.
+const LIVE_COMPONENTS = markdownComponents(true);
+const STATIC_COMPONENTS = markdownComponents(false);
+
 function ThoughtBlock({ text, live }: { text: string; live: boolean }) {
   const { expanded, toggle } = useLiveDisclosure(live);
 
@@ -70,7 +107,9 @@ export const ChatMessageView = memo(function ChatMessageView({
     return (
       <div className="my-3 flex justify-start">
         <div className="chat-markdown max-w-[85%] rounded-xl border border-dashed border-[var(--color-border)] px-3.5 py-2 text-sm text-[var(--color-text-muted)]">
-          <ReactMarkdown remarkPlugins={[remarkGfm]}>{message.text}</ReactMarkdown>
+          <ReactMarkdown remarkPlugins={[remarkGfm]} components={STATIC_COMPONENTS}>
+            {message.text}
+          </ReactMarkdown>
         </div>
       </div>
     );
@@ -106,13 +145,18 @@ export const ChatMessageView = memo(function ChatMessageView({
     );
   }
 
+  // A bubble that shrink-wraps its text is right for prose and wrong for a
+  // chart: a plot squeezed into the width of the sentence above it is
+  // unreadable. A chart-bearing answer claims the whole chat column instead.
+  const hasChart = message.text.includes("```chart");
+
   return (
     <div className="flex justify-start mb-3">
-      <div className="flex items-start gap-2 max-w-[85%]">
+      <div className={`flex items-start gap-2 ${hasChart ? "w-full" : "max-w-[85%]"}`}>
         <div className="mt-0.5 flex h-6 w-6 shrink-0 items-center justify-center rounded-full bg-[var(--color-accent)]/20">
           <Bot className="h-3.5 w-3.5 text-[var(--color-accent)]" />
         </div>
-        <div className="min-w-0">
+        <div className={`min-w-0 ${hasChart ? "flex-1" : ""}`}>
           {/* The thought is the live thing only until the answer starts
               landing in this same bubble. Keying the collapse on `text` too
               means a lost `prompt_done` cannot leave it stuck open. */}
@@ -120,7 +164,12 @@ export const ChatMessageView = memo(function ChatMessageView({
           <ToolCallStatus toolCalls={message.toolCalls} live={live} />
           {message.text && (
             <div className="chat-markdown rounded-2xl rounded-tl-sm bg-[var(--color-surface-hover)] px-3.5 py-2 text-sm">
-              <ReactMarkdown remarkPlugins={[remarkGfm]}>{message.text}</ReactMarkdown>
+              <ReactMarkdown
+                remarkPlugins={[remarkGfm]}
+                components={live ? LIVE_COMPONENTS : STATIC_COMPONENTS}
+              >
+                {message.text}
+              </ReactMarkdown>
             </div>
           )}
           {!message.text && message.toolCalls.length === 0 && !message.thought && (
diff --git a/frontend/src/index.css b/frontend/src/index.css
index b3ab8dd8..e1b3ffc4 100644
--- a/frontend/src/index.css
+++ b/frontend/src/index.css
@@ -24,6 +24,14 @@
   --chart-up: #22c55e;
   --chart-down: #ef4444;
 
+  /* Categorical series, fixed order (chat charts). Validated for CVD
+     separation, lightness band and contrast against --chart-bg — never
+     reordered, never extended by generating a hue. */
+  --chart-series-1: #3f9ae0;
+  --chart-series-2: #c98200;
+  --chart-series-3: #8a5fd6;
+  --chart-series-4: #0e9e6a;
+
   color-scheme: dark;
 }
 
@@ -50,6 +58,12 @@
   --chart-up: #16a34a;
   --chart-down: #dc2626;
 
+  /* Categorical series, fixed order (chat charts) — light steps. */
+  --chart-series-1: #0072b2;
+  --chart-series-2: #d55e00;
+  --chart-series-3: #7d4dd6;
+  --chart-series-4: #009e73;
+
   color-scheme: light;
 }
 
@@ -76,6 +90,13 @@
   --chart-up: #0072b2;
   --chart-down: #e69f00;
 
+  /* Categorical series, fixed order (chat charts) — same hues as dark, which
+     already clear the CVD separation target on this surface. */
+  --chart-series-1: #3f9ae0;
+  --chart-series-2: #c98200;
+  --chart-series-3: #8a5fd6;
+  --chart-series-4: #0e9e6a;
+
   color-scheme: dark;
 }
 

From e633be0ae0df3e6651eed386f47b214ae762f49c Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Thu, 13 Aug 2026 19:19:03 +0300
Subject: [PATCH 047/116] (feat) teach both web chat paths the chart fence
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Formatting conventions have to be ambient: the agent must already know charts
exist while composing a data answer, or it defaults to a table. So the fence
contract lives inline in _WEB_FORMATTING — rules plus one compact example —
next to the table rules it belongs with.

A chat bound to a specialist Agent opens with its own identity instead of
build_initial_context, and so was the one brain that never heard any
formatting rules at all — no tables, and now no charts. bound_agent_context
appends the platform section at that branch, which also gives agent-bound
chats the table guidance they were always missing.

The prompt and the renderer are a contract nothing at runtime enforces: a
renamed field or a tightened cap just makes charts quietly stop appearing.
The test parses the example out of the prompt and checks it against the
renderer's own type whitelist, caps and color names.
---
 condor/runtime/sessions.py        |  33 +++++++-
 handlers/agents/_shared.py        |  26 +++++-
 tests/test_chat_chart_contract.py | 130 ++++++++++++++++++++++++++++++
 3 files changed, 184 insertions(+), 5 deletions(-)
 create mode 100644 tests/test_chat_chart_contract.py

diff --git a/condor/runtime/sessions.py b/condor/runtime/sessions.py
index c306f283..697ac0eb 100644
--- a/condor/runtime/sessions.py
+++ b/condor/runtime/sessions.py
@@ -28,7 +28,11 @@
 from condor.runtime.keys import SessionKey
 from condor.runtime.models import SessionInfo, SessionSpec
 from condor.runtime.timeouts import TIMEOUTS
-from handlers.agents._shared import build_initial_context, get_project_dir
+from handlers.agents._shared import (
+    build_initial_context,
+    get_project_dir,
+    platform_formatting,
+)
 
 log = logging.getLogger(__name__)
 
@@ -246,6 +250,29 @@ async def _enforce_session_budget(user_id: int) -> None:
         await _destroy_session_internal(victim.key)
 
 
+def bound_agent_context(
+    bound: binding.SessionBinding, user_id: int, platform: str
+) -> str:
+    """The opening context of a chat bound to a specialist Agent.
+
+    A specialist opens with its own identity and domain memory rather than the
+    chat's context, which is what makes it a different brain instead of a skin
+    — but it meant it was also the one brain that never passed through
+    :func:`build_initial_context`, and so never heard how the surface it is
+    speaking into renders a reply: no tables and no charts on the dashboard, no
+    length rules on Telegram. The formatting section is appended here, at the
+    branch that skips the other path, so both teach it exactly once.
+    """
+    return "\n\n".join(
+        (
+            binding.agent_identity_context(
+                bound.agent_slug, user_id, bound.instructions, bound.label
+            ),
+            platform_formatting(platform),
+        )
+    )
+
+
 def _resolve_conversation(
     spec: SessionSpec,
     key: SessionKey,
@@ -458,9 +485,7 @@ async def get_or_create_session(
         # the chat's — that is what makes it a different brain, not a skin.
         initial_context = ""
         if bound.is_agent and spec.user_id:
-            initial_context = binding.agent_identity_context(
-                bound.agent_slug, spec.user_id, bound.instructions, bound.label
-            )
+            initial_context = bound_agent_context(bound, spec.user_id, spec.platform)
         elif spec.user_id:
             initial_context = build_initial_context(
                 spec.user_id,
diff --git a/handlers/agents/_shared.py b/handlers/agents/_shared.py
index 6d13279a..49168ffc 100644
--- a/handlers/agents/_shared.py
+++ b/handlers/agents/_shared.py
@@ -246,6 +246,19 @@ def _default_agent() -> str:
     "- No message length limits, but stay concise.\n"
     "- Use tables for structured data (portfolios, prices, comparisons).\n"
     "- Use code blocks for configs, JSON, or commands.\n"
+    "- CHARTS: when the answer is a numeric series or comparison (a price or\n"
+    "  PnL curve, volume per venue, a distribution), draw it with a ```chart\n"
+    "  fence holding one JSON object. The dashboard renders it as an\n"
+    "  interactive chart:\n"
+    "  ```chart\n"
+    '  {"type": "line", "title": "SOL/USDC 24h", "x": "time",\n'
+    '   "series": [{"key": "price", "name": "Price"}],\n'
+    '   "data": [{"time": "12:00", "price": 150.1}, {"time": "16:00", "price": 152.4}]}\n'
+    "  ```\n"
+    '  "type" is "line", "area" or "bar"; "x" and every series "key" name\n'
+    "  fields of the data rows. Max 4 series and 200 points (downsample longer\n"
+    '  series). A series may set "color": "up", "down", "yellow" or a hex.\n'
+    "  Chart for the shape, table for exact values; use both when both matter.\n"
     "- Respond in the user's language."
 )
 
@@ -258,13 +271,24 @@ def _default_agent() -> str:
 )
 
 
+def platform_formatting(platform: str = "telegram") -> str:
+    """The reply-formatting rules for a platform.
+
+    Public because a bound Agent opens the chat with its own identity context
+    instead of :func:`build_initial_context`, and would otherwise be the only
+    brain in the product that never hears how the surface it is speaking into
+    renders a reply.
+    """
+    return _WEB_FORMATTING if platform == "web" else _TELEGRAM_FORMATTING
+
+
 def _build_system_prompt(platform: str = "telegram") -> str:
     """Condor's own AGENT.md plus the platform's formatting rules."""
     agent = _chat_agent()
     return (
         "[System context -- do not repeat this to the user]\n\n"
         f"{agent.instructions if agent else ''}\n\n"
-        f"{_WEB_FORMATTING if platform == 'web' else _TELEGRAM_FORMATTING}"
+        f"{platform_formatting(platform)}"
     )
 
 
diff --git a/tests/test_chat_chart_contract.py b/tests/test_chat_chart_contract.py
new file mode 100644
index 00000000..7be89507
--- /dev/null
+++ b/tests/test_chat_chart_contract.py
@@ -0,0 +1,130 @@
+"""The ```chart fence is a contract between a prompt and a React component.
+
+The agent is told the shape in `_WEB_FORMATTING`; `ChartBlock.tsx` is what
+actually parses it. Nothing at runtime holds the two together: a renamed field
+or a tightened cap on either side does not fail anything, it just makes charts
+quietly stop appearing in the chat. These tests are that seam.
+
+They also pin the second half of the feature: a chat bound to a specialist
+Agent skips `build_initial_context`, so the formatting rules have to reach it
+through `bound_agent_context` or that brain never learns the fence exists.
+"""
+
+import json
+import re
+from pathlib import Path
+
+import pytest
+
+from condor.runtime import binding
+from condor.runtime.sessions import bound_agent_context
+from handlers.agents._shared import (
+    _TELEGRAM_FORMATTING,
+    _WEB_FORMATTING,
+    platform_formatting,
+)
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+CHART_BLOCK_TSX = (
+    REPO_ROOT / "frontend" / "src" / "components" / "chat" / "ChartBlock.tsx"
+)
+
+
+def _prompt_example() -> dict:
+    """The one spec the prompt shows the agent, parsed."""
+    # Anchored on the `{` so the prose that names the fence in passing
+    # ("draw it with a ```chart fence") cannot match instead.
+    fence = re.search(r"```chart\n(\s*\{.*?)\n\s*```", _WEB_FORMATTING, re.S)
+    assert fence, "_WEB_FORMATTING no longer documents a ```chart fence"
+    # The example is indented inside the bullet it belongs to.
+    body = "\n".join(line.strip() for line in fence.group(1).splitlines())
+    return json.loads(body)
+
+
+def _renderer_types() -> set[str]:
+    source = CHART_BLOCK_TSX.read_text()
+    literal = re.search(r"const CHART_TYPES = \[(.*?)\] as const;", source, re.S)
+    assert literal, "CHART_TYPES literal not found in ChartBlock.tsx"
+    return set(re.findall(r'"([^"]+)"', literal.group(1)))
+
+
+def _renderer_cap(name: str) -> int:
+    source = CHART_BLOCK_TSX.read_text()
+    match = re.search(rf"const {name} = (\d+);", source)
+    assert match, f"{name} not found in ChartBlock.tsx"
+    return int(match.group(1))
+
+
+def test_web_prompt_documents_the_chart_fence():
+    """A model that never sees the fence never draws one."""
+    assert "```chart" in _WEB_FORMATTING
+    assert "CHARTS:" in _WEB_FORMATTING
+
+
+def test_prompt_example_is_what_the_renderer_accepts():
+    """The example is the spec: if it would not render, nothing will."""
+    spec = _prompt_example()
+
+    assert spec["type"] in _renderer_types()
+    assert isinstance(spec["x"], str) and spec["x"]
+    assert spec["series"] and len(spec["series"]) <= _renderer_cap("MAX_SERIES")
+    assert spec["data"] and len(spec["data"]) <= _renderer_cap("MAX_ROWS")
+
+    # Every key the spec names must exist in every row, or the chart draws
+    # axes around nothing.
+    keys = {spec["x"]} | {s["key"] for s in spec["series"]}
+    for row in spec["data"]:
+        assert keys <= set(row), f"row {row} is missing {keys - set(row)}"
+
+
+def test_prompt_documents_every_type_the_renderer_supports():
+    """A supported type the agent is never told about is a dead branch."""
+    for chart_type in _renderer_types():
+        assert (
+            f'"{chart_type}"' in _WEB_FORMATTING
+        ), f"prompt never mentions {chart_type}"
+
+
+def test_prompt_caps_match_the_renderer_caps():
+    """The prompt asks for downsampling at exactly the point we slice."""
+    assert str(_renderer_cap("MAX_ROWS")) in _WEB_FORMATTING
+    assert str(_renderer_cap("MAX_SERIES")) in _WEB_FORMATTING
+
+
+def test_named_colors_offered_to_the_agent_exist_in_the_renderer():
+    """A color name the agent is told to use, and the renderer never heard of,
+    silently paints the series with the wrong palette slot."""
+    source = CHART_BLOCK_TSX.read_text()
+    offer = re.search(r'"color":(.*?)or a hex', _WEB_FORMATTING, re.S)
+    assert offer, "_WEB_FORMATTING no longer offers named series colors"
+    named = set(re.findall(r'"(\w+)"', offer.group(1)))
+    block = re.search(r"const NAMED_COLORS[^=]*= \{(.*?)\};", source, re.S)
+    assert block, "NAMED_COLORS not found in ChartBlock.tsx"
+    known = set(re.findall(r"^\s*(\w+):", block.group(1), re.M))
+    assert named <= known, f"prompt offers colors the renderer ignores: {named - known}"
+
+
+def test_telegram_prompt_stays_chartless():
+    """Telegram renders PNGs, not fences — a chart fence there is noise."""
+    assert "```chart" not in _TELEGRAM_FORMATTING
+    assert platform_formatting("telegram") is _TELEGRAM_FORMATTING
+    assert platform_formatting("web") is _WEB_FORMATTING
+
+
+@pytest.mark.parametrize(
+    "platform,expected",
+    [("web", _WEB_FORMATTING), ("telegram", _TELEGRAM_FORMATTING)],
+)
+def test_bound_agent_opens_with_the_platform_formatting(platform, expected):
+    """The specialist path skips build_initial_context; it must not skip this."""
+    bound = binding.SessionBinding(
+        label="Test Agent",
+        agent_slug="a-slug-that-does-not-exist",
+        instructions="You are a test.",
+    )
+
+    context = bound_agent_context(bound, user_id=1, platform=platform)
+
+    assert expected in context
+    # Identity still leads: the formatting is appended, never a replacement.
+    assert context.index("You are a test.") < context.index(expected)

From 4f7929fbd48154b487377c761dffc7906d3b8da0 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Thu, 13 Aug 2026 19:31:33 +0300
Subject: [PATCH 048/116] (feat) improve charting

---
 frontend/src/pages/DexPool.tsx | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/frontend/src/pages/DexPool.tsx b/frontend/src/pages/DexPool.tsx
index 287ed703..2d32a0fe 100644
--- a/frontend/src/pages/DexPool.tsx
+++ b/frontend/src/pages/DexPool.tsx
@@ -43,7 +43,11 @@ export function DexPool() {
   const { network = "", address = "" } = useParams();
 
   const [wantedTab, setTab] = useState<Tab>("order");
-  const [interval, setIntervalValue] = useState("1m");
+  // 5m over 3 days, matching the executor pages. Not 1m: GeckoTerminal caps a
+  // response at 1000 candles, so 1m can only ever fill ~16h of this window (the
+  // buffer then sits permanently short and re-backfills), while 5m covers the
+  // full 3 days in one request and halves the poll rate on a shared budget.
+  const [interval, setIntervalValue] = useState("5m");
   const [lookbackSeconds, setLookbackSeconds] = useState(3 * 86400);
   const [rightPanelWidth, setRightPanelWidth] = useState(288);
   const [bottomPaneHeight, setBottomPaneHeight] = useState(200);

From 4e1a4ef219833a0c9aff8d8ee1e49f05134263b3 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Thu, 13 Aug 2026 19:31:37 +0300
Subject: [PATCH 049/116] (feat) improve dex data

---
 handlers/dex/pool_data.py         | 264 +++++++++++++++++++++++++++---
 tests/conftest.py                 |  16 ++
 tests/test_dex_candles.py         |   6 +-
 tests/test_dex_pool_resolution.py |   2 +-
 4 files changed, 264 insertions(+), 24 deletions(-)

diff --git a/handlers/dex/pool_data.py b/handlers/dex/pool_data.py
index d86d2f87..db8b6f00 100644
--- a/handlers/dex/pool_data.py
+++ b/handlers/dex/pool_data.py
@@ -17,6 +17,7 @@
 import math
 import re
 import time
+from collections import deque
 from typing import Any, Dict, List, Optional, Tuple
 
 import httpx
@@ -265,14 +266,59 @@ def _gecko_client() -> GeckoTerminalAsyncClient:
 
 # GeckoTerminal's free tier is ~30 requests/minute *per IP*, and that budget is
 # shared by every dashboard viewer, the candle poll loop and the pool browser at
-# once. Left unbounded, a single page load with a dex filter fans out to eight
-# concurrent requests and throttles the whole process; the semaphore turns that
-# burst into a queue.
+# once. Three separate guards defend it, because they fail differently:
+#
+# * ``_gecko_gate`` (concurrency) turns a burst into a queue, so one page load
+#   with a dex filter cannot open eight sockets at once.
+# * ``_acquire_rate_slot`` (rate) is the one that actually keeps us under the
+#   limit. A concurrency cap alone does not: four *fast* concurrent requests
+#   sustain well over 100/min, which is how the budget was being spent before
+#   anything looked like a burst.
+# * ``_trip_breaker`` (circuit) stops calling at all for a moment once gecko has
+#   said 429. Every request sent during a throttled window is spent for nothing
+#   and keeps the window rolling, so the cheapest response is silence.
 _GECKO_MAX_CONCURRENCY = 4
 _GECKO_TIMEOUT = 15.0
 _GECKO_RETRIES = 2
 _gecko_semaphore: Optional[asyncio.Semaphore] = None
 
+# Held under gecko's ~30 so a burst that straddles the window boundary still
+# lands inside it, and so a Telegram handler racing the dashboard has headroom.
+_GECKO_RATE_LIMIT = 25
+_GECKO_RATE_WINDOW = 60.0
+
+# How long a caller will queue for a slot before giving up. A web request is
+# waiting on the other end, and this module's standing answer to "no budget" is
+# the stale cache the callers already fall back to — which beats a request that
+# hangs for most of a minute and then succeeds into a closed browser tab.
+_GECKO_MAX_WAIT = 5.0
+
+# Silence after a 429. Long enough for a rolling per-minute window to drain most
+# of the way, short enough that a chart recovers on its next poll rather than
+# staying blank until someone reloads.
+_GECKO_COOLDOWN = 20.0
+
+
+class GeckoRateLimited(RuntimeError):
+    """Raised *instead of* calling gecko when the shared budget is spent.
+
+    Carries "rate limit" in its message so ``_is_rate_limited`` recognizes it and
+    callers that already branch on a throttled upstream need no change.
+    """
+
+
+# Timestamps of the requests inside the current rolling window.
+_gecko_call_times: deque = deque()
+_gecko_rate_lock: Optional[asyncio.Lock] = None
+
+# Circuit-breaker + health state. Process-wide, because the budget is per-IP:
+# one viewer's 429 is every viewer's 429, and there is no point rediscovering it
+# once per chart.
+_gecko_cooldown_until: float = 0.0
+_gecko_last_429: float = 0.0
+_gecko_429_count: int = 0
+_gecko_throttled_calls: int = 0
+
 
 def _gecko_gate() -> asyncio.Semaphore:
     """The concurrency gate, built lazily so it binds to the running loop."""
@@ -282,43 +328,196 @@ def _gecko_gate() -> asyncio.Semaphore:
     return _gecko_semaphore
 
 
+def _gecko_rate_gate() -> asyncio.Lock:
+    """The rate gate, built lazily for the same reason as the semaphore."""
+    global _gecko_rate_lock
+    if _gecko_rate_lock is None:
+        _gecko_rate_lock = asyncio.Lock()
+    return _gecko_rate_lock
+
+
 def _is_rate_limited(exc: BaseException) -> bool:
+    if isinstance(exc, GeckoRateLimited):
+        return True
     resp = getattr(exc, "response", None)
     if resp is not None and getattr(resp, "status_code", None) == 429:
         return True
     return "429" in str(exc) or "rate limit" in str(exc).lower()
 
 
-async def gecko_request(method: str, path: str, **kwargs) -> Any:
-    """One GeckoTerminal call, gated and retried where retrying can help.
+def _trip_breaker() -> None:
+    """Record a 429 and stop outbound calls for ``_GECKO_COOLDOWN`` seconds."""
+    global _gecko_cooldown_until, _gecko_last_429, _gecko_429_count
+    now = time.time()
+    _gecko_last_429 = now
+    _gecko_429_count += 1
+    _gecko_cooldown_until = now + _GECKO_COOLDOWN
+    logger.warning(
+        "GeckoTerminal rate-limited (429 #%d) — pausing all requests for %.0fs",
+        _gecko_429_count,
+        _GECKO_COOLDOWN,
+    )
+
+
+async def _acquire_rate_slot() -> None:
+    """Claim one request from the shared per-minute budget.
+
+    Waits for a slot up to ``_GECKO_MAX_WAIT``; raises ``GeckoRateLimited`` when
+    the budget is spent for longer than that, or while the breaker is open. The
+    wait happens under the lock so callers queue in arrival order instead of
+    stampeding the instant a slot frees.
+    """
+    global _gecko_throttled_calls
+    deadline = time.time() + _GECKO_MAX_WAIT
+    async with _gecko_rate_gate():
+        while True:
+            now = time.time()
+
+            if now < _gecko_cooldown_until:
+                _gecko_throttled_calls += 1
+                raise GeckoRateLimited(
+                    f"GeckoTerminal rate limit: cooling down for another "
+                    f"{_gecko_cooldown_until - now:.1f}s"
+                )
+
+            while (
+                _gecko_call_times and now - _gecko_call_times[0] >= _GECKO_RATE_WINDOW
+            ):
+                _gecko_call_times.popleft()
+
+            if len(_gecko_call_times) < _GECKO_RATE_LIMIT:
+                _gecko_call_times.append(now)
+                return
+
+            # Budget full: wait exactly until the oldest request ages out.
+            wait = _GECKO_RATE_WINDOW - (now - _gecko_call_times[0])
+            if now + wait > deadline:
+                _gecko_throttled_calls += 1
+                raise GeckoRateLimited(
+                    f"GeckoTerminal rate limit: {_GECKO_RATE_LIMIT} requests "
+                    f"already sent this minute, next slot in {wait:.1f}s"
+                )
+            await asyncio.sleep(min(wait, 0.25))
+
+
+def gecko_health() -> Dict[str, Any]:
+    """Current state of the shared GeckoTerminal budget.
+
+    Exists so "are we rate limited?" has an answer that is not "read the logs" —
+    every failure downstream of here degrades to an empty list, which cannot tell
+    a throttled upstream apart from a pool that simply has no trades.
+    """
+    now = time.time()
+    recent = sum(1 for t in _gecko_call_times if now - t < _GECKO_RATE_WINDOW)
+    return {
+        "rate_limited": now < _gecko_cooldown_until,
+        "cooldown_remaining": max(0.0, _gecko_cooldown_until - now),
+        "requests_last_minute": recent,
+        "budget": _GECKO_RATE_LIMIT,
+        "count_429": _gecko_429_count,
+        "last_429_age": (now - _gecko_last_429) if _gecko_last_429 else None,
+        "throttled_calls": _gecko_throttled_calls,
+    }
+
+
+def reset_gecko_throttle() -> None:
+    """Forget the spent budget and any open breaker.
+
+    For tests, which drive hundreds of calls through this module inside one real
+    wall-clock minute and would otherwise throttle themselves.
+    """
+    global _gecko_cooldown_until, _gecko_last_429, _gecko_429_count
+    global _gecko_throttled_calls
+    _gecko_call_times.clear()
+    _gecko_inflight.clear()
+    _gecko_cooldown_until = 0.0
+    _gecko_last_429 = 0.0
+    _gecko_429_count = 0
+    _gecko_throttled_calls = 0
+    for cache in (
+        _gecko_page_cache,
+        _pool_by_address_cache,
+        _multi_pool_cache,
+        _gecko_dexes_cache,
+        _gateway_pool_list_cache,
+        _token_symbol_cache,
+        _token_pool_cache,
+        _pair_pool_cache,
+    ):
+        cache.clear()
+
+
+async def gecko_call(method: str, *args: Any, **kwargs: Any) -> Any:
+    """One GeckoTerminal client call, rate-gated and retried where that helps.
+
+    ``method`` names a method on the shared client. Every outbound GeckoTerminal
+    request in this module goes through here — calling the client directly skips
+    the budget, which is exactly how the candle poll loop (the highest-frequency
+    caller in the process) used to exhaust it while the guards sat idle in front
+    of two pool-list walks.
 
     Only timeouts and transport errors are retried. A 429 is deliberately *not*:
     gecko's limit is a per-minute window, so no backoff short enough to sit inside
     a web request will clear it, and a retry only spends more of the very budget
-    that is exhausted — while making every other caller wait behind it. The answer
-    to a 429 is the stale cache the callers fall back to, and the semaphore above,
-    which stops the burst that causes it. A 404, or the 401 gecko answers past page
-    10, is a final answer and is raised on the first attempt.
+    that is exhausted. It trips the breaker instead. A 404, or the 401 gecko
+    answers past page 10, is a final answer and is raised on the first attempt.
     """
     for attempt in range(_GECKO_RETRIES + 1):
+        await _acquire_rate_slot()
         try:
             async with _gecko_gate():
-                return await _gecko_client().api_request(method, path, **kwargs)
+                return await getattr(_gecko_client(), method)(*args, **kwargs)
         except Exception as e:  # noqa: BLE001 - re-raised below when not retryable
-            retryable = not _is_rate_limited(e) and isinstance(
-                e, (httpx.TimeoutException, httpx.TransportError)
-            )
+            if _is_rate_limited(e):
+                if not isinstance(e, GeckoRateLimited):
+                    _trip_breaker()
+                raise
+            retryable = isinstance(e, (httpx.TimeoutException, httpx.TransportError))
             if not retryable or attempt == _GECKO_RETRIES:
                 raise
             await asyncio.sleep(_GECKO_BACKOFF[attempt])
     raise RuntimeError("unreachable")
 
 
+async def gecko_request(method: str, path: str, **kwargs) -> Any:
+    """A raw REST call for paths the typed client does not expose."""
+    return await gecko_call("api_request", method, path, **kwargs)
+
+
 # Backoff between retries of a *timeout*, which is a slow chain listing rather than
 # a throttled one — short, because a web request is waiting on it.
 _GECKO_BACKOFF = (0.4, 1.0)
 
 
+# ── Single-flight ──
+# A TTL cache only helps once an answer has *arrived*. Flicking between explorer
+# tabs asks for the same listings again while the first requests are still in the
+# air, so every one of them misses the cache and opens its own gecko request — the
+# fastest way there is to spend the minute's budget. This collapses concurrent
+# callers of the same key onto one upstream request.
+_gecko_inflight: Dict[Tuple, "asyncio.Task"] = {}
+
+
+async def _single_flight(key: Tuple, factory) -> Any:
+    """Run ``factory()`` once per key, sharing its result with every concurrent caller.
+
+    The work runs as a detached task and awaiters ``shield`` it, so the very thing
+    that causes the stampede — a viewer navigating away and cancelling their
+    request — cannot also cancel the fetch the remaining viewers are waiting on.
+    """
+    task = _gecko_inflight.get(key)
+    if task is None or task.done():
+        task = asyncio.ensure_future(factory())
+        _gecko_inflight[key] = task
+
+        def _clear(finished: "asyncio.Task", _key: Tuple = key) -> None:
+            if _gecko_inflight.get(_key) is finished:
+                _gecko_inflight.pop(_key, None)
+
+        task.add_done_callback(_clear)
+    return await asyncio.shield(task)
+
+
 # ── Small TTL caches for token lookups ──
 # These answers are process-wide (not per-user) and tiny, so they live here rather
 # than in a caller's user_data. Capped so an unbounded stream of distinct mints
@@ -396,7 +595,7 @@ async def fetch_token_symbol(mint: str, network: str) -> str:
         return cached
 
     try:
-        data = await _gecko_client().get_specific_token_on_network(gnet, mint)
+        data = await gecko_call("get_specific_token_on_network", gnet, mint)
     except Exception as e:
         logger.info("token symbol lookup failed mint=%s net=%s: %s", mint, gnet, e)
         return ""
@@ -436,7 +635,7 @@ async def fetch_token_top_pool_info(
         return cached or None
 
     try:
-        pools = await _gecko_client().get_top_pools_by_network_token(gnet, mint)
+        pools = await gecko_call("get_top_pools_by_network_token", gnet, mint)
     except Exception as e:
         # Includes the KeyError geckoterminal_py raises post-processing an empty
         # result set. Not cached — a transient failure must not pin "" for an hour.
@@ -507,7 +706,7 @@ async def fetch_pair_top_pool_info(
     try:
         # Both symbols in the query: GeckoTerminal matches them against the pool
         # name ("SOLO / XRP"), so this narrows the answer set before we filter.
-        data = await _gecko_client().api_request(
+        data = await gecko_request(
             "GET", "search/pools", params={"query": f"{b} {q}", "network": gnet}
         )
     except Exception as e:
@@ -789,7 +988,8 @@ async def fetch_ohlcv(
         # Pass all parameters explicitly:
         # - currency="token" means price in quote token (not USD)
         # - token="base" means OHLCV for the base token
-        result = await _gecko_client().get_ohlcv(
+        result = await gecko_call(
+            "get_ohlcv",
             gecko_network,
             pool_address,
             timeframe,
@@ -1360,6 +1560,23 @@ async def _gecko_page_rows(
     if cached is not None:
         return [dict(row) for row in cached]
 
+    # Concurrent askers for this exact page share one request. Rows are copied per
+    # caller below, since the shared answer is one list object.
+    rows = await _single_flight(
+        ("page",) + key, lambda: _gecko_page_fetch(gnet, view, token, page, dex, key)
+    )
+    return None if rows is None else [dict(row) for row in rows]
+
+
+async def _gecko_page_fetch(
+    gnet: str,
+    view: str,
+    token: str,
+    page: int,
+    dex: Optional[str],
+    key: Tuple,
+) -> Optional[List[Dict[str, Any]]]:
+    """The uncached fetch behind ``_gecko_page_rows``. One upstream request."""
     if dex:
         path = GECKO_CONSTANTS.GET_TOP_POOLS_BY_NETWORK_DEX_PATH.format(gnet, dex)
     elif view == "token":
@@ -1392,11 +1609,11 @@ async def _gecko_page_rows(
             f" (serving {age:.0f}s-old cache)" if stale is not None else "",
         )
         if stale is not None:
-            return [dict(row) for row in stale]
+            return stale
         return None
 
     _stale_put(_gecko_page_cache, key, rows)
-    return [dict(row) for row in rows]
+    return rows
 
 
 def _normalized_gecko_rows(
@@ -1641,7 +1858,7 @@ async def fetch_pools_by_addresses(
             pools.extend(dict(row) for row in cached)
             continue
         try:
-            result = await _gecko_client().get_multiple_pools_by_network(gnet, batch)
+            result = await gecko_call("get_multiple_pools_by_network", gnet, batch)
         except Exception as e:
             stale, age = _stale_get(_multi_pool_cache, batch_key)
             logger.warning(
@@ -1761,7 +1978,12 @@ async def fetch_pool_by_address(
         return dict(cached) if cached else None
 
     try:
-        result = await _gecko_client().get_pool_by_network_address(gnet, pool_address)
+        # Shared with any concurrent viewer of the same pool — opening pools in
+        # quick succession otherwise opens one request each.
+        result = await _single_flight(
+            ("pool", gnet, pool_address),
+            lambda: gecko_call("get_pool_by_network_address", gnet, pool_address),
+        )
     except Exception as e:
         logger.info("pool lookup failed net=%s pool=%s: %s", gnet, pool_address, e)
         return None
diff --git a/tests/conftest.py b/tests/conftest.py
index 734b9e40..e4c1b38e 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -3,6 +3,8 @@
 import importlib.util
 import sys
 
+import pytest
+
 from condor.memory.paths import shared_routines_root
 
 
@@ -27,3 +29,17 @@ def load_shared_routine(name: str):
     sys.modules[module_name] = module
     spec.loader.exec_module(module)
     return module
+
+
+@pytest.fixture(autouse=True)
+def _reset_gecko_throttle():
+    """Give every test the full GeckoTerminal budget.
+
+    The limiter is process-wide and window-based on real time, so without this a
+    fast suite spends the whole minute's budget inside the first few tests and the
+    rest fail on a throttle that has nothing to do with what they assert.
+    """
+    from handlers.dex.pool_data import reset_gecko_throttle
+
+    reset_gecko_throttle()
+    yield
diff --git a/tests/test_dex_candles.py b/tests/test_dex_candles.py
index 2feb8d6a..af102196 100644
--- a/tests/test_dex_candles.py
+++ b/tests/test_dex_candles.py
@@ -196,7 +196,9 @@ def test_a_failed_pool_lookup_is_not_cached(monkeypatch):
     class _Failing:
         async def get_top_pools_by_network_token(self, *_a):
             calls.append(1)
-            raise RuntimeError("429 Too Many Requests")
+            # Not a 429: that trips the shared breaker, which deliberately skips
+            # the second call. What is under test here is the cache rule.
+            raise RuntimeError("upstream exploded")
 
     monkeypatch.setattr(pool_data, "_gecko_client", lambda: _Failing())
     assert run(pool_data.fetch_token_top_pool("mint", "solana", "SOL")) == ""
@@ -484,7 +486,7 @@ def test_a_failed_pair_search_is_not_cached(monkeypatch):
     class _Failing:
         async def api_request(self, *_a, **_k):
             calls.append(1)
-            raise RuntimeError("429 Too Many Requests")
+            raise RuntimeError("upstream exploded")
 
     monkeypatch.setattr(pool_data, "_gecko_client", lambda: _Failing())
     assert run(pool_data.fetch_pair_top_pool("SOLO", "XRP", "xrpl")) == ("", False)
diff --git a/tests/test_dex_pool_resolution.py b/tests/test_dex_pool_resolution.py
index ef4f97db..75dd23ea 100644
--- a/tests/test_dex_pool_resolution.py
+++ b/tests/test_dex_pool_resolution.py
@@ -127,7 +127,7 @@ def test_a_failed_lookup_is_still_not_cached_in_the_info_form(monkeypatch):
     class _Failing:
         async def get_top_pools_by_network_token(self, *_a):
             calls.append(1)
-            raise RuntimeError("429 Too Many Requests")
+            raise RuntimeError("upstream exploded")
 
     monkeypatch.setattr(pool_data, "_gecko_client", lambda: _Failing())
     assert run(pool_data.fetch_token_top_pool_info("mint", "solana", "SOL")) is None

From 73b1f12cfb612ce9f65458dc9a253966d028430b Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Thu, 13 Aug 2026 23:41:56 +0300
Subject: [PATCH 050/116] (feat) run_code: run a snippet where a routine runs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

An ad-hoc Python snippet gets the same environment a routine gets — the
main process, WebRoutineContext, the cached API client, report
attribution — with the file and its config schema removed.

The snippet is a plain script body: PyCF_ALLOW_TOP_LEVEL_AWAIT makes
top-level `await` work with no wrapper, which is what keeps traceback
line numbers pointing at the line the caller actually wrote. Capture is
a ContextVar-backed sys.stdout proxy and every run lives in its own
asyncio.Task, so concurrent runs cannot read each other's output and the
bot's own logging is never swallowed.

Every run — code, stdout, result, traceback — is persisted whole under
data/code_runs/, so a failed snippet can be read back and corrected.
---
 condor/code_runner.py         | 238 +++++++++++++++++++++++++++++
 condor/code_runs.py           | 180 ++++++++++++++++++++++
 tests/test_code_runner.py     | 273 ++++++++++++++++++++++++++++++++++
 tests/test_code_runs_store.py | 118 +++++++++++++++
 4 files changed, 809 insertions(+)
 create mode 100644 condor/code_runner.py
 create mode 100644 condor/code_runs.py
 create mode 100644 tests/test_code_runner.py
 create mode 100644 tests/test_code_runs_store.py

diff --git a/condor/code_runner.py b/condor/code_runner.py
new file mode 100644
index 00000000..545bca3d
--- /dev/null
+++ b/condor/code_runner.py
@@ -0,0 +1,238 @@
+"""Run an ad-hoc Python snippet with a routine's primitives (FEAT-047).
+
+This is the thinner sibling of ``RoutineStore._execute_and_record``: same main
+process, same :class:`WebRoutineContext`, same report attribution — with the
+routine file and its config schema removed. What a snippet can reach, a routine
+can reach, and vice versa; that is the point, because "it worked in run_code" is
+otherwise a bug class.
+
+The snippet contract is deliberately *no* contract: the code is a script body,
+top-level ``await`` is allowed, ``print()`` is the output and an optional
+``result`` variable is the return value. ``PyCF_ALLOW_TOP_LEVEL_AWAIT`` buys
+that without wrapping the source in a function, which is what keeps traceback
+line numbers pointing at the line the caller actually wrote — the single most
+useful property when the caller is a model about to fix its own snippet.
+"""
+
+from __future__ import annotations
+
+import ast
+import asyncio
+import contextvars
+import inspect
+import io
+import logging
+import sys
+import time
+import traceback
+
+import condor.reports as reports
+from condor.code_runs import CodeRun, get_code_run_store, new_run_id
+from condor.memory.paths import CHAT_SLUG
+
+logger = logging.getLogger(__name__)
+
+# The name compiled snippets carry, and therefore the name in their tracebacks.
+CODE_FILENAME = "<code_run>"
+
+DEFAULT_TIMEOUT = 60.0
+MAX_TIMEOUT = 120.0
+
+# Where a run's ``print`` goes. Per-context, so concurrent runs cannot read each
+# other's output — which only holds because every run gets its own asyncio.Task
+# (a Task copies the context; awaiting a bare coroutine would share ours and
+# leak the buffer into the caller).
+_CAPTURE: contextvars.ContextVar[io.StringIO | None] = contextvars.ContextVar(
+    "code_run_stdout", default=None
+)
+
+
+class _StdoutProxy:
+    """``sys.stdout`` that routes to the running snippet's buffer, else onward.
+
+    Installed process-wide and never removed, so it must be invisible to
+    everything that is not a code run: with no capture buffer set it is a pass
+    through to the stream it wrapped, and the bot's own output is untouched.
+    """
+
+    def __init__(self, stream):
+        self._stream = stream
+
+    def write(self, data):
+        buffer = _CAPTURE.get()
+        if buffer is not None:
+            return buffer.write(data)
+        return self._stream.write(data)
+
+    def flush(self):
+        buffer = _CAPTURE.get()
+        if buffer is None:
+            self._stream.flush()
+
+    def __getattr__(self, name):
+        return getattr(self._stream, name)
+
+
+def _install_stdout_proxy() -> None:
+    """Wrap ``sys.stdout`` once. The isinstance check is the idempotence.
+
+    Not a "did we already do it" flag: something else may have replaced
+    ``sys.stdout`` since (a test harness, a debugger), and then the wrapper is
+    gone and capture has to be re-established over the new stream.
+    """
+    if not isinstance(sys.stdout, _StdoutProxy):
+        sys.stdout = _StdoutProxy(sys.stdout)
+
+
+def _trim_traceback(text: str) -> str:
+    """Drop the harness frames above the snippet's own.
+
+    Everything before the first ``File "<code_run>"`` line is this module
+    calling ``eval``; a model reading the traceback to fix its code should see
+    only its code.
+    """
+    lines = text.splitlines(keepends=True)
+    for i, line in enumerate(lines):
+        if CODE_FILENAME in line:
+            head = lines[0] if lines and lines[0].startswith("Traceback") else ""
+            return head + "".join(lines[i:])
+    return text
+
+
+def _render_result(namespace: dict) -> str:
+    """The snippet's ``result`` global as text, or "" when it never set one.
+
+    ``str`` rather than ``repr``: the readers are a model and a human, and
+    ``2.0`` says what ``np.float64(2.0)`` says with less noise, while a
+    DataFrame renders as its table either way.
+    """
+    if "result" not in namespace:
+        return ""
+    value = namespace["result"]
+    if value is None:
+        return ""
+    try:
+        return str(value)
+    except Exception as e:  # a __str__ that raises must not fail the run
+        return f"<unrenderable result: {type(e).__name__}: {e}>"
+
+
+async def _run_in_task(
+    compiled, namespace: dict, buffer, agent: str, source: str, out: dict
+):
+    """The snippet itself, in its own task context.
+
+    Setting the capture ContextVar *here* (not in the caller) is what keeps the
+    buffer private to this run, and the report id is read in a ``finally`` so a
+    snippet that saved a report and then raised still reports it.
+    """
+    _CAPTURE.set(buffer)
+    reports.reset_last_report_id()
+    try:
+        with reports.attribute_to(agent), reports.default_source("code", source):
+            outcome = eval(compiled, namespace)  # noqa: S307 - this IS the feature
+            if inspect.isawaitable(outcome):
+                await outcome
+    finally:
+        out["report_id"] = reports.get_last_report_id() or ""
+
+
+async def execute_code(
+    code: str,
+    *,
+    server_name: str = "",
+    agent: str = "",
+    label: str = "",
+    timeout: float = DEFAULT_TIMEOUT,
+    chat_id: int = 0,
+    session_key: str = "",
+) -> dict:
+    """Compile, run and persist one snippet. Returns the stored record as a dict."""
+    from condor.routine_store import WebRoutineContext, get_routine_store
+    from config_manager import get_client
+
+    run_id = new_run_id()
+    agent = agent or CHAT_SLUG
+    timeout = max(1.0, min(float(timeout or DEFAULT_TIMEOUT), MAX_TIMEOUT))
+    buffer = io.StringIO()
+    started = time.monotonic()
+
+    run = CodeRun(
+        id=run_id,
+        created=time.time(),
+        agent=agent,
+        label=label,
+        server=server_name,
+        code=code,
+        session_key=session_key,
+    )
+
+    try:
+        compiled = compile(
+            code, CODE_FILENAME, "exec", flags=ast.PyCF_ALLOW_TOP_LEVEL_AWAIT
+        )
+    except SyntaxError as e:
+        run.status = "error"
+        run.error = f"{type(e).__name__}: {e}"
+        run.traceback = _trim_traceback(traceback.format_exc())
+        run.duration_ms = int((time.monotonic() - started) * 1000)
+        get_code_run_store().save(run)
+        return run.to_dict()
+
+    # The exact context a routine gets, so the two paths cannot diverge — the
+    # active server travels as a preference, which is how get_client resolves it.
+    context = WebRoutineContext(
+        server_name, bot=get_routine_store().get_bot(), chat_id=chat_id
+    )
+    # Best effort: a pure-pandas snippet must still run when no server resolves,
+    # and the reason belongs in the run's own output, not in a raised error.
+    try:
+        client = await get_client(chat_id, context=context)
+    except Exception as e:
+        client = None
+        buffer.write(f"[run_code] no API client available ({e}); `client` is None\n")
+
+    namespace = {
+        "__name__": "__code_run__",
+        "context": context,
+        "client": client,
+    }
+
+    _install_stdout_proxy()
+    out: dict = {"report_id": ""}
+    task = asyncio.create_task(
+        _run_in_task(compiled, namespace, buffer, agent, label or run_id, out)
+    )
+    try:
+        await asyncio.wait_for(task, timeout=timeout)
+        run.status = "ok"
+    except (asyncio.TimeoutError, TimeoutError):
+        run.status = "timeout"
+        run.error = f"Timed out after {timeout:g}s"
+    except asyncio.CancelledError:
+        run.status = "timeout"
+        run.error = "Cancelled"
+        raise
+    except BaseException as e:
+        run.status = "error"
+        run.error = f"{type(e).__name__}: {e}"
+        run.traceback = _trim_traceback(
+            "".join(traceback.format_exception(type(e), e, e.__traceback__))
+        )
+    finally:
+        run.duration_ms = int((time.monotonic() - started) * 1000)
+        run.stdout = buffer.getvalue()
+        run.result = _render_result(namespace)
+        run.report_id = out.get("report_id", "")
+        # Never log the snippet or its output: a run can hold credentials it
+        # printed, and the application log has neither the cap nor the gitignore
+        # that data/code_runs/ has.
+        logger.info(
+            "code run %s finished status=%s in %dms",
+            run_id,
+            run.status,
+            run.duration_ms,
+        )
+        get_code_run_store().save(run)
+
+    return run.to_dict()
diff --git a/condor/code_runs.py b/condor/code_runs.py
new file mode 100644
index 00000000..8078d492
--- /dev/null
+++ b/condor/code_runs.py
@@ -0,0 +1,180 @@
+"""Persistence for ad-hoc code runs (FEAT-047).
+
+Same shape as :mod:`condor.backtest_store` and the report index: one JSON file
+per run under ``data/code_runs/`` plus a light ``_index.json`` so listing a
+history needs no per-file reads. No sqlite anywhere in this repo, and a store
+that holds a few hundred short records whose main consumer reads one record at
+a time does not earn the first one.
+
+The store keeps the **full** text of every run — code, stdout, result,
+traceback. Clipping for a model's context is the caller's job, so a snippet
+that failed can always be read back whole and corrected.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+import secrets
+import tempfile
+import time
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+# Anchored at the repo root, not the cwd: the main process writes this dir and
+# every MCP subprocess reads it, and they need not agree on a working directory.
+_DATA_DIR = Path(__file__).resolve().parents[1] / "data" / "code_runs"
+
+# Retention bound. Also the only thing standing between a snippet that printed a
+# credential and an unbounded pile of them on disk (see FEAT-047 risks).
+MAX_RUNS = 300
+
+# Ids are generated here, but they also arrive from a tool argument — anything
+# that is not this shape never becomes a path.
+_ID_RE = re.compile(r"^[A-Za-z0-9_-]{1,64}$")
+
+# The light meta the index carries, so `list` never opens a run file.
+_INDEX_FIELDS = ("id", "created", "agent", "label", "status", "error", "duration_ms")
+
+
+@dataclass
+class CodeRun:
+    """One execution of an ad-hoc snippet, exactly as it is persisted."""
+
+    id: str
+    created: float
+    agent: str = ""  # attribution slug ("condor" | agent slug)
+    label: str = ""  # short purpose the caller passed ("returns of SOL 1h")
+    server: str = ""
+    status: str = "ok"  # "ok" | "error" | "timeout"
+    duration_ms: int = 0
+    code: str = ""
+    stdout: str = ""
+    result: str = ""  # the snippet's `result` global, rendered; "" if unset
+    error: str = ""  # "ZeroDivisionError: division by zero"
+    traceback: str = ""
+    report_id: str = ""
+    session_key: str = ""
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+def new_run_id() -> str:
+    """``code_<epoch_ms>_<4 hex>`` — sortable by time, unique under concurrency."""
+    return f"code_{int(time.time() * 1000)}_{secrets.token_hex(2)}"
+
+
+class CodeRunStore:
+    """Per-file JSON persistence for code runs, newest-first index, capped."""
+
+    def __init__(self, data_dir: Path | None = None) -> None:
+        self._dir = Path(data_dir) if data_dir is not None else _DATA_DIR
+        self._index_path = self._dir / "_index.json"
+        self._index: list[dict] = []
+        self._dir.mkdir(parents=True, exist_ok=True)
+        self._load_index()
+
+    # ── public API ──
+
+    def save(self, run: CodeRun) -> None:
+        """Write the run, put it at the head of the index, evict past the cap."""
+        data = run.to_dict()
+        self._write_json(self._run_path(run.id), data)
+        self._index = [e for e in self._index if e.get("id") != run.id]
+        self._index.insert(0, {k: data.get(k) for k in _INDEX_FIELDS})
+        self._evict()
+        self._persist_index()
+
+    def get(self, run_id: str) -> dict | None:
+        """The full record, or None if it is unknown or unreadable."""
+        path = self._run_path(run_id)
+        if path is None or not path.exists():
+            return None
+        try:
+            return json.loads(path.read_text(encoding="utf-8"))
+        except Exception:
+            logger.warning("Failed to read code run file %s", path)
+            return None
+
+    def list(self, agent: str | None = None, limit: int = 20) -> list[dict]:
+        """Index meta only, newest first, optionally for one agent."""
+        entries = self._index
+        if agent:
+            entries = [e for e in entries if e.get("agent") == agent]
+        return [dict(e) for e in entries[: max(0, limit)]]
+
+    # ── internals ──
+
+    def _run_path(self, run_id: str) -> Path | None:
+        """The file for ``run_id``, or None when the id is not a legal id.
+
+        Ids reach this store from a tool argument, so the shape check is what
+        keeps ``get`` from being turned into an arbitrary file reader.
+        """
+        if not run_id or not _ID_RE.match(run_id):
+            return None
+        return self._dir / f"{run_id}.json"
+
+    def _evict(self) -> None:
+        """Drop the oldest runs past the cap — index entry *and* file."""
+        for entry in self._index[MAX_RUNS:]:
+            path = self._run_path(entry.get("id", ""))
+            if path is not None and path.exists():
+                try:
+                    path.unlink()
+                except OSError:
+                    logger.warning("Could not evict code run file %s", path)
+        del self._index[MAX_RUNS:]
+
+    def _load_index(self) -> None:
+        if not self._index_path.exists():
+            return
+        try:
+            loaded = json.loads(self._index_path.read_text(encoding="utf-8"))
+            self._index = loaded if isinstance(loaded, list) else []
+        except Exception:
+            logger.warning("Failed to load code run index, starting empty")
+            self._index = []
+
+    def _persist_index(self) -> None:
+        self._write_json(self._index_path, self._index)
+
+    def _write_json(self, path: Path | None, data) -> None:
+        """Atomic create-or-replace, same tempfile + os.replace as the report store."""
+        if path is None:
+            return
+        path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = tempfile.NamedTemporaryFile(
+            mode="w",
+            encoding="utf-8",
+            dir=str(path.parent),
+            prefix=f".{path.name}.",
+            suffix=".tmp",
+            delete=False,
+        )
+        try:
+            json.dump(data, tmp, ensure_ascii=False)
+            tmp.close()
+            os.replace(tmp.name, path)
+        except Exception:
+            tmp.close()
+            try:
+                os.unlink(tmp.name)
+            except OSError:
+                pass
+            raise
+
+
+_store: CodeRunStore | None = None
+
+
+def get_code_run_store() -> CodeRunStore:
+    global _store
+    if _store is None:
+        _store = CodeRunStore()
+    return _store
diff --git a/tests/test_code_runner.py b/tests/test_code_runner.py
new file mode 100644
index 00000000..36db8ae8
--- /dev/null
+++ b/tests/test_code_runner.py
@@ -0,0 +1,273 @@
+"""Running a snippet where a routine runs (FEAT-047).
+
+The properties pinned here are the ones that make a snippet worth writing
+instead of a routine file: top-level ``await`` with no boilerplate, tracebacks
+that point at the caller's own line, a timeout that still hands back what was
+printed before the cut, and capture that cannot leak between concurrent runs or
+swallow the bot's own output.
+
+Sync tests driving coroutines with ``asyncio.run``: ``pytest-asyncio`` is a dev
+dependency but is not installed in this venv.
+"""
+
+import asyncio
+import io
+import sys
+
+import pytest
+
+import condor.reports as reports
+from condor import code_runner
+from condor.code_runs import CodeRunStore
+from condor.reports import rendering
+
+
+class _FakeClient:
+    """Stands in for the cached HummingbotAPIClient the main process hands over."""
+
+
+@pytest.fixture
+def store(tmp_path, monkeypatch):
+    """A store under tmp_path, and a client that resolves without a server."""
+    written = CodeRunStore(tmp_path / "code_runs")
+    monkeypatch.setattr(code_runner, "get_code_run_store", lambda: written)
+
+    import config_manager
+
+    async def _client(*a, **kw):
+        return _FakeClient()
+
+    monkeypatch.setattr(config_manager, "get_client", _client)
+    return written
+
+
+@pytest.fixture
+def no_client(monkeypatch):
+    """No server resolves — the case a pure-pandas snippet must survive."""
+    import config_manager
+
+    async def _raise(*a, **kw):
+        raise ValueError("No servers configured")
+
+    monkeypatch.setattr(config_manager, "get_client", _raise)
+
+
+@pytest.fixture
+def reports_dir(tmp_path, monkeypatch):
+    monkeypatch.setattr(reports, "CHARTS_DIR", tmp_path / "reports")
+    monkeypatch.setattr(
+        reports, "INDEX_FILE", tmp_path / "reports" / "reports_index.json"
+    )
+    monkeypatch.setattr(
+        rendering, "plotly_script", lambda: "<script>window.Plotly={};</script>"
+    )
+    return tmp_path / "reports"
+
+
+def run(code: str, **kw) -> dict:
+    return asyncio.run(code_runner.execute_code(code, **kw))
+
+
+# ── the snippet contract ──
+
+
+def test_a_plain_snippet_prints_and_returns_its_result(store):
+    out = run("print('hello')\nresult = 1 + 1")
+
+    assert out["status"] == "ok"
+    assert out["stdout"] == "hello\n"
+    assert out["result"] == "2"
+    assert out["error"] == "" and out["traceback"] == ""
+
+
+def test_top_level_await_needs_no_boilerplate(store):
+    out = run("import asyncio\nawait asyncio.sleep(0)\nresult = 'awaited'")
+
+    assert out["status"] == "ok"
+    assert out["result"] == "awaited"
+
+
+def test_a_pandas_result_renders_as_the_value_not_its_repr(store):
+    out = run("import pandas as pd\nresult = pd.Series([1, 2, 3]).mean()")
+
+    assert out["status"] == "ok"
+    assert out["result"] == "2.0"
+
+
+def test_a_snippet_that_sets_no_result_reports_an_empty_one(store):
+    assert run("x = 5")["result"] == ""
+
+
+def test_the_snippet_reaches_the_routine_context(store):
+    """``context`` is the same object a routine gets, carrying its server."""
+    out = run(
+        "result = (type(context).__name__, context.server_name, type(client).__name__)",
+        server_name="prod",
+    )
+
+    assert out["result"] == "('WebRoutineContext', 'prod', '_FakeClient')"
+
+
+def test_a_missing_client_is_a_notice_in_stdout_not_a_failure(store, no_client):
+    out = run("result = client is None")
+
+    assert out["status"] == "ok"
+    assert out["result"] == "True"
+    assert "no API client available" in out["stdout"]
+
+
+# ── failure, readable by the model that wrote the code ──
+
+
+def test_an_error_traceback_starts_at_the_callers_own_line(store):
+    out = run("x = 1\ny = 2\nraise ValueError('boom')")
+
+    assert out["status"] == "error"
+    assert out["error"] == "ValueError: boom"
+    first_frame = [
+        line
+        for line in out["traceback"].splitlines()
+        if line.strip().startswith("File")
+    ][0]
+    assert '"<code_run>", line 3' in first_frame, out["traceback"]
+    assert "code_runner.py" not in out["traceback"], "harness frames must be trimmed"
+
+
+def test_a_syntax_error_is_a_recorded_run_not_a_raise(store):
+    out = run("def (:")
+
+    assert out["status"] == "error"
+    assert "SyntaxError" in out["error"]
+    assert "<code_run>" in out["traceback"]
+    assert store.get(out["id"]) is not None
+
+
+def test_a_failed_run_is_retrievable_whole_afterwards(store):
+    out = run("raise ZeroDivisionError('division by zero')")
+
+    stored = store.get(out["id"])
+    assert stored["traceback"] == out["traceback"]
+    assert stored["code"] == "raise ZeroDivisionError('division by zero')"
+
+
+def test_a_timeout_is_cut_and_keeps_what_was_printed(store):
+    out = run(
+        "import asyncio\nprint('before')\nawait asyncio.sleep(30)\nprint('after')",
+        timeout=1,
+    )
+
+    assert out["status"] == "timeout"
+    assert "before" in out["stdout"]
+    assert "after" not in out["stdout"]
+    assert "Timed out after 1s" in out["error"]
+
+
+# ── capture isolation ──
+
+
+def test_concurrent_runs_do_not_read_each_others_output(store):
+    async def both():
+        return await asyncio.gather(
+            code_runner.execute_code(
+                "import asyncio\nprint('A1')\nawait asyncio.sleep(0.05)\nprint('A2')",
+                label="a",
+            ),
+            code_runner.execute_code(
+                "import asyncio\nprint('B1')\nawait asyncio.sleep(0.05)\nprint('B2')",
+                label="b",
+            ),
+        )
+
+    first, second = asyncio.run(both())
+
+    assert first["stdout"] == "A1\nA2\n"
+    assert second["stdout"] == "B1\nB2\n"
+
+
+def test_the_process_stdout_is_untouched_before_during_and_after(store):
+    real = io.StringIO()
+    original = sys.stdout
+    sys.stdout = real
+    try:
+        print("before the run")
+        out = run("print('inside the run')")
+        print("after the run")
+    finally:
+        sys.stdout = original
+
+    assert out["stdout"] == "inside the run\n"
+    assert real.getvalue() == "before the run\nafter the run\n"
+
+
+def test_installing_the_proxy_twice_does_not_stack_it(store):
+    original = sys.stdout
+    try:
+        code_runner._install_stdout_proxy()
+        once = sys.stdout
+        code_runner._install_stdout_proxy()
+        assert sys.stdout is once
+    finally:
+        sys.stdout = original
+
+
+# ── reports ──
+
+
+def test_a_snippet_that_saves_a_report_gets_a_report_id(store, reports_dir):
+    out = run(
+        "from condor.reports import ReportBuilder\n"
+        "r = ReportBuilder('Snippet report')\n"
+        "r.markdown('hi')\n"
+        "result = await r.save()",
+        agent="quant",
+        label="funding drift",
+    )
+
+    assert out["status"] == "ok"
+    assert out["report_id"] and out["report_id"] == out["result"]
+
+    entry = reports.list_reports()[0][0]
+    assert entry["agent"] == "quant"
+    assert entry["source_type"] == "code"
+    assert entry["source_name"] == "funding drift"
+
+
+def test_a_report_saved_before_a_failure_is_still_reported(store, reports_dir):
+    out = run(
+        "from condor.reports import ReportBuilder\n"
+        "r = ReportBuilder('Half a report')\n"
+        "r.markdown('hi')\n"
+        "await r.save()\n"
+        "raise RuntimeError('after the save')"
+    )
+
+    assert out["status"] == "error"
+    assert out["report_id"], "the id is read in a finally, not on the happy path"
+
+
+# ── persistence ──
+
+
+def test_every_run_lands_in_the_store_newest_first(store):
+    run("result = 1", label="first")
+    run("result = 2", label="second")
+
+    assert [e["label"] for e in store.list()] == ["second", "first"]
+    assert store.list()[0]["status"] == "ok"
+
+
+def test_the_run_records_its_provenance(store):
+    out = run(
+        "pass",
+        agent="quant",
+        label="probe",
+        server_name="prod",
+        session_key="web:7:slot-1",
+    )
+
+    stored = store.get(out["id"])
+    assert stored["agent"] == "quant"
+    assert stored["label"] == "probe"
+    assert stored["server"] == "prod"
+    assert stored["session_key"] == "web:7:slot-1"
+    assert stored["duration_ms"] >= 0
diff --git a/tests/test_code_runs_store.py b/tests/test_code_runs_store.py
new file mode 100644
index 00000000..66267200
--- /dev/null
+++ b/tests/test_code_runs_store.py
@@ -0,0 +1,118 @@
+"""The code-run store keeps every snippet whole, and bounded (FEAT-047).
+
+Two properties matter here and nothing else does. A run must come back
+*complete* — a traceback the model has to read to fix its snippet is useless
+clipped — and the pile must stay bounded, because a snippet that printed a
+credential is on disk until the cap evicts it.
+"""
+
+import json
+
+import pytest
+
+from condor.code_runs import CodeRun, CodeRunStore, new_run_id
+
+
+@pytest.fixture
+def store(tmp_path):
+    return CodeRunStore(tmp_path / "code_runs")
+
+
+def _run(
+    store_id: str, *, agent: str = "condor", created: float = 1.0, **kw
+) -> CodeRun:
+    return CodeRun(id=store_id, created=created, agent=agent, **kw)
+
+
+def test_round_trip_keeps_the_whole_record(store):
+    run = _run(
+        "code_1_aaaa",
+        label="returns of SOL",
+        server="prod",
+        status="error",
+        duration_ms=42,
+        code="raise ValueError('boom')",
+        stdout="x" * 9000,
+        result="",
+        error="ValueError: boom",
+        traceback='File "<code_run>", line 1',
+        report_id="rep_1",
+        session_key="web:7:slot-1",
+    )
+    store.save(run)
+
+    got = store.get("code_1_aaaa")
+    assert got == run.to_dict()
+    assert len(got["stdout"]) == 9000, "the store never clips — the caller does"
+
+
+def test_get_is_none_for_an_unknown_run(store):
+    assert store.get("code_nope") is None
+
+
+def test_list_is_newest_first_and_index_only(store, tmp_path):
+    for i in range(3):
+        store.save(_run(f"code_{i}_a", created=float(i), label=f"run {i}", code="x=1"))
+
+    listed = store.list()
+    assert [e["id"] for e in listed] == ["code_2_a", "code_1_a", "code_0_a"]
+    assert "code" not in listed[0], "history carries meta, not bodies"
+    assert listed[0]["label"] == "run 2"
+
+
+def test_list_filters_by_agent_and_honors_limit(store):
+    store.save(_run("code_1_a", agent="condor"))
+    store.save(_run("code_2_a", agent="quant"))
+    store.save(_run("code_3_a", agent="quant"))
+
+    assert [e["id"] for e in store.list(agent="quant")] == ["code_3_a", "code_2_a"]
+    assert [e["id"] for e in store.list(agent="quant", limit=1)] == ["code_3_a"]
+    assert len(store.list()) == 3
+
+
+def test_cap_evicts_the_oldest_file_and_its_index_entry(store, tmp_path, monkeypatch):
+    monkeypatch.setattr("condor.code_runs.MAX_RUNS", 3)
+    for i in range(5):
+        store.save(_run(f"code_{i}_a", created=float(i)))
+
+    assert [e["id"] for e in store.list(limit=99)] == [
+        "code_4_a",
+        "code_3_a",
+        "code_2_a",
+    ]
+    assert store.get("code_0_a") is None
+    assert not (tmp_path / "code_runs" / "code_0_a.json").exists()
+    assert (tmp_path / "code_runs" / "code_4_a.json").exists()
+
+
+def test_index_survives_a_new_store_over_the_same_dir(tmp_path):
+    first = CodeRunStore(tmp_path / "code_runs")
+    first.save(_run("code_1_a", label="kept"))
+
+    second = CodeRunStore(tmp_path / "code_runs")
+    assert [e["label"] for e in second.list()] == ["kept"]
+    assert second.get("code_1_a")["label"] == "kept"
+
+
+def test_a_corrupt_index_starts_empty_instead_of_raising(tmp_path):
+    path = tmp_path / "code_runs"
+    path.mkdir()
+    (path / "_index.json").write_text("{not json")
+
+    assert CodeRunStore(path).list() == []
+
+
+def test_a_run_id_can_never_escape_the_store_dir(store, tmp_path):
+    """Ids arrive from a tool argument, so the shape check is load-bearing."""
+    outside = tmp_path / "secret.json"
+    outside.write_text(json.dumps({"token": "hunter2"}))
+
+    assert store.get("../secret") is None
+    assert store.get("/etc/passwd") is None
+    assert store.get("") is None
+
+
+def test_new_run_id_is_unique_and_well_formed():
+    ids = {new_run_id() for _ in range(50)}
+    assert len(ids) == 50
+    assert all(i.startswith("code_") and i.count("_") == 2 for i in ids)

From 613e68f9578b166f1a52ff5cf98f671dc693066d Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Thu, 13 Aug 2026 23:42:04 +0300
Subject: [PATCH 051/116] (feat) run_code: hand the scratchpad to the assistant
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The same split tools/routines.py already makes: reading history is local
to the MCP subprocess, executing crosses to the main process over
call_main_api, because that is where the clients, the report index's
single writer and the bot are.

POST /api/v1/code/run runs the snippet as the authenticated caller — the
chat id is never taken from the body, since it is what resolves the
snippet's client. The tool clips stdout/result for the model's context
and points at action="get" for the full record the store always keeps.

Every seat (chat, worker, agent) is told the same thing: a one-off
computation is a snippet, not a file; promote it to a routine once it
repeats or needs scheduling. The routine cookbook says the mirror of it.
---
 .../_shared/skills/routine_cookbook/SKILL.md  |  18 +
 condor/web/app.py                             |   2 +
 condor/web/routes/code.py                     |  66 ++++
 mcp_servers/condor/server.py                  |  85 +++++
 mcp_servers/condor/tools/code.py              | 143 ++++++++
 tests/test_code_run_tool.py                   | 347 ++++++++++++++++++
 6 files changed, 661 insertions(+)
 create mode 100644 condor/web/routes/code.py
 create mode 100644 mcp_servers/condor/tools/code.py
 create mode 100644 tests/test_code_run_tool.py

diff --git a/agents/_shared/skills/routine_cookbook/SKILL.md b/agents/_shared/skills/routine_cookbook/SKILL.md
index 0cf7d335..bc2b53bb 100644
--- a/agents/_shared/skills/routine_cookbook/SKILL.md
+++ b/agents/_shared/skills/routine_cookbook/SKILL.md
@@ -29,6 +29,24 @@ Most routines need `report_builder.md` plus one or two others. A continuous
 price monitor with a live dashboard, for example, reads `hummingbot_client.md`
 + `continuous.md`.
 
+## First: is this a routine at all?
+
+A routine is a **durable artifact** — it has a name, a config schema, a place in
+the library, and it can be scheduled, shared and re-run by anyone. That is worth
+a file when the work repeats.
+
+A **one-off computation** is not. "What were SOL's hourly returns yesterday",
+"what is the spread between these two venues right now", "aggregate these
+executors by controller" — write the Python and call
+`run_code(code="...")`. It runs in the bot with exactly the primitives below
+(`context`, `client`, pandas, `ReportBuilder`, every `condor.*` module), returns
+its `print` output and its `result`, and hands you the traceback to fix when it
+fails. No file, no `Config` class, no library entry.
+
+Promote a snippet to a routine when you have run essentially the same thing a
+third time, or the moment it needs to be scheduled, shared, or visible to the
+user.
+
 ## Where the routine lives
 
 **Agent-local** — `agents/{slug}/routines/` — visible only to that agent, and
diff --git a/condor/web/app.py b/condor/web/app.py
index 40b47299..71ae9d9f 100644
--- a/condor/web/app.py
+++ b/condor/web/app.py
@@ -17,6 +17,7 @@
     backtesting,
     bots,
     chat_ws,
+    code,
     confirmations,
     controller_performance,
     conversations,
@@ -87,6 +88,7 @@ def create_app() -> FastAPI:
     app.include_router(ws.router, prefix="/api/v1")
     app.include_router(agents.router, prefix="/api/v1")
     app.include_router(routines.router, prefix="/api/v1")
+    app.include_router(code.router, prefix="/api/v1")
     app.include_router(reports.router, prefix="/api/v1")
     app.include_router(settings.router, prefix="/api/v1")
     app.include_router(sessions.router, prefix="/api/v1")
diff --git a/condor/web/routes/code.py b/condor/web/routes/code.py
new file mode 100644
index 00000000..08e463cd
--- /dev/null
+++ b/condor/web/routes/code.py
@@ -0,0 +1,66 @@
+"""Ad-hoc code execution — the crossing into the main process (FEAT-047).
+
+The MCP subprocess cannot run a snippet itself: the cached API clients, the
+report index's single writer and the real bot all live here. So ``run_code``
+POSTs its snippet to this route, exactly as ``manage_routines(action="run")``
+already delegates a routine run — same destination, same context, one pattern
+for the next reader of ``tools/code.py`` beside ``tools/routines.py``.
+
+There are no GET endpoints on purpose: history is read straight off disk by the
+subprocess, which shares the filesystem, just as routine CRUD is.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel
+
+from condor.code_runner import DEFAULT_TIMEOUT, MAX_TIMEOUT, execute_code
+from condor.web.auth import get_current_user
+from condor.web.models import WebUser
+from config_manager import get_config_manager
+
+log = logging.getLogger(__name__)
+router = APIRouter(prefix="/code", tags=["code"])
+
+
+class RunCodeRequest(BaseModel):
+    code: str
+    # The server the snippet's client resolves against. Empty is legal: a
+    # snippet that only needs pandas must not be refused for lack of a server.
+    server_name: str = ""
+    label: str = ""
+    timeout: float = DEFAULT_TIMEOUT
+    # Which assistant produced this run's reports, same field and same meaning
+    # as RunRequestV2.attribute_to.
+    attribute_to: str = ""
+    session_key: str = ""
+
+
+@router.post("/run")
+async def run_code(
+    body: RunCodeRequest,
+    user: WebUser = Depends(get_current_user),
+):
+    """Execute a Python snippet in this process and return its recorded run."""
+    if not body.code.strip():
+        raise HTTPException(400, "code is required")
+    if body.server_name:
+        cm = get_config_manager()
+        if not cm.has_server_access(user.id, body.server_name):
+            raise HTTPException(status_code=403, detail="No access")
+
+    return await execute_code(
+        body.code,
+        server_name=body.server_name,
+        agent=body.attribute_to,
+        label=body.label,
+        timeout=max(1.0, min(float(body.timeout or DEFAULT_TIMEOUT), MAX_TIMEOUT)),
+        # The caller's own id, never a value from the body: it is what resolves
+        # the snippet's client, so it must be the authenticated identity — the
+        # same one RoutineStore.execute runs a routine under.
+        chat_id=user.id,
+        session_key=body.session_key,
+    )
diff --git a/mcp_servers/condor/server.py b/mcp_servers/condor/server.py
index 37d41b7c..6eeb170e 100644
--- a/mcp_servers/condor/server.py
+++ b/mcp_servers/condor/server.py
@@ -9,6 +9,7 @@
 from condor.telemetry import taps as telemetry_taps
 from mcp_servers.condor.middleware import handle_errors
 from mcp_servers.condor.tools import available_models as available_models_tool
+from mcp_servers.condor.tools import code as code_tool
 from mcp_servers.condor.tools import consult as consult_tool
 from mcp_servers.condor.tools import context
 from mcp_servers.condor.tools import delegate as delegate_tool
@@ -22,6 +23,23 @@
     trading_agent,
 )
 
+# FEAT-047: the branch above the routines one in cost — a one-off computation is
+# a snippet, not a file. Identical for every seat (chat, worker, agent), so it is
+# defined once and spliced into all three routing texts.
+_RUN_CODE_RULE = (
+    "- FOR A ONE-OFF COMPUTATION OVER DATA — candles → returns → filter, a "
+    "spread across venues, a quick aggregation — write it as Python and call "
+    '`run_code(code="...")` instead of chaining raw tools and doing the '
+    "arithmetic by hand. It runs in the bot with the same primitives a routine "
+    "has (`context`, `client`, pandas, `ReportBuilder`, every `condor.*` "
+    "module); `print()` is the output and an optional `result` variable is the "
+    "return value. On failure it returns the traceback — fix the snippet and "
+    "re-run. Keep snippets short and `await` inside loops. If you have run "
+    "essentially the same snippet three times, or you want it scheduled or "
+    "shared, promote it to a routine with "
+    '`manage_routines(action="create_routine")`.\n'
+)
+
 _CHAT_ROUTINES_RULE = (
     "- ROUTINES ARE SPECIAL: any request to CREATE, EDIT, FIX, DEBUG, or "
     "design a routine MUST go to a background Condor worker — "
@@ -98,6 +116,7 @@ def _coordinator_base(routines_rule: str) -> str:
         'the user when finished), use `delegate(action="start", agent="<slug>", '
         'task="...")` instead and poll with `delegate(action="get", task_id="...")`.\n'
         f"{routines_rule}"
+        f"{_RUN_CODE_RULE}"
         "- Only fall back to raw tools when nothing matches.\n"
         "Anti-pattern: answering a domain request (deploy/tune an executor, analyze "
         "logs, author a routine) with a chain of raw `mcp-hummingbot`/`manage_*` "
@@ -178,6 +197,7 @@ def _agent_base(slug: str, name: str, worker: bool = False) -> str:
         '`manage_routines(action="run", name="X", config={})` instead of '
         "reimplementing it by hand.\n"
         f"{routines_rule}"
+        f"{_RUN_CODE_RULE}"
         f"{'' if worker else self_delegation_rule}"
         "- You MAY consult a PEER agent listed below for work outside your own "
         'domain (`consult(agent="<slug>", task="...", context="...")`, or '
@@ -454,6 +474,71 @@ async def manage_routines(
     )
 
 
+@mcp.tool()
+@handle_errors("run code")
+@telemetry_taps.tracked("run_code")
+async def run_code(
+    code: str | None = None,
+    action: str = "run",
+    label: str = "",
+    timeout: int | None = None,
+    run_id: str | None = None,
+    agent: str | None = None,
+    limit: int = 20,
+) -> dict:
+    """Run a Python snippet inside Condor and get its output back.
+
+    The scratchpad below a routine: for a ONE-OFF computation over data — fetch
+    candles, build a DataFrame, compute returns, filter the series — write the
+    Python instead of chaining raw tools and doing the arithmetic by hand. There
+    is no file to author and no config schema to declare.
+
+    The snippet is a plain script body running in the bot process with the same
+    primitives a routine has:
+    - top-level `await` works, with no wrapper function
+    - `print(...)` is the output (use `print`, not `logging` — logging is not
+      captured); an optional `result` variable is the return value
+    - `context` is the routine context (active server, bot, chat), `client` is
+      the Hummingbot API client for that server (None if none resolves)
+    - every `condor.*` module is importable, including
+      `from condor.reports import ReportBuilder` — a snippet that saves one
+      produces a real dashboard report and its id comes back as `report_id`
+
+    On failure you get `status="error"` and a traceback whose line numbers are
+    YOUR snippet's: read it, fix the code, run it again. Keep snippets short and
+    `await` inside loops — a snippet that never yields blocks the bot until the
+    timeout cuts it.
+
+    Run essentially the same snippet a third time, or want it scheduled, shared
+    or visible to the user? Promote it to a routine with
+    `manage_routines(action="create_routine")`. That is the durable artifact;
+    this is the scratchpad.
+
+    Actions:
+    - "run" (default): execute `code` and wait for it (requires code)
+    - "history": list recent runs, newest first, with label and status
+    - "get": read one past run back in full — code, stdout, result, traceback
+      (requires run_id)
+
+    Args:
+        action: run | history | get.
+        code: The Python snippet to execute (for "run").
+        label: Short purpose of the run ("returns of SOL 1h"), shown in history
+            and used as the report source name.
+        timeout: Seconds to allow the snippet (for "run"). Default 60, max 120.
+        run_id: Id of a past run (for "get").
+        agent: Whose runs to list (for "history"). Defaults to your own; pass
+            "all" for every assistant's.
+        limit: How many runs to list (for "history"). Default 20.
+
+    Returns:
+        For "run": {run_id, status: ok|error|timeout, stdout, result, error,
+        traceback, report_id, duration_ms}. Long stdout/result are clipped with
+        "truncated": true — read the whole run with action="get".
+    """
+    return await code_tool.run_code(code, action, label, timeout, run_id, agent, limit)
+
+
 @mcp.tool()
 @handle_errors("manage servers")
 @telemetry_taps.tracked("manage_servers")
diff --git a/mcp_servers/condor/tools/code.py b/mcp_servers/condor/tools/code.py
new file mode 100644
index 00000000..f4958f3d
--- /dev/null
+++ b/mcp_servers/condor/tools/code.py
@@ -0,0 +1,143 @@
+"""Ad-hoc Python execution — the scratchpad below a routine (FEAT-047).
+
+Same split as ``tools/routines.py``, for the same reason: reading history is
+local (this subprocess shares the filesystem), *executing* is not. A snippet
+must run where the cached API clients, the report index's single writer and the
+real bot are, so ``run`` crosses to the main process over ``call_main_api`` and
+everything else reads ``data/code_runs/`` directly.
+
+What the model gets back is clipped; what the store keeps never is. A snippet
+that failed is read back whole with ``action="get"``, corrected, and re-run —
+which is the whole point of persisting these at all.
+"""
+
+from mcp_servers.condor.condor_client import call_main_api
+from mcp_servers.condor.settings import settings
+
+# Snippet budget. The main process clamps to the same ceiling; this copy exists
+# so a bad `timeout` is corrected before it becomes an HTTP deadline.
+DEFAULT_TIMEOUT = 60
+MAX_TIMEOUT = 120
+
+# Slack over the snippet's own budget, so the HTTP call never gives up on a run
+# the main process is still cutting short itself — a timeout must come back as
+# a recorded run, not as an unreachable-API error.
+_HTTP_MARGIN = 15
+
+# Per-field ceiling in the tool's *reply*. Enough for a table or a traceback,
+# small enough that a runaway print loop cannot flood a context window.
+_CLIP = 4000
+
+
+def _caller_slug() -> str:
+    """The assistant behind this subprocess, as reports and runs are stamped."""
+    from condor.memory.paths import CHAT_SLUG
+
+    return settings.specialist_slug or CHAT_SLUG
+
+
+def _store():
+    """A fresh store per call — the index is written by the *other* process.
+
+    A cached singleton here would answer ``history`` from whatever the index
+    held when this subprocess started, which for a long-lived session is every
+    run except the ones the caller just made.
+    """
+    from condor.code_runs import CodeRunStore
+
+    return CodeRunStore()
+
+
+def _clip(text: str) -> tuple[str, bool]:
+    text = text or ""
+    if len(text) <= _CLIP:
+        return text, False
+    return text[:_CLIP], True
+
+
+def _reply(run: dict) -> dict:
+    """The run as the caller sees it: clipped, with a pointer to the full copy."""
+    stdout, stdout_cut = _clip(run.get("stdout", ""))
+    result, result_cut = _clip(run.get("result", ""))
+    reply = {
+        "run_id": run.get("id", ""),
+        "status": run.get("status", ""),
+        "stdout": stdout,
+        "result": result,
+        "error": run.get("error", ""),
+        "traceback": run.get("traceback", ""),
+        "report_id": run.get("report_id", ""),
+        "duration_ms": run.get("duration_ms", 0),
+    }
+    if stdout_cut or result_cut:
+        reply["truncated"] = True
+        reply["note"] = (
+            f"Output was clipped at {_CLIP} chars. Read the full run with "
+            f"run_code(action='get', run_id='{reply['run_id']}')."
+        )
+    return reply
+
+
+async def run_snippet(code: str, label: str, timeout: int | None) -> dict:
+    """Execute a snippet in the main process and return its recorded run."""
+    if not (code or "").strip():
+        return {"error": "code is required for action='run'"}
+
+    budget = max(1, min(int(timeout or DEFAULT_TIMEOUT), MAX_TIMEOUT))
+    run = await call_main_api(
+        "POST",
+        "/code/run",
+        {
+            "code": code,
+            # Named, not required: a snippet that never touches a client runs
+            # fine without one, so a missing server is passed through rather
+            # than refused.
+            "server_name": settings.active_server or "",
+            "label": label or "",
+            "timeout": budget,
+            "attribute_to": _caller_slug(),
+            "session_key": settings.session_key,
+        },
+        timeout=budget + _HTTP_MARGIN,
+    )
+    if not isinstance(run, dict):
+        return {"error": f"Unexpected response from the code runner: {run}"}
+    return _reply(run)
+
+
+def list_runs(agent: str | None, limit: int) -> dict:
+    """Recent runs, newest first — the caller's own unless asked otherwise."""
+    scope = None if agent == "all" else (agent or _caller_slug())
+    return {
+        "agent": scope or "all",
+        "runs": _store().list(agent=scope, limit=max(1, min(int(limit or 20), 100))),
+    }
+
+
+def get_run(run_id: str | None) -> dict:
+    """One run in full — code, stdout, result and traceback, unclipped."""
+    if not run_id:
+        return {"error": "run_id is required for action='get'"}
+    run = _store().get(run_id)
+    if not run:
+        return {"error": f"No code run '{run_id}'"}
+    return run
+
+
+async def run_code(
+    code: str | None = None,
+    action: str = "run",
+    label: str = "",
+    timeout: int | None = None,
+    run_id: str | None = None,
+    agent: str | None = None,
+    limit: int = 20,
+) -> dict:
+    """Dispatch the tool's three actions."""
+    if action == "run":
+        return await run_snippet(code or "", label, timeout)
+    if action == "history":
+        return list_runs(agent, limit)
+    if action == "get":
+        return get_run(run_id)
+    return {"error": f"Unknown action '{action}'. Use run | history | get."}
diff --git a/tests/test_code_run_tool.py b/tests/test_code_run_tool.py
new file mode 100644
index 00000000..41dad91d
--- /dev/null
+++ b/tests/test_code_run_tool.py
@@ -0,0 +1,347 @@
+"""``run_code`` — the crossing, the clipping, and the guidance (FEAT-047).
+
+Execution belongs to the main process, so what this file pins on the tool side
+is the *delegation*: the right provenance leaves the subprocess, the HTTP
+deadline outlives the snippet's own budget (a timeout must come back as a
+recorded run, never as an unreachable-API error), and a flood of output is
+clipped for the model while the store keeps it whole.
+
+The route half pins the two things a shared execution endpoint must not get
+wrong: it is authenticated, and it runs the snippet as the caller.
+
+Sync tests driving coroutines with ``asyncio.run``: ``pytest-asyncio`` is a dev
+dependency but is not installed in this venv.
+"""
+
+import asyncio
+
+import pytest
+from fastapi import HTTPException
+
+from condor.code_runs import CodeRun, CodeRunStore
+from condor.web.models import WebUser
+from condor.web.routes import code as code_routes
+from condor.web.routes.code import RunCodeRequest
+from condor.web.routes.code import run_code as run_code_route
+from mcp_servers.condor.settings import settings
+from mcp_servers.condor.tools import code as code_tool
+
+CALLER = WebUser(id=7, role="user")
+
+
+@pytest.fixture
+def api(monkeypatch):
+    """Capture what the tool sends across to the main process."""
+    calls: list[dict] = []
+
+    async def _call(method, path, body=None, timeout=None):
+        calls.append({"method": method, "path": path, "body": body, "timeout": timeout})
+        return {
+            "id": "code_1_aaaa",
+            "status": "ok",
+            "stdout": "hi\n",
+            "result": "2",
+            "error": "",
+            "traceback": "",
+            "report_id": "rep_1",
+            "duration_ms": 12,
+        }
+
+    monkeypatch.setattr(code_tool, "call_main_api", _call)
+    return calls
+
+
+@pytest.fixture
+def seat(monkeypatch):
+    """A session with a server and a session key behind it."""
+    monkeypatch.setattr(settings, "agent_slug", "quant")
+    monkeypatch.setattr(settings, "active_server", "prod")
+    monkeypatch.setattr(settings, "session_key", "web:7:slot-1")
+
+
+@pytest.fixture
+def store(tmp_path, monkeypatch):
+    written = CodeRunStore(tmp_path / "code_runs")
+    monkeypatch.setattr(code_tool, "_store", lambda: written)
+    return written
+
+
+# ── run: the crossing ──
+
+
+def test_run_delegates_to_the_main_process_with_its_provenance(api, seat):
+    out = asyncio.run(code_tool.run_code(code="result = 2", label="probe"))
+
+    assert len(api) == 1
+    call = api[0]
+    assert (call["method"], call["path"]) == ("POST", "/code/run")
+    assert call["body"] == {
+        "code": "result = 2",
+        "server_name": "prod",
+        "label": "probe",
+        "timeout": 60,
+        "attribute_to": "quant",
+        "session_key": "web:7:slot-1",
+    }
+    assert out["run_id"] == "code_1_aaaa"
+    assert out["result"] == "2"
+    assert out["report_id"] == "rep_1"
+
+
+def test_the_http_deadline_outlives_the_snippets_own_budget(api, seat):
+    asyncio.run(code_tool.run_code(code="pass", timeout=90))
+
+    assert api[0]["body"]["timeout"] == 90
+    assert api[0]["timeout"] == 90 + code_tool._HTTP_MARGIN
+
+
+def test_a_timeout_above_the_cap_is_clamped(api, seat):
+    asyncio.run(code_tool.run_code(code="pass", timeout=9999))
+
+    assert api[0]["body"]["timeout"] == code_tool.MAX_TIMEOUT
+
+
+def test_the_chat_seat_attributes_runs_to_condor(api, monkeypatch):
+    monkeypatch.setattr(settings, "agent_slug", "condor")
+    monkeypatch.setattr(settings, "active_server", "prod")
+    monkeypatch.setattr(settings, "session_key", "")
+
+    asyncio.run(code_tool.run_code(code="pass"))
+
+    assert api[0]["body"]["attribute_to"] == "condor"
+
+
+def test_a_missing_server_is_passed_through_not_refused(api, monkeypatch):
+    """A pure-pandas snippet needs no server, so a missing one cannot block it."""
+    monkeypatch.setattr(settings, "agent_slug", "quant")
+    monkeypatch.setattr(settings, "active_server", "")
+    monkeypatch.setattr(settings, "session_key", "")
+
+    out = asyncio.run(code_tool.run_code(code="result = 1"))
+
+    assert api[0]["body"]["server_name"] == ""
+    assert not out["error"]
+
+
+def test_run_without_code_never_crosses(api, seat):
+    out = asyncio.run(code_tool.run_code(action="run", code="   "))
+
+    assert "error" in out and api == []
+
+
+def test_an_unknown_action_is_an_error(api, seat):
+    assert "error" in asyncio.run(code_tool.run_code(action="explode"))
+
+
+# ── clipping ──
+
+
+def test_long_output_is_clipped_for_the_model_with_a_pointer_to_the_full_run(
+    monkeypatch, seat
+):
+    async def _call(method, path, body=None, timeout=None):
+        return {
+            "id": "code_1_aaaa",
+            "status": "ok",
+            "stdout": "x" * 9000,
+            "result": "y" * 9000,
+            "duration_ms": 1,
+        }
+
+    monkeypatch.setattr(code_tool, "call_main_api", _call)
+    out = asyncio.run(code_tool.run_code(code="pass"))
+
+    assert len(out["stdout"]) == code_tool._CLIP
+    assert len(out["result"]) == code_tool._CLIP
+    assert out["truncated"] is True
+    assert "action='get'" in out["note"] and "code_1_aaaa" in out["note"]
+
+
+def test_short_output_carries_no_truncation_flag(api, seat):
+    assert "truncated" not in asyncio.run(code_tool.run_code(code="pass"))
+
+
+# ── history and get ──
+
+
+def _save(store, run_id, agent="quant", **kw):
+    store.save(CodeRun(id=run_id, created=1.0, agent=agent, **kw))
+
+
+def test_history_defaults_to_the_callers_own_runs(store, seat):
+    _save(store, "code_1_a", agent="quant", label="mine")
+    _save(store, "code_2_a", agent="condor", label="the chat's")
+
+    out = asyncio.run(code_tool.run_code(action="history"))
+
+    assert out["agent"] == "quant"
+    assert [r["label"] for r in out["runs"]] == ["mine"]
+
+
+def test_history_can_ask_for_every_assistants_runs(store, seat):
+    _save(store, "code_1_a", agent="quant")
+    _save(store, "code_2_a", agent="condor")
+
+    out = asyncio.run(code_tool.run_code(action="history", agent="all"))
+
+    assert len(out["runs"]) == 2 and out["agent"] == "all"
+
+
+def test_history_is_newest_first_and_honors_limit(store, seat):
+    _save(store, "code_1_a", label="older")
+    _save(store, "code_2_a", label="newer")
+
+    out = asyncio.run(code_tool.run_code(action="history", limit=1))
+
+    assert [r["label"] for r in out["runs"]] == ["newer"]
+
+
+def test_get_returns_the_full_record_unclipped(store, seat):
+    _save(
+        store,
+        "code_1_a",
+        code="print('x')",
+        stdout="z" * 9000,
+        status="error",
+        traceback='File "<code_run>", line 1',
+    )
+
+    out = asyncio.run(code_tool.run_code(action="get", run_id="code_1_a"))
+
+    assert out["code"] == "print('x')"
+    assert len(out["stdout"]) == 9000, "get is how a failed snippet is read back"
+    assert out["traceback"] == 'File "<code_run>", line 1'
+
+
+def test_get_without_an_id_or_for_an_unknown_run_is_an_error(store, seat):
+    assert "error" in asyncio.run(code_tool.run_code(action="get"))
+    assert "error" in asyncio.run(code_tool.run_code(action="get", run_id="code_x"))
+
+
+def test_history_rereads_the_index_the_main_process_writes(tmp_path, seat, monkeypatch):
+    """A cached store would answer with whatever existed at subprocess start."""
+    directory = tmp_path / "code_runs"
+    monkeypatch.setattr("condor.code_runs._DATA_DIR", directory)
+    CodeRunStore(directory)  # the reader's view at startup: empty
+
+    asyncio.run(code_tool.run_code(action="history"))  # warms nothing
+    CodeRunStore(directory).save(CodeRun(id="code_9_a", created=1.0, agent="quant"))
+
+    out = asyncio.run(code_tool.run_code(action="history"))
+    assert [r["id"] for r in out["runs"]] == ["code_9_a"]
+
+
+# ── the route ──
+
+
+def test_the_route_runs_the_snippet_as_the_authenticated_caller(monkeypatch):
+    seen: dict = {}
+
+    async def _execute(code, **kw):
+        seen.update({"code": code, **kw})
+        return {"id": "code_1_aaaa", "status": "ok"}
+
+    monkeypatch.setattr(code_routes, "execute_code", _execute)
+    monkeypatch.setattr(
+        code_routes, "get_config_manager", lambda: _FakeConfigManager(True)
+    )
+
+    body = RunCodeRequest(
+        code="result = 1",
+        server_name="prod",
+        label="probe",
+        timeout=30,
+        attribute_to="quant",
+        session_key="web:7:slot-1",
+    )
+    out = asyncio.run(run_code_route(body, user=CALLER))
+
+    assert out["id"] == "code_1_aaaa"
+    assert seen["chat_id"] == CALLER.id, "never a chat_id taken from the body"
+    assert seen["agent"] == "quant"
+    assert seen["server_name"] == "prod"
+    assert seen["label"] == "probe"
+    assert seen["timeout"] == 30
+    assert seen["session_key"] == "web:7:slot-1"
+
+
+class _FakeConfigManager:
+    def __init__(self, allowed: bool):
+        self.allowed = allowed
+
+    def has_server_access(self, user_id, server_name, *a, **kw):
+        return self.allowed
+
+
+def test_the_route_refuses_a_server_the_caller_cannot_reach(monkeypatch):
+    monkeypatch.setattr(
+        code_routes, "get_config_manager", lambda: _FakeConfigManager(False)
+    )
+
+    body = RunCodeRequest(code="result = 1", server_name="someone-elses")
+    with pytest.raises(HTTPException) as excinfo:
+        asyncio.run(run_code_route(body, user=CALLER))
+
+    assert excinfo.value.status_code == 403
+
+
+def test_the_route_rejects_an_empty_snippet(monkeypatch):
+    with pytest.raises(HTTPException) as excinfo:
+        asyncio.run(run_code_route(RunCodeRequest(code="  \n "), user=CALLER))
+
+    assert excinfo.value.status_code == 400
+
+
+def test_the_route_clamps_the_timeout_to_the_hard_cap(monkeypatch):
+    seen: dict = {}
+
+    async def _execute(code, **kw):
+        seen.update(kw)
+        return {}
+
+    monkeypatch.setattr(code_routes, "execute_code", _execute)
+    asyncio.run(run_code_route(RunCodeRequest(code="pass", timeout=9999), user=CALLER))
+
+    assert seen["timeout"] == code_routes.MAX_TIMEOUT
+
+
+def test_the_route_is_authenticated_like_every_other_router():
+    from condor.web.auth import get_current_user
+
+    route = next(r for r in code_routes.router.routes if r.path == "/code/run")
+    assert any(
+        d.call is get_current_user for d in route.dependant.dependencies
+    ), "an endpoint that executes arbitrary Python must never be anonymous"
+
+
+# ── guidance: the assistant has to be told this exists ──
+
+
+@pytest.mark.parametrize(
+    "instructions",
+    [
+        pytest.param(lambda s: s._chat_base(), id="chat"),
+        pytest.param(lambda s: s._worker_base(), id="worker"),
+        pytest.param(lambda s: s._agent_base("quant", "Quant"), id="agent"),
+        pytest.param(
+            lambda s: s._agent_base("quant", "Quant", worker=True), id="agent-worker"
+        ),
+    ],
+)
+def test_every_seat_is_told_to_reach_for_run_code(instructions):
+    from mcp_servers.condor import server
+
+    text = instructions(server)
+    assert "run_code" in text
+    assert "create_routine" in text, "and when to promote a snippet to a routine"
+
+
+def test_the_routine_cookbook_sends_one_offs_to_run_code():
+    from pathlib import Path
+
+    skill = (
+        Path(__file__).resolve().parent.parent
+        / "agents/_shared/skills/routine_cookbook/SKILL.md"
+    )
+    text = skill.read_text()
+    assert "run_code" in text, "the cookbook must not send a one-off to author a file"

From e45c3e0afdcaad28472ba52c0ae34c14392efbfd Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Fri, 14 Aug 2026 14:03:49 +0300
Subject: [PATCH 052/116] (fix) route bound_agent_context through the runtime
 client facade

The chart-fence contract test imported it straight from condor.runtime.sessions,
tripping the import-discipline guard and leaving the branch red.
---
 condor/runtime/client.py          | 5 +++++
 tests/test_chat_chart_contract.py | 2 +-
 2 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/condor/runtime/client.py b/condor/runtime/client.py
index 881f6e4b..1d50bd52 100644
--- a/condor/runtime/client.py
+++ b/condor/runtime/client.py
@@ -60,6 +60,11 @@ def _local():
     return sessions
 
 
+def bound_agent_context(bound, user_id: int, platform: str) -> str:
+    """Opening context for a chat bound to a specialist Agent."""
+    return _local().bound_agent_context(bound, user_id, platform)
+
+
 async def create_session(
     spec: SessionSpec,
     *,
diff --git a/tests/test_chat_chart_contract.py b/tests/test_chat_chart_contract.py
index 7be89507..7c6f0c0c 100644
--- a/tests/test_chat_chart_contract.py
+++ b/tests/test_chat_chart_contract.py
@@ -17,7 +17,7 @@
 import pytest
 
 from condor.runtime import binding
-from condor.runtime.sessions import bound_agent_context
+from condor.runtime.client import bound_agent_context
 from handlers.agents._shared import (
     _TELEGRAM_FORMATTING,
     _WEB_FORMATTING,

From db012df528e4227504b9bfb22d5bf3032fa1793b Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Fri, 14 Aug 2026 14:05:43 +0300
Subject: [PATCH 053/116] (refactor) agents: drop the inert inject_directive
 mechanism

`inject_directive` was the only writer of `_pending_directives` and had
zero callers anywhere -- no web route, no MCP tool, no Telegram handler,
nothing in frontend/src -- so the "USER DIRECTIVES" prompt-injection block
in `_tick` was unreachable. The adjacent `is_paused` property was likewise
never referenced (`status` reads `_paused` directly). Worse, the README
documented the feature as working, advertising an inert code path.

Removes the field, the method, the injection block, the unused property,
and the matching README section. Recoverable path if the feature is ever
wanted for real: add a POST .../directive route next to the existing
pause/resume routes in condor/web/routes/agents.py.

READ-157
---
 condor/agents/README.md | 12 ++----------
 condor/agents/engine.py | 16 ----------------
 2 files changed, 2 insertions(+), 26 deletions(-)

diff --git a/condor/agents/README.md b/condor/agents/README.md
index f140e4e9..33e7ca69 100644
--- a/condor/agents/README.md
+++ b/condor/agents/README.md
@@ -63,7 +63,7 @@ In short: executors give us the cleanest possible boundary between "what this ag
 | `engine.py` | `TickEngine` — one instance per running agent. Runs the tick loop, builds prompts, drives ACP sessions, captures tool calls, persists snapshots. |
 | `strategy.py` | `Strategy` + `StrategyStore`. Strategies live as `agent.md` files (YAML frontmatter + markdown body) under `agents/{slug}/`. |
 | `journal.py` | `JournalManager` — compact, human-readable per-session memory: summary, decisions, ticks, snapshots, executors. Also `learnings.md` cross-session. |
-| `prompts.py` | Builds the per-tick prompt: system prompt + strategy + provider summaries + journal context + risk state + user directives. |
+| `prompts.py` | Builds the per-tick prompt: system prompt + strategy + provider summaries + journal context + risk state. |
 | `risk.py` | `RiskEngine` + `RiskLimits`. Hard guardrails (max exposure, max drawdown, max open executors) and the permission callback that auto-approves tool calls only if they pass the risk check. |
 | `providers/` | Deterministic pre-tick data fetchers. Two core providers ship: `executors.py` (filtered by `controller_id`) and `positions.py` (positions summary, also filtered by `controller_id`). |
 | `config.py` | `AgentConfig` schema persisted per session. |
@@ -94,7 +94,7 @@ agents/
 2. **Run core providers** — currently `executors` and `positions`, both filtered by `controller_id == agent_id`. Their structured `data` is kept for tracking; their `summary` strings go into the prompt.
 3. **Read journal context** — `learnings.md`, `summary`, and the last 3 decisions.
 4. **Get risk state** from `RiskEngine` (exposure, drawdown, open count). If the agent is blocked, log it and return without invoking the LLM.
-5. **Build the prompt** via `build_tick_prompt(...)`, optionally appending any user directives queued via `inject_directive()`.
+5. **Build the prompt** via `build_tick_prompt(...)`.
 6. **Spawn an ACP session** for the strategy's `agent_key` (claude-code, gemini, copilot…) with MCP servers wired in (Hummingbot tools, market data, notifications, journal writes). Stream events, capture text and tool calls.
 7. **Persist** — for sessions, write `snapshot_N.md`, append a tick to the journal, and update the running summary. For dry-runs / run-once, write a flat `experiment_N.md`.
 
@@ -258,14 +258,6 @@ In production, agents are normally started/stopped from the Telegram `/agent` fl
 - `agents/{slug}/learnings.md` — lessons the agent has chosen to keep across sessions.
 - `agents/{slug}/dry_runs/experiment_N.md` — dry-run / run-once results.
 
-### 4.5 Injecting directives mid-flight
-
-```python
-engine.inject_directive("Reduce exposure, news event in 10 min.")
-```
-
-The next tick's prompt will include the directive verbatim under a `USER DIRECTIVES` section, then clear it.
-
 ---
 
 ## 5. Mental model
diff --git a/condor/agents/engine.py b/condor/agents/engine.py
index 923959e6..cfdbb3fc 100644
--- a/condor/agents/engine.py
+++ b/condor/agents/engine.py
@@ -108,7 +108,6 @@ class TickEngine:
     _last_tick_at: float = field(default=0.0, init=False)
     _last_error: str = field(default="", init=False)
     _last_skill_data: dict[str, Any] = field(default_factory=dict, init=False)
-    _pending_directives: list[str] = field(default_factory=list, init=False)
     _cached_routines_section: str | None = field(default=None, init=False, repr=False)
     _adoption_done: bool = field(default=False, init=False, repr=False)
     _mode_mismatch_noted: bool = field(default=False, init=False, repr=False)
@@ -351,19 +350,10 @@ def resume(self) -> None:
         self._paused = False
         _supervisor().record(self, LoopState.RUNNING)
 
-    def inject_directive(self, text: str) -> None:
-        """Queue a user directive to be included in the next tick's prompt."""
-        self._pending_directives.append(text)
-        log.info("TickEngine %s: directive queued: %s", self.agent_id, text[:80])
-
     @property
     def is_running(self) -> bool:
         return self._running and self._task is not None and not self._task.done()
 
-    @property
-    def is_paused(self) -> bool:
-        return self._paused
-
     @property
     def status(self) -> str:
         if not self._running:
@@ -586,12 +576,6 @@ async def _tick(self) -> None:
             canvas_nudge=canvas_nudge,
         )
 
-        # Inject pending user directives
-        if self._pending_directives:
-            directives = "\n".join(f"- {d}" for d in self._pending_directives)
-            prompt += f"\n\nUSER DIRECTIVES (apply these on this tick):\n{directives}"
-            self._pending_directives.clear()
-
         # 6. Create a fresh agent client per tick (clean context window)
         acp_client = await self._create_client(risk_state)
         self._active_client = acp_client

From 6252e4884a53e0ed07cd0c15afaaa34246683d68 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Fri, 14 Aug 2026 14:07:49 +0300
Subject: [PATCH 054/116] (refactor) server_data_service: drop the dead
 stale_threshold knob

DataTypeDefaults.stale_threshold had exactly one reader in get(), and
every one of the 15 _DEFAULTS entries set it strictly below its ttl, so
the `if age <= stale_threshold: return entry.value` branch was fully
subsumed by the `age <= ttl` return that followed it. The field never
changed behavior, yet its docstring advertised a three-tier freshness
model and all 15 registrations picked values for it.

Remove the field and its 15 kwargs, collapse get() to the single ttl
check, and drop the stale "without subscribers" wording on the ttl
comment (READ-066 removed that distinction). Pure cleanup, no behavior
change.

Closes READ-154.
---
 condor/server_data_service.py | 55 ++++++++++++-----------------------
 1 file changed, 18 insertions(+), 37 deletions(-)

diff --git a/condor/server_data_service.py b/condor/server_data_service.py
index 7223432d..b6ccd9ee 100644
--- a/condor/server_data_service.py
+++ b/condor/server_data_service.py
@@ -52,48 +52,33 @@ class ServerDataType(Enum):
 
 @dataclass(frozen=True)
 class DataTypeDefaults:
-    """Default interval, TTL, and stale threshold for a data type."""
+    """Default polling interval and cache TTL for a data type."""
 
     interval: float  # Default polling interval (seconds)
-    ttl: float  # How long cached data is considered valid without subscribers
-    stale_threshold: float  # Data younger than this is always returned
+    ttl: float  # How long cached data is considered valid
 
 
 _DEFAULTS: Dict[ServerDataType, DataTypeDefaults] = {
-    ServerDataType.PORTFOLIO: DataTypeDefaults(interval=10, ttl=60, stale_threshold=5),
-    ServerDataType.PRICES: DataTypeDefaults(interval=3, ttl=30, stale_threshold=2),
-    ServerDataType.POSITIONS: DataTypeDefaults(interval=10, ttl=60, stale_threshold=5),
-    ServerDataType.ACTIVE_ORDERS: DataTypeDefaults(
-        interval=10, ttl=60, stale_threshold=5
-    ),
-    ServerDataType.TRADING_RULES: DataTypeDefaults(
-        interval=300, ttl=600, stale_threshold=30
-    ),
-    ServerDataType.CONNECTORS: DataTypeDefaults(
-        interval=300, ttl=600, stale_threshold=30
-    ),
-    ServerDataType.BOTS_STATUS: DataTypeDefaults(interval=5, ttl=30, stale_threshold=3),
-    ServerDataType.EXECUTORS: DataTypeDefaults(interval=2, ttl=30, stale_threshold=1),
-    ServerDataType.BOT_RUNS: DataTypeDefaults(interval=30, ttl=120, stale_threshold=10),
-    ServerDataType.CANDLE_CONNECTORS: DataTypeDefaults(
-        interval=300, ttl=600, stale_threshold=30
-    ),
-    ServerDataType.SERVER_STATUS: DataTypeDefaults(
-        interval=60, ttl=120, stale_threshold=15
-    ),
-    ServerDataType.ALL_CONNECTORS: DataTypeDefaults(
-        interval=300, ttl=600, stale_threshold=30
-    ),
+    ServerDataType.PORTFOLIO: DataTypeDefaults(interval=10, ttl=60),
+    ServerDataType.PRICES: DataTypeDefaults(interval=3, ttl=30),
+    ServerDataType.POSITIONS: DataTypeDefaults(interval=10, ttl=60),
+    ServerDataType.ACTIVE_ORDERS: DataTypeDefaults(interval=10, ttl=60),
+    ServerDataType.TRADING_RULES: DataTypeDefaults(interval=300, ttl=600),
+    ServerDataType.CONNECTORS: DataTypeDefaults(interval=300, ttl=600),
+    ServerDataType.BOTS_STATUS: DataTypeDefaults(interval=5, ttl=30),
+    ServerDataType.EXECUTORS: DataTypeDefaults(interval=2, ttl=30),
+    ServerDataType.BOT_RUNS: DataTypeDefaults(interval=30, ttl=120),
+    ServerDataType.CANDLE_CONNECTORS: DataTypeDefaults(interval=300, ttl=600),
+    ServerDataType.SERVER_STATUS: DataTypeDefaults(interval=60, ttl=120),
+    ServerDataType.ALL_CONNECTORS: DataTypeDefaults(interval=300, ttl=600),
     # Venue traits follow the CONNECTORS cadence, not the "chains change ~never"
     # one: the credentialed connector list is one of the inputs, so the answer
     # changes the moment a user adds API keys.
-    ServerDataType.VENUES: DataTypeDefaults(interval=300, ttl=600, stale_threshold=30),
-    ServerDataType.TICKERS: DataTypeDefaults(interval=60, ttl=180, stale_threshold=30),
+    ServerDataType.VENUES: DataTypeDefaults(interval=300, ttl=600),
+    ServerDataType.TICKERS: DataTypeDefaults(interval=60, ttl=180),
     # Whole-server ticker pool: one poll feeds every per-connector ticker view and
     # all currency conversion, so reads never hit the network.
-    ServerDataType.TICKER_POOL: DataTypeDefaults(
-        interval=60, ttl=300, stale_threshold=60
-    ),
+    ServerDataType.TICKER_POOL: DataTypeDefaults(interval=60, ttl=300),
 }
 
 
@@ -378,11 +363,7 @@ def get(self, server: str, data_type: ServerDataType, **params) -> Optional[Any]
         defaults = _DEFAULTS[data_type]
         age = time.time() - entry.fetched_at
 
-        # Always return if within stale threshold
-        if age <= defaults.stale_threshold:
-            return entry.value
-
-        # Past the stale threshold: still usable until the TTL expires
+        # Cached data is usable until the TTL expires
         return entry.value if age <= defaults.ttl else None
 
     async def get_or_fetch(

From d99cad41e5098df45be6a14e20471af2a1f0cb27 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Fri, 14 Aug 2026 14:12:18 +0300
Subject: [PATCH 055/116] (fix) keep a kill-switched session dead past the tick
 that killed it
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The hard risk kill-switch escalates from inside the tick: _run_shutdown winds
the session down, records the terminal stopped state and unregisters the run,
but it must not cancel its own task, so _loop resumes right after it and ran
the post-tick bookkeeping unconditionally. record_tick then wrote state=running
over that stopped, and the file stayed that way — the loop exits without
another write. On the next boot, reconcile_boot read a live run with a foreign
boot id, marked it interrupted and, when the session had restart_on_boot,
restarted the very strategy the risk engine had just emergency-wound-down.

_loop now returns as soon as a tick leaves the engine shutting down or no
longer running, before any bookkeeping. As defense in depth, record_tick is a
no-op for an engine that already left the registry, so no future exit path can
resurrect a final state to RUNNING either.
---
 condor/agents/engine.py                       |  10 +
 condor/runtime/loops.py                       |  10 +-
 ...test_kill_switch_status_not_resurrected.py | 190 ++++++++++++++++++
 3 files changed, 209 insertions(+), 1 deletion(-)
 create mode 100644 tests/test_kill_switch_status_not_resurrected.py

diff --git a/condor/agents/engine.py b/condor/agents/engine.py
index cfdbb3fc..5d586b6a 100644
--- a/condor/agents/engine.py
+++ b/condor/agents/engine.py
@@ -383,6 +383,16 @@ async def _loop(self) -> None:
                         self.journal.append_error(str(e))
                     await self._notify(f"Agent {self.agent_id} tick error: {e}")
 
+                # A shutdown that started *inside* the tick (the hard risk
+                # kill-switch) already ran its winddown, wrote the terminal
+                # state and unregistered this run — it only returns here
+                # because it must not cancel its own task. Recording a tick
+                # now would rewrite state=running over that STOPPED, and the
+                # next boot would read a live run to reconcile and possibly
+                # restart the very strategy the risk engine just wound down.
+                if self._shutting_down or not self._running:
+                    return
+
                 # Record the tick we just finished. A tiny atomic write, so if
                 # the process dies mid-sleep the boot pass can say which tick
                 # this run reached instead of guessing.
diff --git a/condor/runtime/loops.py b/condor/runtime/loops.py
index 7ed36a9e..6716f6fa 100644
--- a/condor/runtime/loops.py
+++ b/condor/runtime/loops.py
@@ -136,7 +136,15 @@ def record(self, engine, state: str) -> None:
         )
 
     def record_tick(self, engine) -> None:
-        """Cheap per-tick counter update; keeps the last tick honest on a crash."""
+        """Cheap per-tick counter update; keeps the last tick honest on a crash.
+
+        Never for an engine that already left the registry: stop/shutdown wrote
+        its final state on the way out, and rewriting RUNNING over it would make
+        the next boot read a finished run as interrupted — and restart it when
+        the session opted into ``restart_on_boot``.
+        """
+        if self._engines.get(engine.agent_id) is not engine:
+            return
         self.record(engine, LoopState.RUNNING)
 
     # ── Lifecycle ──
diff --git a/tests/test_kill_switch_status_not_resurrected.py b/tests/test_kill_switch_status_not_resurrected.py
new file mode 100644
index 00000000..83c44961
--- /dev/null
+++ b/tests/test_kill_switch_status_not_resurrected.py
@@ -0,0 +1,190 @@
+"""Regression tests for CORR-139 — the kill switch must stay killed.
+
+When the hard risk kill-switch fires *inside* a tick, ``_run_shutdown`` winds the
+session down and records the terminal ``stopped`` state, but it deliberately does
+not cancel its own task, so ``_loop`` resumes right after it. It used to run the
+post-tick bookkeeping unconditionally, and ``record_tick`` rewrote ``running``
+over that ``stopped`` — leaving a session that the next boot read as an
+interrupted live run and, with ``restart_on_boot``, restarted the very strategy
+the risk engine had just emergency-wound-down.
+"""
+
+import asyncio
+import json
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+
+from condor.agents import engine as engine_module
+from condor.agents import shutdown as shutdown_module
+from condor.agents.engine import TickEngine
+from condor.runtime.loops import LoopSupervisor
+from condor.runtime.registry_file import LoopState, read_status
+
+FOREIGN_BOOT = "00000000-dead-beef-0000-000000000000"
+
+
+class _FakeJournal:
+    def __init__(self):
+        self.tick_count = 3
+        self.closed = False
+
+    def close(self):
+        self.closed = True
+
+    def append_error(self, msg):
+        pass
+
+
+def _session_dir(agents_root: Path) -> Path:
+    d = agents_root / "acme" / "strategies" / "scalper" / "sessions" / "session_1"
+    d.mkdir(parents=True, exist_ok=True)
+    (d / "journal.md").write_text("# Journal\n\n## Decisions\n\n")
+    return d
+
+
+def _stub_engine(session_dir: Path, *, restart_on_boot=True, mode="loop"):
+    """A stand-in carrying exactly what ``_loop``/``_run_shutdown`` touch."""
+    return SimpleNamespace(
+        agent_id="acme.scalper_1",
+        agent=SimpleNamespace(slug="acme"),
+        strategy=SimpleNamespace(slug="scalper"),
+        session_num=1,
+        session_dir=session_dir,
+        chat_id=555,
+        user_id=4242,
+        journal=_FakeJournal(),
+        ledger=None,
+        config={
+            "frequency_sec": 0,
+            "execution_mode": mode,
+            "restart_on_boot": restart_on_boot,
+        },
+        _running=True,
+        _paused=False,
+        _shutting_down=False,
+        _task=None,
+        _active_client=None,
+        _last_error="",
+        _last_stop_reason="",
+        _notify=_swallow,
+    )
+
+
+async def _swallow(msg):
+    pass
+
+
+@pytest.fixture
+def supervisor(monkeypatch):
+    """A fresh supervisor wired into the engine module."""
+    sup = LoopSupervisor()
+    monkeypatch.setattr(engine_module, "_supervisor", lambda: sup)
+    return sup
+
+
+@pytest.fixture
+def no_op_winddown(monkeypatch):
+    """The winddown itself is FEAT-007's business; here only bookkeeping matters."""
+
+    async def fake_run_shutdown(engine, reason):
+        return None
+
+    monkeypatch.setattr(shutdown_module, "run_shutdown", fake_run_shutdown)
+
+
+def _run_loop_with_in_tick_shutdown(stub, supervisor):
+    """Drive one tick that trips the kill switch, exactly as ``_tick`` does."""
+    supervisor.register(stub)
+
+    async def _tick():
+        # Mirrors engine._tick: hard kill-switch escalates, then returns.
+        await TickEngine._run_shutdown(stub, "max drawdown breached")
+
+    stub._tick = _tick
+    asyncio.run(TickEngine._loop(stub))
+
+
+def test_in_tick_shutdown_leaves_status_stopped(tmp_path, supervisor, no_op_winddown):
+    """The post-tick bookkeeping must not resurrect a shut-down session."""
+    session_dir = _session_dir(tmp_path)
+    stub = _stub_engine(session_dir)
+
+    _run_loop_with_in_tick_shutdown(stub, supervisor)
+
+    assert read_status(session_dir)["state"] == LoopState.STOPPED
+    assert supervisor.all() == {}
+    assert stub._shutting_down is True
+    assert stub._running is False
+
+
+def test_record_tick_after_unregister_is_a_no_op(tmp_path, supervisor):
+    """Defense in depth: no exit path can rewrite RUNNING over a final state."""
+    session_dir = _session_dir(tmp_path)
+    stub = _stub_engine(session_dir)
+
+    supervisor.register(stub)
+    supervisor.unregister(stub.agent_id, LoopState.STOPPED)
+    before = read_status(session_dir)
+
+    supervisor.record_tick(stub)
+
+    assert read_status(session_dir) == before
+    assert read_status(session_dir)["state"] == LoopState.STOPPED
+
+
+def test_boot_does_not_restart_a_kill_switched_session(
+    tmp_path, supervisor, no_op_winddown
+):
+    """A next boot sees a finished run: nothing interrupted, nothing restarted."""
+    session_dir = _session_dir(tmp_path)
+    stub = _stub_engine(session_dir, restart_on_boot=True)
+
+    _run_loop_with_in_tick_shutdown(stub, supervisor)
+
+    # Simulate the next process boot: the status file this run left behind now
+    # carries a foreign boot id, which is the only thing that changes on reboot.
+    status = json.loads((session_dir / "status.json").read_text())
+    assert status["restart_on_boot"] is True  # the opt-in that made this dangerous
+    status["boot_id"] = FOREIGN_BOOT
+    (session_dir / "status.json").write_text(json.dumps(status))
+
+    restarts = []
+
+    async def _never(status_dict):
+        restarts.append(status_dict)
+        return True
+
+    supervisor._restart = _never
+    report = asyncio.run(supervisor.reconcile_boot(tmp_path))
+
+    assert report.interrupted == []
+    assert report.restarted == []
+    assert restarts == []
+
+
+def test_normal_tick_still_records_running(tmp_path, supervisor):
+    """The guard is for terminal states only — a healthy tick still records."""
+    session_dir = _session_dir(tmp_path)
+    stub = _stub_engine(session_dir, mode="run_once")
+
+    states = []
+    real_record = supervisor.record
+
+    def spy(engine, state):
+        states.append(state)
+        real_record(engine, state)
+
+    supervisor.record = spy
+
+    async def _tick():
+        stub.journal.tick_count += 1
+
+    stub._tick = _tick
+    supervisor.register(stub)
+    asyncio.run(TickEngine._loop(stub))
+
+    # register → post-tick record_tick → single-tick completion.
+    assert states == [LoopState.RUNNING, LoopState.RUNNING, LoopState.COMPLETED]
+    assert read_status(session_dir)["tick"] == 4

From b44ab0e57c95b5bfbf4768f3b5c2bf0f306fb559 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Fri, 14 Aug 2026 14:15:21 +0300
Subject: [PATCH 056/116] (fix) cancel the turn at the agent when the prompt
 times out
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

PROMPT_OVERALL_TIMEOUT only stopped us relaying: the agent kept
generating and kept running tools against a permission callback nobody
was watching, and the freed lock let the next prompt overlap it at the
subprocess. Send session/cancel from the timeout branch, exactly as
abort() does — bounded by TIMEOUTS.prompt_cancel with a local fallback.
---
 condor/runtime/sessions.py          | 15 ++++++++++
 tests/runtime/test_prompt_cancel.py | 46 ++++++++++++++++++++++++++++-
 2 files changed, 60 insertions(+), 1 deletion(-)

diff --git a/condor/runtime/sessions.py b/condor/runtime/sessions.py
index 697ac0eb..b61ce48b 100644
--- a/condor/runtime/sessions.py
+++ b/condor/runtime/sessions.py
@@ -159,6 +159,21 @@ async def prompt_stream(self, text: str, *, lock_timeout: float | None = None):
                         PROMPT_OVERALL_TIMEOUT,
                         self.key,
                     )
+                    # Cancel at the agent before walking away, exactly as
+                    # abort() does. Breaking out only stops us *relaying*: the
+                    # turn would keep generating and keep running tools against
+                    # a permission callback nobody is watching, and the next
+                    # prompt would overlap it at the subprocess. Bounded by
+                    # TIMEOUTS.prompt_cancel with a local fallback, so this
+                    # cannot hang the caller.
+                    try:
+                        await self.client.abort_prompt()
+                    except Exception:  # noqa: BLE001 - never mask the timeout
+                        log.warning(
+                            "Could not cancel timed-out prompt for session %s",
+                            self.key,
+                            exc_info=True,
+                        )
                     yield PromptDone(stop_reason="timeout")
                     break
         finally:
diff --git a/tests/runtime/test_prompt_cancel.py b/tests/runtime/test_prompt_cancel.py
index 70854014..626d03dc 100644
--- a/tests/runtime/test_prompt_cancel.py
+++ b/tests/runtime/test_prompt_cancel.py
@@ -14,7 +14,7 @@
 from contextlib import asynccontextmanager
 from dataclasses import replace
 
-from condor.acp.client import ACPClient, PromptDone
+from condor.acp.client import ACPClient, PromptDone, TextChunk
 from condor.acp.pydantic_ai_client import PydanticAIClient
 from condor.runtime import SessionKey
 from condor.runtime import sessions as session_module
@@ -277,3 +277,47 @@ async def scenario():
 
     assert events[-1].stop_reason == "end_turn"
     assert run.consumed == 2
+
+
+# ── the session-level wall-clock timeout also cancels at the agent (CORR-140) ──
+
+
+def test_prompt_overall_timeout_aborts_the_turn_at_the_agent(monkeypatch):
+    """A runaway prompt is killed, not just stopped being listened to.
+
+    The timeout branch used to break out of the relay loop only: the agent kept
+    generating and kept running tools against a permission callback nobody was
+    watching, and the lock was freed so the next prompt overlapped it at the
+    subprocess. It must send ``session/cancel`` exactly like Stop does.
+    """
+    monkeypatch.setattr(session_module, "PROMPT_OVERALL_TIMEOUT", 0)
+    client = _client(answers_cancel=True)
+    stdin = client._process.stdin
+    session = _session(client, "slot-timeout")
+
+    async def scenario():
+        events = []
+
+        async def consume():
+            async for event in session.prompt_stream("write me an essay"):
+                events.append(event)
+
+        task = asyncio.create_task(consume())
+        await asyncio.sleep(0.05)
+        # One event past the deadline is what trips the wall-clock check.
+        client._event_queue.put_nowait(TextChunk(text="thinking..."))
+        await asyncio.wait_for(task, timeout=5)
+        return events
+
+    events = asyncio.run(scenario())
+
+    # The turn ended as a timeout for the caller...
+    assert isinstance(events[-1], PromptDone)
+    assert events[-1].stop_reason == "timeout"
+    # ...and the agent was actually told to stop, exactly once.
+    assert stdin.methods().count("session/cancel") == 1
+    # Nothing in flight for the next prompt to overlap with.
+    assert client._current_req_id is None
+    assert client._peer._pending == {}
+    assert session.is_busy is False
+    assert session._lock.locked() is False

From 33cdf861029d261eb8863f14a69a2e816bc06153 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Fri, 14 Aug 2026 14:18:20 +0300
Subject: [PATCH 057/116] (perf) fan out the per-server status fetch on GET
 /servers
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

list_servers resolved each accessible server's status one at a time. An
unreachable server caches an error-only entry, so its status missed the
cache on every request and paid a full 10s connect timeout — N offline
servers blocked the dashboard's landing endpoint for the sum of those
timeouts. Resolve them with asyncio.gather instead, with each coroutine
swallowing its own failure to online=False so one broken server cannot
sink the batch. SDS already coalesces in-flight fetches per key.
---
 condor/web/routes/servers.py              |  41 ++++-
 tests/test_web_servers_parallel_status.py | 197 ++++++++++++++++++++++
 2 files changed, 231 insertions(+), 7 deletions(-)
 create mode 100644 tests/test_web_servers_parallel_status.py

diff --git a/condor/web/routes/servers.py b/condor/web/routes/servers.py
index 03d87b42..9d94afd9 100644
--- a/condor/web/routes/servers.py
+++ b/condor/web/routes/servers.py
@@ -1,29 +1,56 @@
 from __future__ import annotations
 
+import asyncio
+import logging
+
 from fastapi import APIRouter, Depends, HTTPException
 
-from condor.server_data_service import ServerDataType, get_server_data_service
+from condor.server_data_service import (
+    ServerDataService,
+    ServerDataType,
+    get_server_data_service,
+)
 from condor.web.auth import get_current_user
 from condor.web.models import ServerInfo, WebUser
 from config_manager import get_config_manager
 
+logger = logging.getLogger(__name__)
+
 router = APIRouter(tags=["servers"])
 
 
+async def _resolve_online(sds: ServerDataService, name: str) -> bool:
+    """Resolve one server's online flag, never raising.
+
+    An unreachable server caches an error-only entry (value=None), so ``get()``
+    misses on every request and the fetch pays a full connect timeout. Callers
+    run these concurrently, so a single failure must not sink the whole batch.
+    """
+    try:
+        status = sds.get(name, ServerDataType.SERVER_STATUS)
+        if status is None:
+            status = await sds.get_or_fetch(name, ServerDataType.SERVER_STATUS)
+    except Exception as e:  # noqa: BLE001 - a broken server is offline, not a 500
+        logger.debug("servers: status fetch failed for %s: %s", name, e)
+        return False
+    return status.get("status") == "online" if isinstance(status, dict) else False
+
+
 @router.get("/servers", response_model=list[ServerInfo])
 async def list_servers(user: WebUser = Depends(get_current_user)):
     cm = get_config_manager()
     accessible = cm.list_accessible_servers(user.id)
     sds = get_server_data_service()
 
+    # Per-server status resolution is independent and each miss can cost a full
+    # connect timeout, so fan it out: the endpoint waits once, not N times.
+    names = list(accessible)
+    flags = await asyncio.gather(*(_resolve_online(sds, name) for name in names))
+
     results = []
-    for name, cfg in accessible.items():
+    for name, online in zip(names, flags):
+        cfg = accessible[name]
         perm = cm.get_server_permission(user.id, name)
-        # Try cache first, fetch if missing/expired
-        status = sds.get(name, ServerDataType.SERVER_STATUS)
-        if status is None:
-            status = await sds.get_or_fetch(name, ServerDataType.SERVER_STATUS)
-        online = status.get("status") == "online" if isinstance(status, dict) else False
         results.append(
             ServerInfo(
                 name=name,
diff --git a/tests/test_web_servers_parallel_status.py b/tests/test_web_servers_parallel_status.py
new file mode 100644
index 00000000..2dd18760
--- /dev/null
+++ b/tests/test_web_servers_parallel_status.py
@@ -0,0 +1,197 @@
+"""GET /servers resolves every server's status concurrently (PERF-134).
+
+An unreachable server caches an error-only entry, so its status is re-fetched on
+every request and pays a full connect timeout. Resolved serially, the landing
+endpoint blocks for the *sum* of those timeouts. These tests pin the fan-out, the
+shape of the response, and that one broken server never sinks the batch.
+"""
+
+import asyncio
+import time
+
+import pytest
+from fastapi import FastAPI
+from starlette.testclient import TestClient
+
+import condor.web.routes.servers as servers_routes
+from condor.server_data_service import ServerDataType
+from condor.web.auth import get_current_user
+from condor.web.models import WebUser
+
+USER = WebUser(id=7, username="u", first_name="U", role="user")
+
+DELAY = 0.3
+
+
+class FakePermission:
+    def __init__(self, value):
+        self.value = value
+
+
+class FakeConfigManager:
+    def __init__(self, servers, permission="owner"):
+        self._servers = servers
+        self._permission = permission
+
+    def list_accessible_servers(self, user_id):
+        return self._servers
+
+    def get_server_permission(self, user_id, name):
+        return FakePermission(self._permission) if self._permission else None
+
+
+class FakeSDS:
+    """Cache always misses; each fetch sleeps like a connect timeout would."""
+
+    def __init__(self, statuses, delay=DELAY, raises=()):
+        self._statuses = statuses
+        self._delay = delay
+        self._raises = set(raises)
+        self.concurrent = 0
+        self.max_concurrent = 0
+
+    def get(self, name, data_type, **params):
+        return None
+
+    async def get_or_fetch(self, name, data_type, **params):
+        assert data_type is ServerDataType.SERVER_STATUS
+        self.concurrent += 1
+        self.max_concurrent = max(self.max_concurrent, self.concurrent)
+        try:
+            await asyncio.sleep(self._delay)
+            if name in self._raises:
+                raise RuntimeError("connection refused")
+            return self._statuses[name]
+        finally:
+            self.concurrent -= 1
+
+
+def build_client(monkeypatch, cm, sds):
+    monkeypatch.setattr(servers_routes, "get_config_manager", lambda: cm)
+    monkeypatch.setattr(servers_routes, "get_server_data_service", lambda: sds)
+    app = FastAPI()
+    app.include_router(servers_routes.router)
+    app.dependency_overrides[get_current_user] = lambda: USER
+    return TestClient(app)
+
+
+def three_servers():
+    return {
+        "alpha": {"host": "a.local", "port": 8000},
+        "bravo": {"host": "b.local", "port": 8001},
+        "charlie": {"host": "c.local", "port": 8002},
+    }
+
+
+def test_three_slow_servers_resolve_in_one_timeout_not_three(monkeypatch):
+    """Two unreachable servers must not stack their timeouts on the third."""
+    sds = FakeSDS(
+        statuses={
+            "alpha": {"status": "online"},
+            "bravo": None,
+            "charlie": None,
+        }
+    )
+    client = build_client(monkeypatch, FakeConfigManager(three_servers()), sds)
+
+    t0 = time.monotonic()
+    resp = client.get("/servers")
+    elapsed = time.monotonic() - t0
+
+    assert resp.status_code == 200
+    # Serial would be ~3x DELAY; concurrent stays well under 1.5x the slowest.
+    assert elapsed < DELAY * 1.5, f"took {elapsed:.2f}s, expected ~{DELAY:.2f}s"
+    assert sds.max_concurrent == 3
+
+
+def test_all_online_response_is_unchanged(monkeypatch):
+    """Names, hosts, ports, online flags, permission and sort order hold."""
+    sds = FakeSDS(
+        statuses={n: {"status": "online"} for n in three_servers()},
+        delay=0,
+    )
+    client = build_client(monkeypatch, FakeConfigManager(three_servers()), sds)
+
+    assert client.get("/servers").json() == [
+        {
+            "name": "alpha",
+            "host": "a.local",
+            "port": 8000,
+            "online": True,
+            "permission": "owner",
+        },
+        {
+            "name": "bravo",
+            "host": "b.local",
+            "port": 8001,
+            "online": True,
+            "permission": "owner",
+        },
+        {
+            "name": "charlie",
+            "host": "c.local",
+            "port": 8002,
+            "online": True,
+            "permission": "owner",
+        },
+    ]
+
+
+def test_offline_servers_sort_after_online_ones(monkeypatch):
+    """Sort key stays (not online, name) across the fan-out."""
+    sds = FakeSDS(
+        statuses={
+            "alpha": None,
+            "bravo": {"status": "online"},
+            "charlie": {"status": "offline"},
+        },
+        delay=0,
+    )
+    client = build_client(monkeypatch, FakeConfigManager(three_servers()), sds)
+
+    rows = client.get("/servers").json()
+    assert [(r["name"], r["online"]) for r in rows] == [
+        ("bravo", True),
+        ("alpha", False),
+        ("charlie", False),
+    ]
+
+
+def test_a_raising_fetch_renders_offline_instead_of_failing_the_endpoint(monkeypatch):
+    """One server blowing up must not take the other two down with it."""
+    sds = FakeSDS(
+        statuses={n: {"status": "online"} for n in three_servers()},
+        delay=0,
+        raises=["bravo"],
+    )
+    client = build_client(monkeypatch, FakeConfigManager(three_servers()), sds)
+
+    resp = client.get("/servers")
+    assert resp.status_code == 200
+    assert {r["name"]: r["online"] for r in resp.json()} == {
+        "alpha": True,
+        "bravo": False,
+        "charlie": True,
+    }
+
+
+def test_a_cache_hit_never_reaches_the_fetch(monkeypatch):
+    """The get()-first fallback survives: fresh cache short-circuits the fetch."""
+    sds = FakeSDS(statuses={}, delay=0)
+    sds.get = lambda name, data_type, **params: {"status": "online"}
+
+    async def boom(*a, **kw):
+        raise AssertionError("get_or_fetch must not run on a cache hit")
+
+    sds.get_or_fetch = boom
+    client = build_client(monkeypatch, FakeConfigManager(three_servers()), sds)
+
+    assert all(r["online"] for r in client.get("/servers").json())
+
+
+def test_missing_permission_falls_back_to_trader(monkeypatch):
+    sds = FakeSDS(statuses={n: {"status": "online"} for n in three_servers()}, delay=0)
+    cm = FakeConfigManager(three_servers(), permission=None)
+    client = build_client(monkeypatch, cm, sds)
+
+    assert {r["permission"] for r in client.get("/servers").json()} == {"trader"}

From 6a91da2b3d2f686c1287b1550527d92350273d5c Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Fri, 14 Aug 2026 14:22:38 +0300
Subject: [PATCH 058/116] (fix) gate agent strategy start on server access

POST /agents/{slug}/start and /{slug}/strategies/{sslug}/start merged the
free-form request config straight into TickEngine, which trades on
config["server_name"], so any approved user could start a live loop on
another user's stored API credentials. Apply the same has_server_access
check the config pin, consult and delegate already use: strict on a name
the body asks for, and on an inherited one whenever it resolves to a real
server, so the accessible-servers fallback keeps working.
---
 condor/web/routes/agents.py             |  16 +++
 tests/test_agent_start_server_access.py | 124 ++++++++++++++++++++++++
 2 files changed, 140 insertions(+)
 create mode 100644 tests/test_agent_start_server_access.py

diff --git a/condor/web/routes/agents.py b/condor/web/routes/agents.py
index 030420c9..46b0ffb1 100644
--- a/condor/web/routes/agents.py
+++ b/condor/web/routes/agents.py
@@ -1739,11 +1739,27 @@ async def _start(agent, strategy, req: StartStrategyRequest, user_id: int) -> di
     """Spawn a TickEngine session for ``strategy`` under ``agent``."""
     from condor.agents.config import load_full_config
     from condor.agents.engine import TickEngine
+    from config_manager import get_config_manager
 
     config_dict = load_full_config(strategy.dir, strategy.default_config)
     if req.config:
         config_dict.update(req.config)
 
+    # ``TickEngine._resolve_server`` trades on ``config["server_name"]`` and the
+    # request body is a free-form dict, so without this gate any authenticated
+    # user could start a live loop on another user's stored credentials — the
+    # same check the config pin and consult/delegate already apply. A name the
+    # body asked for is held to it strictly; an inherited one (strategy default,
+    # or the "local" that AgentConfig fills in) only matters when it resolves to
+    # a real server, since otherwise the engine falls through to the caller's
+    # own accessible servers, which is scoped already.
+    cm = get_config_manager()
+    server_name = config_dict.get("server_name")
+    asked_for_it = bool(req.config and req.config.get("server_name"))
+    if server_name and (asked_for_it or cm.get_server(server_name)):
+        if not cm.has_server_access(user_id, server_name):
+            raise HTTPException(status_code=403, detail="No access")
+
     if req.trading_context:
         config_dict["trading_context"] = req.trading_context
     elif not config_dict.get("trading_context") and strategy.default_trading_context:
diff --git a/tests/test_agent_start_server_access.py b/tests/test_agent_start_server_access.py
new file mode 100644
index 00000000..5c80bedd
--- /dev/null
+++ b/tests/test_agent_start_server_access.py
@@ -0,0 +1,124 @@
+"""Starting a strategy cannot borrow a server the caller has no access to (SEC-149).
+
+``StartStrategyRequest.config`` is a free-form dict merged straight into the
+engine config, and ``TickEngine._resolve_server`` trades on its ``server_name``,
+so before the gate any approved user could POST a foreign server name and run a
+live loop on someone else's stored API credentials. The sibling routes in the
+same file (config pin, consult, delegate) always checked ``has_server_access``;
+only the start path did not.
+"""
+
+import pytest
+from fastapi import FastAPI
+from starlette.testclient import TestClient
+
+from condor.agents import agent as agent_module
+from condor.agents import engine as engine_module
+from condor.agents import strategy as strategy_module
+from condor.agents.agent import AgentStore
+from condor.agents.strategy import StrategyStore
+from condor.web.auth import get_current_user
+from condor.web.models import WebUser
+from condor.web.routes import agents as routes
+
+USER = WebUser(id=555, username="u", first_name="U", role="user")
+
+MINE = "mine-prod"
+THEIRS = "someone-else"
+KNOWN = {MINE, THEIRS}
+
+
+class FakeConfigManager:
+    def is_admin(self, user_id):
+        return False
+
+    def get_server(self, server_name):
+        return {"name": server_name} if server_name in KNOWN else None
+
+    def has_server_access(self, user_id, server_name, *a, **k):
+        return user_id == USER.id and server_name == MINE
+
+
+class FakeEngine:
+    """Stands in for TickEngine: records every spawn, never touches the network."""
+
+    spawned: list[dict] = []
+
+    def __init__(self, agent, strategy, config, chat_id, user_id):
+        self.config = config
+        self.agent_id = "agent-1"
+        self.session_num = 1
+        FakeEngine.spawned.append(config)
+
+    async def start(self):
+        return None
+
+
+@pytest.fixture
+def env(tmp_path, monkeypatch):
+    monkeypatch.setattr(agent_module, "_DATA_ROOT", tmp_path)
+    monkeypatch.setattr(strategy_module, "_DATA_ROOT", tmp_path)
+    monkeypatch.setattr(
+        "config_manager.get_config_manager", lambda: FakeConfigManager()
+    )
+    monkeypatch.setattr(engine_module, "TickEngine", FakeEngine)
+    FakeEngine.spawned = []
+    AgentStore().create(name="Brigado", description="BRL market making")
+    StrategyStore().create(agent_slug="brigado", name="Scalp")
+    return tmp_path
+
+
+def _client() -> TestClient:
+    app = FastAPI()
+    app.include_router(routes.router)
+    app.dependency_overrides[get_current_user] = lambda: USER
+    return TestClient(app)
+
+
+def test_starting_on_someone_elses_server_is_refused(env):
+    res = _client().post(
+        "/agents/brigado/strategies/scalp/start",
+        json={"config": {"server_name": THEIRS}},
+    )
+
+    assert res.status_code == 403
+    assert FakeEngine.spawned == [], "no engine spawned on a foreign server"
+
+
+def test_starting_on_my_own_server_still_works(env):
+    res = _client().post(
+        "/agents/brigado/strategies/scalp/start",
+        json={"config": {"server_name": MINE}},
+    )
+
+    assert res.status_code == 200
+    assert res.json()["started"] is True
+    assert [c["server_name"] for c in FakeEngine.spawned] == [MINE]
+
+
+def test_starting_without_a_server_keeps_the_accessible_servers_fallback(env):
+    """No server was asked for and the inherited default names nothing real."""
+    res = _client().post("/agents/brigado/strategies/scalp/start", json={})
+
+    assert res.status_code == 200
+    assert len(FakeEngine.spawned) == 1
+
+
+def test_a_foreign_server_baked_into_the_strategy_default_is_refused_too(env):
+    StrategyStore().create(
+        agent_slug="brigado", name="Borrowed", default_config={"server_name": THEIRS}
+    )
+
+    res = _client().post("/agents/brigado/strategies/borrowed/start", json={})
+
+    assert res.status_code == 403
+    assert FakeEngine.spawned == []
+
+
+def test_the_unnamed_loop_route_is_gated_as_well(env):
+    res = _client().post(
+        "/agents/brigado/start", json={"config": {"server_name": THEIRS}}
+    )
+
+    assert res.status_code == 403
+    assert FakeEngine.spawned == []

From ccb417faf52a29d044aaf6b896c70adbc3706375 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Fri, 14 Aug 2026 14:26:32 +0300
Subject: [PATCH 059/116] (fix) gate routine instance endpoints on ownership
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

get/stop/image on a routine instance, and the instance listing, checked
nothing beyond authentication: any approved user could read another
user's instance with its last result, fetch its chart PNG, stop their
running monitors, and enumerate every instance in the store — the same
cross-user leak SEC-045 closed for run/schedule.

Ownership already travels in the instance meta as user_id, so the routes
now compare against it: admins reach everything, everyone else only what
they started, and an instance with no recorded owner is nobody's.
---
 condor/web/routes/routines.py            |  54 +++++--
 tests/test_routine_instance_ownership.py | 185 +++++++++++++++++++++++
 2 files changed, 228 insertions(+), 11 deletions(-)
 create mode 100644 tests/test_routine_instance_ownership.py

diff --git a/condor/web/routes/routines.py b/condor/web/routes/routines.py
index f406d401..fdc64f1b 100644
--- a/condor/web/routes/routines.py
+++ b/condor/web/routes/routines.py
@@ -65,6 +65,39 @@ class HooksRequest(BaseModel):
     trigger: str = "success"
 
 
+# ── Helpers ──
+
+
+def _owns(inst: dict, user: WebUser) -> bool:
+    """Whether ``user`` started this instance.
+
+    The owner is the ``user_id`` RoutineStore records in the instance meta.
+    An instance without one is nobody's: MCP runs that carried no user and
+    Telegram instances synced into the store both land here, and treating them
+    as unowned keeps them out of every non-admin's reach instead of handing
+    them to whoever asks first.
+    """
+    owner = inst.get("user_id")
+    return bool(owner) and owner == user.id
+
+
+def _require_instance_access(inst: dict, user: WebUser) -> None:
+    """Admins reach every instance; everyone else only their own (SEC-150)."""
+    if get_config_manager().is_admin(user.id):
+        return
+    if not _owns(inst, user):
+        raise HTTPException(status_code=403, detail="Not your instance")
+
+
+def _authorized_instance(instance_id: str, user: WebUser) -> dict:
+    """Fetch an instance, 404 if absent and 403 if it belongs to someone else."""
+    inst = get_routine_store().get_instance(instance_id)
+    if not inst:
+        raise HTTPException(404, "Instance not found")
+    _require_instance_access(inst, user)
+    return inst
+
+
 # ── Routes ──
 
 
@@ -77,19 +110,18 @@ async def list_routines(user: WebUser = Depends(get_current_user)):
 
 @router.get("/instances")
 async def list_instances(user: WebUser = Depends(get_current_user)):
-    """List all active routine instances."""
+    """List the caller's active routine instances (admins see them all)."""
     store = get_routine_store()
-    return store.list_instances()
+    instances = store.list_instances()
+    if get_config_manager().is_admin(user.id):
+        return instances
+    return [inst for inst in instances if _owns(inst, user)]
 
 
 @router.get("/instances/{instance_id}")
 async def get_instance(instance_id: str, user: WebUser = Depends(get_current_user)):
     """Get instance detail including last result."""
-    store = get_routine_store()
-    inst = store.get_instance(instance_id)
-    if not inst:
-        raise HTTPException(404, "Instance not found")
-    return inst
+    return _authorized_instance(instance_id, user)
 
 
 @router.get("/instances/{instance_id}/image")
@@ -97,8 +129,8 @@ async def get_instance_image(
     instance_id: str, user: WebUser = Depends(get_current_user)
 ):
     """Serve the chart PNG for an instance result."""
-    store = get_routine_store()
-    result = store.get_result(instance_id)
+    _authorized_instance(instance_id, user)
+    result = get_routine_store().get_result(instance_id)
     if not result or not result.chart_image:
         raise HTTPException(404, "No chart image available")
     return Response(content=result.chart_image, media_type="image/png")
@@ -234,8 +266,8 @@ async def schedule_routine_v2(
 @router.post("/instances/{instance_id}/stop")
 async def stop_instance(instance_id: str, user: WebUser = Depends(get_current_user)):
     """Stop a running or scheduled instance."""
-    store = get_routine_store()
-    if not store.stop(instance_id):
+    _authorized_instance(instance_id, user)
+    if not get_routine_store().stop(instance_id):
         raise HTTPException(404, "Instance not found")
     return {"stopped": True}
 
diff --git a/tests/test_routine_instance_ownership.py b/tests/test_routine_instance_ownership.py
new file mode 100644
index 00000000..85e740e8
--- /dev/null
+++ b/tests/test_routine_instance_ownership.py
@@ -0,0 +1,185 @@
+"""Tests for SEC-150: routine instance endpoints must enforce ownership.
+
+SEC-045 gated *starting* a routine behind server access but left the instance
+endpoints wide open: any approved user could GET another user's instance (with
+its last result), fetch its chart PNG, stop it, and enumerate every instance in
+the store. Ownership lives in the instance meta as ``user_id``
+(RoutineStore._new_instance_meta), so each endpoint now checks it — admins keep
+reaching everything, mirroring ``_require_ownership`` in routes/sessions.py.
+"""
+
+import pytest
+from fastapi import FastAPI
+from starlette.testclient import TestClient
+
+import condor.web.routes.routines as routines_module
+from condor.web.auth import get_current_user
+from condor.web.models import WebUser
+
+OWNER = WebUser(id=111, username="owner", first_name="O", role="user")
+STRANGER = WebUser(id=222, username="stranger", first_name="S", role="user")
+ADMIN = WebUser(id=999, username="admin", first_name="A", role="admin")
+
+OWNED = "inst-owned"
+FOREIGN = "inst-foreign"
+UNATTRIBUTED = "inst-orphan"
+
+
+class FakeResult:
+    def __init__(self, chart_image=b"PNG-BYTES"):
+        self.chart_image = chart_image
+
+
+class FakeRoutineStore:
+    """Holds one instance per user; records which ones were actually stopped."""
+
+    def __init__(self):
+        self._instances = {
+            OWNED: {"instance_id": OWNED, "user_id": OWNER.id, "last_result": "mine"},
+            FOREIGN: {
+                "instance_id": FOREIGN,
+                "user_id": STRANGER.id,
+                "last_result": "secret",
+            },
+            # Telegram-synced / MCP instances land in the store without an owner.
+            UNATTRIBUTED: {"instance_id": UNATTRIBUTED, "last_result": "nobody's"},
+        }
+        self.stopped = []
+
+    def list_instances(self):
+        return list(self._instances.values())
+
+    def get_instance(self, instance_id):
+        return self._instances.get(instance_id)
+
+    def get_result(self, instance_id):
+        return FakeResult() if instance_id in self._instances else None
+
+    def stop(self, instance_id):
+        if instance_id not in self._instances:
+            return False
+        self.stopped.append(instance_id)
+        return True
+
+
+class FakeConfigManager:
+    def is_admin(self, user_id):
+        return user_id == ADMIN.id
+
+    def has_server_access(self, user_id, server_name, *args, **kwargs):
+        return True
+
+
+@pytest.fixture
+def make_client(monkeypatch):
+    store = FakeRoutineStore()
+    monkeypatch.setattr(routines_module, "get_routine_store", lambda: store)
+    monkeypatch.setattr(routines_module, "get_config_manager", FakeConfigManager)
+
+    def _make(user: WebUser):
+        app = FastAPI()
+        app.include_router(routines_module.router)
+        app.dependency_overrides[get_current_user] = lambda: user
+        return TestClient(app)
+
+    return _make, store
+
+
+# ── GET /routines/instances/{id} ──
+
+
+def test_get_foreign_instance_is_refused(make_client):
+    make, _store = make_client
+    resp = make(OWNER).get(f"/routines/instances/{FOREIGN}")
+    assert resp.status_code == 403
+    assert "secret" not in resp.text
+
+
+def test_get_own_instance_still_works(make_client):
+    make, _store = make_client
+    resp = make(OWNER).get(f"/routines/instances/{OWNED}")
+    assert resp.status_code == 200
+    assert resp.json()["last_result"] == "mine"
+
+
+def test_admin_can_get_any_instance(make_client):
+    make, _store = make_client
+    resp = make(ADMIN).get(f"/routines/instances/{FOREIGN}")
+    assert resp.status_code == 200
+
+
+def test_unowned_instance_is_refused_to_non_admins(make_client):
+    """No recorded owner -> nobody's but the admin's. Fails closed."""
+    make, _store = make_client
+    assert make(OWNER).get(f"/routines/instances/{UNATTRIBUTED}").status_code == 403
+    assert make(ADMIN).get(f"/routines/instances/{UNATTRIBUTED}").status_code == 200
+
+
+def test_missing_instance_is_still_a_404(make_client):
+    make, _store = make_client
+    assert make(OWNER).get("/routines/instances/nope").status_code == 404
+
+
+# ── POST /routines/instances/{id}/stop ──
+
+
+def test_stop_foreign_instance_is_refused_and_it_keeps_running(make_client):
+    make, store = make_client
+    resp = make(OWNER).post(f"/routines/instances/{FOREIGN}/stop")
+    assert resp.status_code == 403
+    assert store.stopped == []
+
+
+def test_stop_own_instance_still_works(make_client):
+    make, store = make_client
+    resp = make(OWNER).post(f"/routines/instances/{OWNED}/stop")
+    assert resp.status_code == 200
+    assert resp.json() == {"stopped": True}
+    assert store.stopped == [OWNED]
+
+
+def test_admin_can_stop_any_instance(make_client):
+    make, store = make_client
+    resp = make(ADMIN).post(f"/routines/instances/{FOREIGN}/stop")
+    assert resp.status_code == 200
+    assert store.stopped == [FOREIGN]
+
+
+# ── GET /routines/instances/{id}/image ──
+
+
+def test_foreign_instance_image_is_refused(make_client):
+    make, _store = make_client
+    resp = make(OWNER).get(f"/routines/instances/{FOREIGN}/image")
+    assert resp.status_code == 403
+    assert resp.content != b"PNG-BYTES"
+
+
+def test_own_instance_image_is_served(make_client):
+    make, _store = make_client
+    resp = make(OWNER).get(f"/routines/instances/{OWNED}/image")
+    assert resp.status_code == 200
+    assert resp.content == b"PNG-BYTES"
+
+
+def test_admin_can_fetch_any_instance_image(make_client):
+    make, _store = make_client
+    resp = make(ADMIN).get(f"/routines/instances/{FOREIGN}/image")
+    assert resp.status_code == 200
+    assert resp.content == b"PNG-BYTES"
+
+
+# ── GET /routines/instances ──
+
+
+def test_list_shows_only_the_callers_instances(make_client):
+    make, _store = make_client
+    resp = make(OWNER).get("/routines/instances")
+    assert resp.status_code == 200
+    assert [i["instance_id"] for i in resp.json()] == [OWNED]
+
+
+def test_admin_list_shows_every_instance(make_client):
+    make, _store = make_client
+    resp = make(ADMIN).get("/routines/instances")
+    assert {i["instance_id"] for i in resp.json()} == {OWNED, FOREIGN, UNATTRIBUTED}

From 9e97880f43256c80a4d7c29179646de393cf391b Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Fri, 14 Aug 2026 14:32:07 +0300
Subject: [PATCH 060/116] (fix) SEC-151: gate /code/run behind admin or an
 explicit grant
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

POST /api/v1/code/run was gated only by get_current_user, i.e. any approved
UserRole.USER. The snippet is eval'd unsandboxed in the bot process, so a
caller could read every server's credentials, the web JWT secret and
os.environ regardless of the server ACL the route had just applied — a full
USER -> admin escalation that voided the role model.

The route now refuses anyone who is not an admin, with an explicit per-user
`code_run` preference as the grant an admin can hand to a seat that
legitimately needs the MCP run_code tool. The MCP path is unaffected: it
authenticates as CONDOR_USER_ID, whose role is resolved from config, not
from the JWT's hint.
---
 condor/code_runner.py       |   6 ++
 condor/web/routes/code.py   |  33 ++++++++
 tests/test_code_run_tool.py | 165 +++++++++++++++++++++++++++++++++---
 3 files changed, 190 insertions(+), 14 deletions(-)

diff --git a/condor/code_runner.py b/condor/code_runner.py
index 545bca3d..752843c8 100644
--- a/condor/code_runner.py
+++ b/condor/code_runner.py
@@ -12,6 +12,12 @@
 that without wrapping the source in a function, which is what keeps traceback
 line numbers pointing at the line the caller actually wrote — the single most
 useful property when the caller is a model about to fix its own snippet.
+
+There is no sandbox and that is deliberate — a snippet is meant to reach exactly
+what a routine reaches. It follows that calling ``execute_code`` is handing over
+the whole process, so every caller must gate it at least as tightly as
+``condor/web/routes/code.py`` does (SEC-151); "the caller is authenticated" is
+not a gate.
 """
 
 from __future__ import annotations
diff --git a/condor/web/routes/code.py b/condor/web/routes/code.py
index 08e463cd..2ef24c65 100644
--- a/condor/web/routes/code.py
+++ b/condor/web/routes/code.py
@@ -8,6 +8,11 @@
 
 There are no GET endpoints on purpose: history is read straight off disk by the
 subprocess, which shares the filesystem, just as routine CRUD is.
+
+A snippet runs unsandboxed in this process, so reaching this route *is* reaching
+everything the bot can reach — config.yml, the web JWT secret, os.environ. The
+server ACL below only picks which client is pre-resolved; it cannot constrain a
+body. The real gate is therefore ``_may_run_code`` (SEC-151).
 """
 
 from __future__ import annotations
@@ -25,6 +30,29 @@
 log = logging.getLogger(__name__)
 router = APIRouter(prefix="/code", tags=["code"])
 
+# The preference an admin sets on a user record to hand them the code runner.
+RUN_CODE_PREFERENCE = "code_run"
+
+
+def _may_run_code(user_id: int) -> bool:
+    """Who is allowed to execute a snippet in the bot's own process.
+
+    Being approved is not enough. ``execute_code`` compiles with full builtins
+    and no sandbox, so any snippet can read every server's credentials, the web
+    JWT secret and ``os.environ`` no matter which servers its caller was granted
+    — running code here is admin-equivalent by construction, and gating it on
+    ``UserRole.USER`` silently voided the whole role model (SEC-151).
+
+    Admins therefore pass, and anyone else only with the explicit
+    ``code_run`` preference an admin sets on their record. That opt-in is what
+    keeps the door open for a non-admin seat whose MCP ``run_code`` tool is a
+    legitimate part of their workflow: it is a grant, not a default.
+    """
+    cm = get_config_manager()
+    return cm.is_admin(user_id) or bool(
+        cm.get_user_preference(user_id, RUN_CODE_PREFERENCE, False)
+    )
+
 
 class RunCodeRequest(BaseModel):
     code: str
@@ -45,6 +73,11 @@ async def run_code(
     user: WebUser = Depends(get_current_user),
 ):
     """Execute a Python snippet in this process and return its recorded run."""
+    if not _may_run_code(user.id):
+        # Before the 400 and before any store write: a refused caller must not
+        # learn anything, and must leave no CodeRun behind.
+        log.warning("Denied /code/run to user %s (not admin, no grant)", user.id)
+        raise HTTPException(status_code=403, detail="Not allowed to run code")
     if not body.code.strip():
         raise HTTPException(400, "code is required")
     if body.server_name:
diff --git a/tests/test_code_run_tool.py b/tests/test_code_run_tool.py
index 41dad91d..91bbbfa1 100644
--- a/tests/test_code_run_tool.py
+++ b/tests/test_code_run_tool.py
@@ -234,6 +234,32 @@ def test_history_rereads_the_index_the_main_process_writes(tmp_path, seat, monke
 # ── the route ──
 
 
+class _FakeConfigManager:
+    """Server ACL + the SEC-151 code-run gate, both answered from the test."""
+
+    def __init__(self, allowed: bool = True, admins=(), granted=()):
+        self.allowed = allowed
+        self.admins = set(admins)
+        self.granted = set(granted)
+
+    def has_server_access(self, user_id, server_name, *a, **kw):
+        return self.allowed
+
+    def is_admin(self, user_id):
+        return user_id in self.admins
+
+    def get_user_preference(self, user_id, key, default=None):
+        if key == code_routes.RUN_CODE_PREFERENCE:
+            return user_id in self.granted
+        return default
+
+
+def _config(monkeypatch, **kw):
+    monkeypatch.setattr(
+        code_routes, "get_config_manager", lambda: _FakeConfigManager(**kw)
+    )
+
+
 def test_the_route_runs_the_snippet_as_the_authenticated_caller(monkeypatch):
     seen: dict = {}
 
@@ -242,9 +268,7 @@ async def _execute(code, **kw):
         return {"id": "code_1_aaaa", "status": "ok"}
 
     monkeypatch.setattr(code_routes, "execute_code", _execute)
-    monkeypatch.setattr(
-        code_routes, "get_config_manager", lambda: _FakeConfigManager(True)
-    )
+    _config(monkeypatch, allowed=True, admins={CALLER.id})
 
     body = RunCodeRequest(
         code="result = 1",
@@ -265,18 +289,8 @@ async def _execute(code, **kw):
     assert seen["session_key"] == "web:7:slot-1"
 
 
-class _FakeConfigManager:
-    def __init__(self, allowed: bool):
-        self.allowed = allowed
-
-    def has_server_access(self, user_id, server_name, *a, **kw):
-        return self.allowed
-
-
 def test_the_route_refuses_a_server_the_caller_cannot_reach(monkeypatch):
-    monkeypatch.setattr(
-        code_routes, "get_config_manager", lambda: _FakeConfigManager(False)
-    )
+    _config(monkeypatch, allowed=False, admins={CALLER.id})
 
     body = RunCodeRequest(code="result = 1", server_name="someone-elses")
     with pytest.raises(HTTPException) as excinfo:
@@ -286,6 +300,7 @@ def test_the_route_refuses_a_server_the_caller_cannot_reach(monkeypatch):
 
 
 def test_the_route_rejects_an_empty_snippet(monkeypatch):
+    _config(monkeypatch, admins={CALLER.id})
     with pytest.raises(HTTPException) as excinfo:
         asyncio.run(run_code_route(RunCodeRequest(code="  \n "), user=CALLER))
 
@@ -300,6 +315,7 @@ async def _execute(code, **kw):
         return {}
 
     monkeypatch.setattr(code_routes, "execute_code", _execute)
+    _config(monkeypatch, admins={CALLER.id})
     asyncio.run(run_code_route(RunCodeRequest(code="pass", timeout=9999), user=CALLER))
 
     assert seen["timeout"] == code_routes.MAX_TIMEOUT
@@ -314,6 +330,127 @@ def test_the_route_is_authenticated_like_every_other_router():
     ), "an endpoint that executes arbitrary Python must never be anonymous"
 
 
+# ── SEC-151: the gate in front of an unsandboxed interpreter ──
+
+
+def _never_executes(monkeypatch):
+    """An ``execute_code`` that fails the test if the gate ever lets it run."""
+
+    async def _execute(code, **kw):  # pragma: no cover - must not be reached
+        raise AssertionError("execute_code ran for a caller that must be refused")
+
+    monkeypatch.setattr(code_routes, "execute_code", _execute)
+
+
+def test_an_approved_non_admin_is_refused_before_anything_executes(monkeypatch):
+    """Approved is not enough: the snippet outranks every ACL, so USER cannot."""
+    _never_executes(monkeypatch)
+    _config(monkeypatch, admins={999}, granted=set())
+
+    with pytest.raises(HTTPException) as excinfo:
+        asyncio.run(run_code_route(RunCodeRequest(code="result = 1"), user=CALLER))
+
+    assert excinfo.value.status_code == 403
+
+
+def test_the_refusal_lands_before_the_empty_snippet_check(monkeypatch):
+    """A refused caller learns nothing about the body it sent."""
+    _never_executes(monkeypatch)
+    _config(monkeypatch, admins={999})
+
+    with pytest.raises(HTTPException) as excinfo:
+        asyncio.run(run_code_route(RunCodeRequest(code="   "), user=CALLER))
+
+    assert excinfo.value.status_code == 403, "403 must win over the 400"
+
+
+def test_an_admin_still_runs_code(monkeypatch):
+    ran: dict = {}
+
+    async def _execute(code, **kw):
+        ran["code"] = code
+        return {"id": "code_1_aaaa", "status": "ok"}
+
+    monkeypatch.setattr(code_routes, "execute_code", _execute)
+    _config(monkeypatch, admins={CALLER.id})
+
+    out = asyncio.run(run_code_route(RunCodeRequest(code="result = 1"), user=CALLER))
+
+    assert out["status"] == "ok"
+    assert ran["code"] == "result = 1"
+
+
+def test_a_non_admin_the_admin_granted_still_runs_code(monkeypatch):
+    """The escape hatch: a seat that legitimately needs run_code is not locked out."""
+    ran: dict = {}
+
+    async def _execute(code, **kw):
+        ran["code"] = code
+        return {"id": "code_1_aaaa", "status": "ok"}
+
+    monkeypatch.setattr(code_routes, "execute_code", _execute)
+    _config(monkeypatch, admins={999}, granted={CALLER.id})
+
+    out = asyncio.run(run_code_route(RunCodeRequest(code="result = 1"), user=CALLER))
+
+    assert out["status"] == "ok"
+    assert ran["code"] == "result = 1"
+
+
+def test_the_mcp_run_code_path_still_works_end_to_end(monkeypatch, seat):
+    """The MCP tool → its JWT → get_current_user → the gated route, for real.
+
+    Only the HTTP hop is elided: the token is minted by the same
+    ``create_jwt(settings.user_id, ...)`` call ``condor_client.call_main_api``
+    makes, and it is resolved by the real ``get_current_user`` dependency, so a
+    gate that rejected the MCP principal would fail here.
+    """
+    from fastapi.security import HTTPAuthorizationCredentials
+
+    from condor.web import auth as web_auth
+    from config_manager import UserRole
+
+    seat_user_id = 4242
+    monkeypatch.setattr(settings, "user_id", seat_user_id)
+    monkeypatch.setattr(web_auth, "_jwt_secret", lambda: "test-secret")
+
+    class _AuthConfigManager:
+        def get_user_role(self, user_id):
+            return UserRole.ADMIN if user_id == seat_user_id else UserRole.PENDING
+
+    monkeypatch.setattr(web_auth, "get_config_manager", lambda: _AuthConfigManager())
+    _config(monkeypatch, allowed=True, admins={seat_user_id})
+
+    async def _execute(code, **kw):
+        return {
+            "id": "code_1_aaaa",
+            "status": "ok",
+            "stdout": "",
+            "result": str(kw["chat_id"]),
+            "error": "",
+            "traceback": "",
+            "report_id": "",
+            "duration_ms": 1,
+        }
+
+    monkeypatch.setattr(code_routes, "execute_code", _execute)
+
+    async def _transport(method, path, body=None, timeout=None):
+        assert (method, path) == ("POST", "/code/run")
+        token = web_auth.create_jwt(settings.user_id, role="user")
+        user = await web_auth.get_current_user(
+            HTTPAuthorizationCredentials(scheme="Bearer", credentials=token)
+        )
+        return await run_code_route(RunCodeRequest(**body), user=user)
+
+    monkeypatch.setattr(code_tool, "call_main_api", _transport)
+
+    out = asyncio.run(code_tool.run_code(code="result = 1", label="probe"))
+
+    assert out["status"] == "ok", out
+    assert out["result"] == str(seat_user_id), "the run belongs to the MCP seat"
+
+
 # ── guidance: the assistant has to be told this exists ──
 
 

From c192b9a432890432c55b4c01f179709e77099846 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Fri, 14 Aug 2026 14:39:21 +0300
Subject: [PATCH 061/116] (refactor) ARCH-146: one historical-candles ladder in
 the fetcher layer

The sequence "get_historical_candles -> unwrap a list-or-{"data": [...]}
payload -> fall back to get_candles -> normalize dict-or-tuple rows to float
OHLCV" was inlined three times: the REST candles route, the WS candle backfill
and the WS REST poll. All three talked to client.market_data directly, against
the fetcher layer's contract, and the unwrap ternary appeared four times.

It now lives in condor.fetchers.market_data.fetch_historical_candles, with the
edges the call sites actually differed on expressed as arguments instead of
silently unified: limit (None disables the get_candles fallback, which the poll
never had), fallback_on_error (only the REST route degrades to the plain window
when the range call fails) and strict (only the REST route surfaces a malformed
row instead of dropping it). ws_manager._normalize_candle stays as a thin alias
over the one normalizer, for the two WS stream uses unrelated to this ladder.
---
 condor/fetchers/market_data.py           | 126 ++++++++-
 condor/web/routes/market.py              | 110 ++------
 condor/web/ws_manager.py                 |  68 +----
 tests/test_fetcher_historical_candles.py | 312 +++++++++++++++++++++++
 4 files changed, 471 insertions(+), 145 deletions(-)
 create mode 100644 tests/test_fetcher_historical_candles.py

diff --git a/condor/fetchers/market_data.py b/condor/fetchers/market_data.py
index fd3de269..184ba754 100644
--- a/condor/fetchers/market_data.py
+++ b/condor/fetchers/market_data.py
@@ -40,8 +40,7 @@ async def fetch_candles(
         )
         if not candles:
             return None
-        data = candles if isinstance(candles, list) else candles.get("data", [])
-        if not data:
+        if not _unwrap_candles(candles):
             return None
         return candles
     except Exception as e:
@@ -51,6 +50,129 @@ async def fetch_candles(
         return None
 
 
+def normalize_candle(c: Any, *, strict: bool = False) -> Optional[Dict[str, float]]:
+    """Normalize one candle row to a dict of floats, or None when unusable.
+
+    The API returns candles in two shapes depending on endpoint and version: a
+    dict keyed by OHLCV names, or a positional row ``[ts, o, h, l, c, v]``
+    (extra trailing fields are ignored). Rows in neither shape yield None.
+
+    Args:
+        strict: Re-raise ``TypeError``/``ValueError`` from a malformed value
+            (e.g. ``open="n/a"``) instead of dropping the row. The REST candles
+            route has always surfaced those; the WS paths have always swallowed
+            them, so the behaviour stays per-caller.
+    """
+    try:
+        if isinstance(c, dict):
+            return {
+                "timestamp": float(c.get("timestamp", 0)),
+                "open": float(c.get("open", 0)),
+                "high": float(c.get("high", 0)),
+                "low": float(c.get("low", 0)),
+                "close": float(c.get("close", 0)),
+                "volume": float(c.get("volume", 0)),
+            }
+        if isinstance(c, (list, tuple)) and len(c) >= 6:
+            return {
+                "timestamp": float(c[0]),
+                "open": float(c[1]),
+                "high": float(c[2]),
+                "low": float(c[3]),
+                "close": float(c[4]),
+                "volume": float(c[5]),
+            }
+    except (TypeError, ValueError):
+        if strict:
+            raise
+    return None
+
+
+def _unwrap_candles(result: Any) -> List[Any]:
+    """Candle rows out of either payload shape: a bare list or ``{"data": [...]}``."""
+    return (
+        result
+        if isinstance(result, list)
+        else result.get("data", []) if isinstance(result, dict) else []
+    )
+
+
+async def fetch_historical_candles(
+    client,
+    connector_name: str,
+    trading_pair: str,
+    interval: str = "1m",
+    *,
+    start_time: Optional[int] = None,
+    end_time: Optional[int] = None,
+    limit: Optional[int] = None,
+    fallback_on_error: bool = False,
+    strict: bool = False,
+) -> List[Dict[str, float]]:
+    """Time-ranged candles, normalized, with the ``get_candles`` fallback ladder.
+
+    Owns the sequence every candle consumer used to inline: ask for the historical
+    range, unwrap whichever payload shape came back, fall back to the plain
+    ``get_candles`` window when the range yields nothing, and normalize the rows.
+
+    Args:
+        start_time / end_time: Unix epoch seconds. With ``start_time`` None the
+            historical call is skipped entirely and the fallback (if any) answers.
+        limit: Row count for the ``get_candles`` fallback. None disables the
+            fallback — for pollers that only want the fresh tail of a live range
+            and would rather return nothing than a full unrelated window.
+        fallback_on_error: Treat a failing historical call as an empty result and
+            continue to the fallback, instead of propagating. Callers that abort
+            on failure (WS backfill, REST poll) leave it off.
+        strict: Passed through to `normalize_candle`.
+
+    Returns:
+        Normalized candles in upstream order; empty when nothing was usable.
+    """
+    result = None
+    if start_time is not None:
+        try:
+            logger.info(
+                "Fetching historical candles: connector=%s pair=%s interval=%s "
+                "start=%s end=%s",
+                connector_name,
+                trading_pair,
+                interval,
+                start_time,
+                end_time,
+            )
+            result = await client.market_data.get_historical_candles(
+                connector_name,
+                trading_pair,
+                interval,
+                start_time=start_time,
+                end_time=end_time,
+            )
+        except Exception as e:
+            if not fallback_on_error:
+                raise
+            logger.warning(
+                "get_historical_candles failed: %s — falling back to get_candles", e
+            )
+            result = None
+
+    rows = _unwrap_candles(result)
+    if not rows and limit is not None:
+        logger.info(
+            "Falling back to get_candles: connector=%s pair=%s interval=%s limit=%s",
+            connector_name,
+            trading_pair,
+            interval,
+            limit,
+        )
+        result = await client.market_data.get_candles(
+            connector_name, trading_pair, interval, limit
+        )
+        rows = _unwrap_candles(result)
+
+    return [c for r in rows if (c := normalize_candle(r, strict=strict)) is not None]
+
+
 async def fetch_candle_connectors(client, **_kw) -> List[str]:
     """Fetch available candle connectors."""
     return await client.market_data.get_available_candle_connectors()
diff --git a/condor/web/routes/market.py b/condor/web/routes/market.py
index 032bc931..34137bba 100644
--- a/condor/web/routes/market.py
+++ b/condor/web/routes/market.py
@@ -29,6 +29,7 @@ def _candle_cache_put(key: tuple, value: list, now: float) -> None:
         _candle_cache.pop(next(iter(_candle_cache)))
 
 
+from condor.fetchers.market_data import fetch_historical_candles
 from condor.web.auth import get_current_user
 from condor.web.models import (
     CandleData,
@@ -471,95 +472,34 @@ async def get_candles(
         return candles
 
     client = await cm.get_client(name)
-    result = None
     try:
-        # Prefer historical candles with time range when start_time is given
-        if start_time is not None:
-            st = int(start_time)
-            et = int(end_time) if end_time else int(time.time())
-            logger.info(
-                "Fetching historical candles: connector=%s pair=%s interval=%s start=%s end=%s",
-                connector,
-                trading_pair,
-                interval,
-                st,
-                et,
-            )
-            result = await client.market_data.get_historical_candles(
-                connector,
-                trading_pair,
-                interval,
-                start_time=st,
-                end_time=et,
-            )
-            logger.info(
-                "Historical candles result: type=%s len=%s",
-                type(result).__name__,
-                len(result) if isinstance(result, (list, dict)) else "?",
-            )
+        rows = await fetch_historical_candles(
+            client,
+            connector,
+            trading_pair,
+            interval,
+            # No start_time means no time range to ask for: go straight to the
+            # plain `limit`-sized window.
+            start_time=int(start_time) if start_time is not None else None,
+            end_time=int(end_time) if end_time else int(time.time()),
+            limit=limit,
+            fallback_on_error=True,
+            strict=True,
+        )
+    except (TypeError, ValueError):
+        # A malformed row (strict=True) is a bug in the payload, not an upstream
+        # outage — surface it as-is, as this route always has.
+        raise
     except Exception as e:
-        logger.warning(
-            "get_historical_candles failed: %s — falling back to get_candles", e
+        logger.exception(
+            "Failed to fetch candles for %s on %s of '%s'",
+            trading_pair,
+            connector,
+            name,
         )
-        result = None
+        raise upstream_error("Failed to fetch candles", e)
 
-    # Fallback: if historical returned nothing usable, use regular candles
-    candles_raw = (
-        result
-        if isinstance(result, list)
-        else result.get("data", []) if isinstance(result, dict) else []
-    )
-    if not candles_raw:
-        try:
-            logger.info(
-                "Falling back to get_candles: connector=%s pair=%s interval=%s limit=%s",
-                connector,
-                trading_pair,
-                interval,
-                limit,
-            )
-            result = await client.market_data.get_candles(
-                connector, trading_pair, interval, limit
-            )
-        except Exception as e:
-            logger.exception(
-                "Failed to fetch candles for %s on %s of '%s'",
-                trading_pair,
-                connector,
-                name,
-            )
-            raise upstream_error("Failed to fetch candles", e)
-
-    candles_raw = (
-        result
-        if isinstance(result, list)
-        else result.get("data", []) if isinstance(result, dict) else []
-    )
-
-    candles = []
-    for c in candles_raw:
-        if isinstance(c, dict):
-            candles.append(
-                CandleData(
-                    timestamp=float(c.get("timestamp", 0)),
-                    open=float(c.get("open", 0)),
-                    high=float(c.get("high", 0)),
-                    low=float(c.get("low", 0)),
-                    close=float(c.get("close", 0)),
-                    volume=float(c.get("volume", 0)),
-                )
-            )
-        elif isinstance(c, (list, tuple)) and len(c) >= 6:
-            candles.append(
-                CandleData(
-                    timestamp=float(c[0]),
-                    open=float(c[1]),
-                    high=float(c[2]),
-                    low=float(c[3]),
-                    close=float(c[4]),
-                    volume=float(c[5]),
-                )
-            )
+    candles = [CandleData(**row) for row in rows]
     _candle_cache_put(cache_key, candles, now)
     return candles
 
diff --git a/condor/web/ws_manager.py b/condor/web/ws_manager.py
index 2b79d152..b12c1eba 100644
--- a/condor/web/ws_manager.py
+++ b/condor/web/ws_manager.py
@@ -10,6 +10,7 @@
 from fastapi import WebSocket
 
 from condor import dex_candles
+from condor.fetchers.market_data import fetch_historical_candles, normalize_candle
 from condor.web.auth import decode_jwt
 
 logger = logging.getLogger(__name__)
@@ -244,28 +245,7 @@ def _server_from_channel(channel: str) -> str | None:
     @staticmethod
     def _normalize_candle(c: Any) -> dict | None:
         """Normalize a candle from any format to a uniform dict with float values."""
-        try:
-            if isinstance(c, dict):
-                return {
-                    "timestamp": float(c.get("timestamp", 0)),
-                    "open": float(c.get("open", 0)),
-                    "high": float(c.get("high", 0)),
-                    "low": float(c.get("low", 0)),
-                    "close": float(c.get("close", 0)),
-                    "volume": float(c.get("volume", 0)),
-                }
-            elif isinstance(c, (list, tuple)) and len(c) >= 6:
-                return {
-                    "timestamp": float(c[0]),
-                    "open": float(c[1]),
-                    "high": float(c[2]),
-                    "low": float(c[3]),
-                    "close": float(c[4]),
-                    "volume": float(c[5]),
-                }
-        except (TypeError, ValueError):
-            pass
-        return None
+        return normalize_candle(c)
 
     # -- Lifecycle --
 
@@ -562,33 +542,15 @@ async def _backfill_candles(self, channel: str) -> None:
                 return
 
             client = await cm.get_client(server_name)
-            result = await client.market_data.get_historical_candles(
+            candles = await fetch_historical_candles(
+                client,
                 connector,
                 pair,
                 interval,
                 start_time=start_time,
                 end_time=end_time,
+                limit=min(buf.max_size, 5000),
             )
-
-            candles_raw = (
-                result
-                if isinstance(result, list)
-                else result.get("data", []) if isinstance(result, dict) else []
-            )
-            # Fallback to regular candles if historical returned nothing
-            if not candles_raw:
-                result = await client.market_data.get_candles(
-                    connector, pair, interval, min(buf.max_size, 5000)
-                )
-                candles_raw = (
-                    result
-                    if isinstance(result, list)
-                    else result.get("data", []) if isinstance(result, dict) else []
-                )
-
-            candles = [
-                c for r in candles_raw if (c := self._normalize_candle(r)) is not None
-            ]
             if candles:
                 buf.upsert_many(candles)
                 logger.info(
@@ -1263,27 +1225,17 @@ async def _candle_poll_fallback(self, channel: str) -> None:
                     else:
                         cm = get_config_manager()
                         client = await cm.get_client(server_name)
-                        result = await client.market_data.get_historical_candles(
+                        # No `limit`: this poll only wants the fresh tail of the
+                        # live range, so an empty historical answer stays empty
+                        # rather than pulling a full unrelated window.
+                        candles = await fetch_historical_candles(
+                            client,
                             connector,
                             pair,
                             interval,
                             start_time=now - interval_sec * 5,
                             end_time=now,
                         )
-                        candles_raw = (
-                            result
-                            if isinstance(result, list)
-                            else (
-                                result.get("data", [])
-                                if isinstance(result, dict)
-                                else []
-                            )
-                        )
-                        candles = [
-                            c
-                            for r in candles_raw
-                            if (c := self._normalize_candle(r)) is not None
-                        ]
                     if candles:
                         buf = self._candle_buffers.get(channel)
                         # Broadcast if we have newer candles OR if the latest
diff --git a/tests/test_fetcher_historical_candles.py b/tests/test_fetcher_historical_candles.py
new file mode 100644
index 00000000..a6467c26
--- /dev/null
+++ b/tests/test_fetcher_historical_candles.py
@@ -0,0 +1,312 @@
+"""Tests for ARCH-146: one historical-candles ladder behind `fetch_historical_candles`.
+
+The sequence "ask for a time range → unwrap a list-or-``{"data": [...]}`` payload →
+fall back to ``get_candles`` → normalize dict-or-tuple rows to float OHLCV" used to
+be inlined three times (the REST candles route, the WS backfill, the WS REST poll)
+with subtly different edges. It now lives in ``condor.fetchers.market_data``, with
+the three differences the call sites actually relied on expressed as arguments:
+``limit=None`` (no fallback), ``fallback_on_error`` (swallow a failing historical
+call) and ``strict`` (surface a malformed row instead of dropping it).
+
+These tests pin the unified ladder — both payload shapes, both row shapes, the
+fallback branch — and that each call site still gets its own edge behaviour.
+"""
+
+import asyncio
+
+import pytest
+
+import condor.web.routes.market as market
+from condor.fetchers.market_data import fetch_historical_candles, normalize_candle
+from condor.web.models import WebUser
+from condor.web.ws_manager import WebSocketManager, _CandleBuffer
+
+DICT_ROWS = [
+    {
+        "timestamp": 100,
+        "open": 1,
+        "high": 2,
+        "low": 0.5,
+        "close": 1.5,
+        "volume": 10,
+    },
+    {
+        "timestamp": 160,
+        "open": 1.5,
+        "high": 3,
+        "low": 1.4,
+        "close": 2.0,
+        "volume": 20,
+    },
+]
+
+# The other shape the API answers with: positional rows, extra fields trailing.
+TUPLE_ROWS = [
+    [100, 1, 2, 0.5, 1.5, 10, "ignored"],
+    (160, 1.5, 3, 1.4, 2.0, 20),
+]
+
+EXPECTED = [
+    {
+        "timestamp": 100.0,
+        "open": 1.0,
+        "high": 2.0,
+        "low": 0.5,
+        "close": 1.5,
+        "volume": 10.0,
+    },
+    {
+        "timestamp": 160.0,
+        "open": 1.5,
+        "high": 3.0,
+        "low": 1.4,
+        "close": 2.0,
+        "volume": 20.0,
+    },
+]
+
+
+class FakeMarketData:
+    """Records both candle calls and answers with canned payloads."""
+
+    def __init__(self, historical=None, candles=None, historical_exc=None):
+        self._historical = historical
+        self._candles = candles
+        self._historical_exc = historical_exc
+        self.historical_calls = []
+        self.candles_calls = []
+
+    async def get_historical_candles(
+        self, connector, pair, interval, *, start_time=None, end_time=None
+    ):
+        self.historical_calls.append((connector, pair, interval, start_time, end_time))
+        if self._historical_exc is not None:
+            raise self._historical_exc
+        return self._historical
+
+    async def get_candles(self, connector, pair, interval, limit):
+        self.candles_calls.append((connector, pair, interval, limit))
+        return self._candles
+
+
+class FakeClient:
+    def __init__(self, **kwargs):
+        self.market_data = FakeMarketData(**kwargs)
+
+
+def _fetch(client, **kwargs):
+    return asyncio.run(
+        fetch_historical_candles(client, "binance", "BTC-USDT", "1m", **kwargs)
+    )
+
+
+# --- Payload shapes and row shapes ---
+
+
+@pytest.mark.parametrize(
+    "payload",
+    [
+        pytest.param(DICT_ROWS, id="bare-list-of-dicts"),
+        pytest.param({"data": DICT_ROWS}, id="data-envelope-of-dicts"),
+        pytest.param(TUPLE_ROWS, id="bare-list-of-tuples"),
+        pytest.param({"data": TUPLE_ROWS}, id="data-envelope-of-tuples"),
+    ],
+)
+def test_both_payload_shapes_and_both_row_shapes_normalize_identically(payload):
+    client = FakeClient(historical=payload)
+    assert _fetch(client, start_time=100, end_time=200, limit=500) == EXPECTED
+    assert client.market_data.candles_calls == [], "no fallback when the range answers"
+
+
+def test_unexpected_payload_shape_yields_no_candles():
+    client = FakeClient(historical="not a payload", candles="also not")
+    assert _fetch(client, start_time=100, end_time=200, limit=500) == []
+
+
+# --- The get_candles fallback branch ---
+
+
+@pytest.mark.parametrize(
+    "empty",
+    [pytest.param([], id="empty-list"), pytest.param({"data": []}, id="empty-data")],
+)
+def test_an_empty_range_falls_back_to_get_candles(empty):
+    client = FakeClient(historical=empty, candles={"data": TUPLE_ROWS})
+    assert _fetch(client, start_time=100, end_time=200, limit=42) == EXPECTED
+    assert client.market_data.candles_calls == [("binance", "BTC-USDT", "1m", 42)]
+
+
+def test_no_limit_disables_the_fallback():
+    """The WS REST poll wants the fresh tail or nothing — never a full window."""
+    client = FakeClient(historical=[], candles=DICT_ROWS)
+    assert _fetch(client, start_time=100, end_time=200) == []
+    assert client.market_data.candles_calls == []
+
+
+def test_without_start_time_the_range_call_is_skipped_entirely():
+    client = FakeClient(historical=DICT_ROWS, candles=TUPLE_ROWS)
+    assert _fetch(client, limit=7) == EXPECTED
+    assert client.market_data.historical_calls == []
+    assert client.market_data.candles_calls == [("binance", "BTC-USDT", "1m", 7)]
+
+
+# --- Error handling per call site ---
+
+
+def test_a_failing_range_call_propagates_by_default():
+    """WS backfill/poll abort on failure rather than pulling a different window."""
+    client = FakeClient(historical_exc=RuntimeError("boom"), candles=DICT_ROWS)
+    with pytest.raises(RuntimeError):
+        _fetch(client, start_time=100, end_time=200, limit=5)
+    assert client.market_data.candles_calls == []
+
+
+def test_fallback_on_error_swallows_the_range_failure():
+    """The REST route degrades to the plain window instead of erroring out."""
+    client = FakeClient(historical_exc=RuntimeError("boom"), candles=DICT_ROWS)
+    got = _fetch(client, start_time=100, end_time=200, limit=5, fallback_on_error=True)
+    assert got == EXPECTED
+    assert client.market_data.candles_calls == [("binance", "BTC-USDT", "1m", 5)]
+
+
+def test_a_failing_fallback_always_propagates():
+    client = FakeClient(historical=[])
+
+    async def _raise(*_a, **_kw):
+        raise RuntimeError("fallback down")
+
+    client.market_data.get_candles = _raise
+    with pytest.raises(RuntimeError):
+        _fetch(client, start_time=100, end_time=200, limit=5, fallback_on_error=True)
+
+
+# --- Row normalization ---
+
+
+@pytest.mark.parametrize(
+    "row",
+    [
+        pytest.param([1, 2, 3], id="too-short-a-row"),
+        pytest.param("candle", id="a-string"),
+        pytest.param(None, id="none"),
+    ],
+)
+def test_rows_in_neither_shape_are_dropped(row):
+    assert normalize_candle(row) is None
+
+
+def test_a_malformed_value_is_dropped_by_default_and_raised_when_strict():
+    row = {
+        "timestamp": 100,
+        "open": "n/a",
+        "high": 2,
+        "low": 1,
+        "close": 1,
+        "volume": 1,
+    }
+    assert normalize_candle(row) is None
+    with pytest.raises(ValueError):
+        normalize_candle(row, strict=True)
+
+
+def test_missing_fields_default_to_zero():
+    assert normalize_candle({"timestamp": 100}) == {
+        "timestamp": 100.0,
+        "open": 0.0,
+        "high": 0.0,
+        "low": 0.0,
+        "close": 0.0,
+        "volume": 0.0,
+    }
+
+
+def test_unusable_rows_do_not_sink_the_rest_of_the_batch():
+    client = FakeClient(historical=[DICT_ROWS[0], "junk", TUPLE_ROWS[1]])
+    assert _fetch(client, start_time=100, end_time=200) == EXPECTED
+
+
+# --- The call sites still behave as they did ---
+
+
+class _FakeCM:
+    def __init__(self, client):
+        self._client = client
+
+    def has_server_access(self, *_a, **_kw):
+        return True
+
+    async def get_client(self, _name):
+        return self._client
+
+
+_USER = WebUser(id=1, role="admin")
+
+
+@pytest.fixture(autouse=True)
+def _clean_candle_cache():
+    market._candle_cache.clear()
+    yield
+    market._candle_cache.clear()
+
+
+def _route(client, monkeypatch, *, start_time=None, end_time=None):
+    """Call the route function directly, with every Query default made explicit."""
+    monkeypatch.setattr(market, "get_config_manager", lambda: _FakeCM(client))
+    return asyncio.run(
+        market.get_candles(
+            name="srv",
+            connector="binance",
+            trading_pair="BTC-USDT",
+            interval="1m",
+            limit=1000,
+            start_time=start_time,
+            end_time=end_time,
+            pool_address=None,
+            user=_USER,
+        )
+    )
+
+
+def test_the_route_returns_the_same_payload_with_and_without_a_start_time(monkeypatch):
+    """Same rows in, same CandleData out — one path via the range, one via the window."""
+    ranged = _route(
+        FakeClient(historical={"data": DICT_ROWS}),
+        monkeypatch,
+        start_time=100.0,
+        end_time=200.0,
+    )
+    windowed = _route(FakeClient(candles=TUPLE_ROWS), monkeypatch)
+    assert [c.model_dump() for c in ranged] == EXPECTED
+    assert [c.model_dump() for c in windowed] == EXPECTED
+
+
+def test_the_route_still_falls_back_when_the_range_call_fails(monkeypatch):
+    client = FakeClient(historical_exc=RuntimeError("boom"), candles=DICT_ROWS)
+    got = _route(client, monkeypatch, start_time=100.0, end_time=200.0)
+    assert [c.model_dump() for c in got] == EXPECTED
+
+
+def test_ws_backfill_fills_the_buffer_through_the_fallback(monkeypatch):
+    import config_manager
+
+    client = FakeClient(historical=[], candles={"data": TUPLE_ROWS})
+    monkeypatch.setattr(config_manager, "get_config_manager", lambda: _FakeCM(client))
+
+    mgr = WebSocketManager()
+    channel = "candles:srv:binance:BTC-USDT:1m"
+    buf = _CandleBuffer("1m")
+    mgr._candle_buffers[channel] = buf
+
+    asyncio.run(mgr._backfill_candles(channel))
+
+    assert buf.get_sorted() == EXPECTED
+    # The backfill sizes its fallback off the buffer, capped at 5000.
+    assert client.market_data.candles_calls == [
+        ("binance", "BTC-USDT", "1m", min(buf._max_size, 5000))
+    ]
+
+
+def test_ws_normalize_candle_alias_shares_the_one_implementation():
+    assert WebSocketManager._normalize_candle(TUPLE_ROWS[0]) == EXPECTED[0]
+    assert WebSocketManager._normalize_candle(DICT_ROWS[0]) == EXPECTED[0]
+    assert WebSocketManager._normalize_candle("junk") is None

From 90692c08ad55d76e0fd5b426b3e2dadcc9dc3378 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Fri, 14 Aug 2026 14:48:22 +0300
Subject: [PATCH 062/116] (refactor) ARCH-148: one atomic file write for the
 whole codebase
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Seven independent copies of the tmpfile + os.replace dance lived under
condor/ and had already drifted apart in ways that mattered:

- runtime/registry_file.py wrote to a FIXED sibling tmp name
  (path.with_suffix(".json.tmp")), the exact pattern CORR-032 called out
  as defeating the atomicity — and write_status is called concurrently
  from loops.py, state.py, conversations.py and delegate.py against the
  same status/meta files.
- memory/store.py and routine_hooks.py wrote in the locale encoding, so
  a non-UTF-8 machine produced files another machine could not read.
- routine_hooks.py and reports/store._write_index left the temp file
  under a bare tmpXXXX.tmp name, unlinked from its target.
- only persistence.py fsync-ed before the rename; none fsync-ed the
  parent directory, so the rename itself was not durable.
- reports/store._write_report_html did not create its parent directory.

condor/fsutil.py now holds the single implementation, built as the
safest superset rather than the common denominator: unique O_EXCL temp
file per writer, hidden target-derived temp name, UTF-8 always, fsync of
the data plus the parent directory (opt-out via fsync=False for a hot
writer), the target's existing mode preserved (new files 0600), and no
temp file left behind on success, on failure, or on KeyboardInterrupt.

All seven call sites now delegate to it. persistence.py keeps its backup
rotation and serializes to memory first, so a pickling failure can no
longer cost the rotation. write_status keeps its never-raises wrapper.
JSON kwargs are forwarded verbatim at every call site, so the bytes on
disk are unchanged.

The two memory/skill store tests that spied on Path.write_text now
observe os.replace instead: the property under test (a unique temp name
per writer) is unchanged, but it is no longer tied to the write
mechanism the helper replaced.
---
 condor/agents/canvas.py         |  27 +----
 condor/code_runs.py             |  27 +----
 condor/fsutil.py                | 143 +++++++++++++++++++++++
 condor/memory/store.py          |  39 ++-----
 condor/persistence.py           |  34 ++----
 condor/reports/store.py         |  40 +------
 condor/routine_hooks.py         |  20 +---
 condor/runtime/registry_file.py |  14 +--
 tests/test_fsutil.py            | 196 ++++++++++++++++++++++++++++++++
 tests/test_memory_store.py      |  15 ++-
 tests/test_skill_store.py       |  15 ++-
 11 files changed, 398 insertions(+), 172 deletions(-)
 create mode 100644 condor/fsutil.py
 create mode 100644 tests/test_fsutil.py

diff --git a/condor/agents/canvas.py b/condor/agents/canvas.py
index 1256134f..2a4f7cac 100644
--- a/condor/agents/canvas.py
+++ b/condor/agents/canvas.py
@@ -18,12 +18,12 @@
 
 from __future__ import annotations
 
-import os
 import re
-import tempfile
 from datetime import datetime, timezone
 from pathlib import Path
 
+from condor.fsutil import atomic_write_text
+
 CANVAS_FILE = "canvas.md"
 REVISIONS_FILE = "canvas_revisions.md"
 
@@ -211,31 +211,12 @@ def _append_revision(
 
 
 def _atomic_write(path: Path, content: str) -> None:
-    """tmpfile + ``os.replace``, matching ``condor/reports/store.py``.
+    """tmpfile + ``os.replace``, via the shared :mod:`condor.fsutil` helper.
 
     A tick can be cancelled mid-write; a half-written canvas would then be
     inlined into the next prompt.
     """
-    path.parent.mkdir(parents=True, exist_ok=True)
-    tmp = tempfile.NamedTemporaryFile(
-        mode="w",
-        encoding="utf-8",
-        dir=str(path.parent),
-        prefix=f".{path.name}.",
-        suffix=".tmp",
-        delete=False,
-    )
-    try:
-        tmp.write(content)
-        tmp.close()
-        os.replace(tmp.name, path)
-    except Exception:
-        tmp.close()
-        try:
-            os.unlink(tmp.name)
-        except OSError:
-            pass
-        raise
+    atomic_write_text(path, content)
 
 
 # ---------------------------------------------------------------------------
diff --git a/condor/code_runs.py b/condor/code_runs.py
index 8078d492..8a37bc3a 100644
--- a/condor/code_runs.py
+++ b/condor/code_runs.py
@@ -15,14 +15,14 @@
 
 import json
 import logging
-import os
 import re
 import secrets
-import tempfile
 import time
 from dataclasses import asdict, dataclass
 from pathlib import Path
 
+from condor.fsutil import atomic_write_json
+
 logger = logging.getLogger(__name__)
 
 # Anchored at the repo root, not the cwd: the main process writes this dir and
@@ -145,29 +145,10 @@ def _persist_index(self) -> None:
         self._write_json(self._index_path, self._index)
 
     def _write_json(self, path: Path | None, data) -> None:
-        """Atomic create-or-replace, same tempfile + os.replace as the report store."""
+        """Atomic create-or-replace, via the shared :mod:`condor.fsutil` helper."""
         if path is None:
             return
-        path.parent.mkdir(parents=True, exist_ok=True)
-        tmp = tempfile.NamedTemporaryFile(
-            mode="w",
-            encoding="utf-8",
-            dir=str(path.parent),
-            prefix=f".{path.name}.",
-            suffix=".tmp",
-            delete=False,
-        )
-        try:
-            json.dump(data, tmp, ensure_ascii=False)
-            tmp.close()
-            os.replace(tmp.name, path)
-        except Exception:
-            tmp.close()
-            try:
-                os.unlink(tmp.name)
-            except OSError:
-                pass
-            raise
+        atomic_write_json(path, data, ensure_ascii=False)
 
 
 _store: CodeRunStore | None = None
diff --git a/condor/fsutil.py b/condor/fsutil.py
new file mode 100644
index 00000000..3577de41
--- /dev/null
+++ b/condor/fsutil.py
@@ -0,0 +1,143 @@
+"""One atomic file write for the whole codebase.
+
+Seven independent copies of the "write a temp file, then ``os.replace`` it over
+the target" dance used to live in ``condor/`` (memory store, canvas, routine
+hooks, code runs, the report store twice, the runtime status registry and the
+pickle persistence). They had already drifted apart in ways that mattered:
+only one had ``fsync``, only one wrote to a *fixed* temp name (which defeats
+the atomicity as soon as two writers race — CORR-032), two wrote in the locale
+encoding instead of UTF-8, and two left the temp file visible in a directory
+the app lists. ARCH-148 collapses them into this module.
+
+The implementation here is the **safest superset** of what the copies did:
+
+* **Unique temp file per writer.** ``tempfile.mkstemp`` opens it ``O_EXCL`` in
+  the target's own directory, so concurrent writers never share — and thus
+  never tear — the temp file, and ``os.replace`` stays a same-filesystem
+  rename.
+* **Hidden, target-derived temp name** (``.<target>.<random>.tmp``), so a
+  half-written file is never picked up by a listing of the directory and is
+  obvious to a human who finds one.
+* **Durability.** The data is ``fsync``-ed before the rename and the parent
+  directory is ``fsync``-ed after it, so a power loss leaves either the old
+  file or the new one — never a zero-length survivor of the rename. Pass
+  ``fsync=False`` on a writer hot enough that the barrier costs more than the
+  data is worth; every current caller keeps it on (an agent tick, a report
+  save and a config save are all far slower than the flush).
+* **UTF-8 always**, so a file written on a machine with a non-UTF-8 locale is
+  still readable on one that has it.
+* **Mode preserved.** ``mkstemp`` creates ``0600``, which would silently
+  tighten a file that already existed with looser permissions; the target's
+  current mode is carried over when there is one, and new files stay ``0600``.
+* **No temp file left behind**, on success (the rename consumes it) or on any
+  failure, including ``KeyboardInterrupt``.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+import tempfile
+from pathlib import Path
+from typing import Any
+
+__all__ = ["atomic_write_bytes", "atomic_write_text", "atomic_write_json"]
+
+# Mode for a file this helper creates from scratch. Matches what
+# ``tempfile.mkstemp`` produces, i.e. what most of the folded-in copies already
+# left on disk: these are the application's own data files, not shared ones.
+_NEW_FILE_MODE = 0o600
+
+
+def atomic_write_bytes(
+    path: str | Path, data: bytes, *, fsync: bool = True, mkdir: bool = True
+) -> None:
+    """Create-or-replace ``path`` with ``data``, atomically.
+
+    A reader of ``path`` sees either the previous contents or the complete new
+    ones, never a partial write, and a crash at any point leaves the previous
+    file intact.
+    """
+    path = Path(path)
+    if mkdir:
+        path.parent.mkdir(parents=True, exist_ok=True)
+
+    mode = _target_mode(path)
+    fd, tmp_name = tempfile.mkstemp(
+        dir=str(path.parent), prefix=f".{path.name}.", suffix=".tmp"
+    )
+    try:
+        try:
+            handle = os.fdopen(fd, "wb")
+        except BaseException:
+            os.close(fd)
+            raise
+        with handle:
+            handle.write(data)
+            if fsync:
+                handle.flush()
+                os.fsync(handle.fileno())
+        os.chmod(tmp_name, mode)
+        os.replace(tmp_name, path)
+    except BaseException:
+        # Nothing published: drop the temp file rather than leave litter next
+        # to the real one.
+        try:
+            os.unlink(tmp_name)
+        except OSError:
+            pass
+        raise
+
+    if fsync:
+        _fsync_dir(path.parent)
+
+
+def atomic_write_text(
+    path: str | Path,
+    text: str,
+    *,
+    encoding: str = "utf-8",
+    fsync: bool = True,
+    mkdir: bool = True,
+) -> None:
+    """:func:`atomic_write_bytes` for text. UTF-8 unless told otherwise."""
+    atomic_write_bytes(path, text.encode(encoding), fsync=fsync, mkdir=mkdir)
+
+
+def atomic_write_json(
+    path: str | Path,
+    data: Any,
+    *,
+    fsync: bool = True,
+    mkdir: bool = True,
+    **json_kw: Any,
+) -> None:
+    """:func:`atomic_write_text` over ``json.dumps(data, **json_kw)``.
+
+    Serialization happens *before* the temp file is created, so a value that
+    cannot be encoded raises without having touched the filesystem at all.
+    """
+    atomic_write_text(path, json.dumps(data, **json_kw), fsync=fsync, mkdir=mkdir)
+
+
+def _target_mode(path: Path) -> int:
+    """Permissions to publish with: the target's own, or ``0600`` if new."""
+    try:
+        return stat.S_IMODE(path.stat().st_mode)
+    except OSError:
+        return _NEW_FILE_MODE
+
+
+def _fsync_dir(directory: Path) -> None:
+    """Flush the rename itself. Best effort: not every filesystem allows it."""
+    try:
+        fd = os.open(str(directory), os.O_RDONLY)
+    except OSError:
+        return
+    try:
+        os.fsync(fd)
+    except OSError:
+        pass
+    finally:
+        os.close(fd)
diff --git a/condor/memory/store.py b/condor/memory/store.py
index db1225cd..0284824e 100644
--- a/condor/memory/store.py
+++ b/condor/memory/store.py
@@ -22,14 +22,14 @@
 from __future__ import annotations
 
 import json
-import os
 import re
-import uuid
 from datetime import datetime, timezone
 from pathlib import Path
 
 import yaml
 
+from condor.fsutil import atomic_write_text
+
 from .paths import store_root
 
 _VALID_TYPES = ("preference", "fact", "feedback", "reference")
@@ -109,22 +109,15 @@ def _atomic_write(path: Path, text: str) -> None:
 
     Free function (not a method) so every per-assistant store — memories and
     skills alike — shares one implementation instead of a verbatim copy. The
-    temp file is named uniquely per writer (pid + uuid) so two processes
-    writing the same slug concurrently never share — and thus never tear — the
-    temp file; ``os.replace`` then publishes each writer's complete file
-    atomically (FEAT-003 runs the same store from the main process and the MCP
-    subprocess).
+    temp file is unique per writer, so two processes writing the same slug
+    concurrently never share — and thus never tear — it; ``os.replace`` then
+    publishes each writer's complete file atomically (FEAT-003 runs the same
+    store from the main process and the MCP subprocess).
+
+    Thin alias over :func:`condor.fsutil.atomic_write_text`, which is the one
+    implementation of this dance in the codebase (ARCH-148).
     """
-    path.parent.mkdir(parents=True, exist_ok=True)
-    tmp = path.with_name(f".{path.name}.{os.getpid()}.{uuid.uuid4().hex}.tmp")
-    try:
-        tmp.write_text(text)
-        os.replace(tmp, path)
-    finally:
-        try:
-            tmp.unlink()
-        except FileNotFoundError:
-            pass
+    atomic_write_text(path, text)
 
 
 def _trim_audit(audit_file: Path, cap: int | None = None) -> None:
@@ -146,17 +139,7 @@ def _trim_audit(audit_file: Path, cap: int | None = None) -> None:
     if len(lines) <= cap * 2:
         return
     tail = lines[-cap:]
-    tmp = audit_file.with_name(
-        f".{audit_file.name}.{os.getpid()}.{uuid.uuid4().hex}.tmp"
-    )
-    try:
-        tmp.write_text("".join(tail))
-        os.replace(tmp, audit_file)
-    finally:
-        try:
-            tmp.unlink()
-        except FileNotFoundError:
-            pass
+    _atomic_write(audit_file, "".join(tail))
 
 
 class MemoryStore:
diff --git a/condor/persistence.py b/condor/persistence.py
index f7db4e1e..d9e242d3 100644
--- a/condor/persistence.py
+++ b/condor/persistence.py
@@ -10,10 +10,10 @@
    to prevent pickle bloat.
 """
 
+import io
 import logging
 import os
 import pickle
-import tempfile
 from copy import deepcopy
 from pathlib import Path
 from typing import Any, Dict, Optional
@@ -21,6 +21,8 @@
 from telegram.ext import PicklePersistence
 from telegram.ext._picklepersistence import _BotPickler, _BotUnpickler
 
+from condor.fsutil import atomic_write_bytes
+
 logger = logging.getLogger(__name__)
 
 # Keys that live in user_data at runtime but should NOT be persisted.
@@ -60,20 +62,12 @@ def _dump_singlefile(self) -> None:
         }
 
         target = self.filepath
-        tmp_fd = None
-        tmp_path = None
 
         try:
-            # 1. Write to a temp file in the same directory
-            tmp_fd, tmp_path = tempfile.mkstemp(
-                suffix=".tmp",
-                dir=str(target.parent),
-            )
-            with os.fdopen(tmp_fd, "wb") as f:
-                tmp_fd = None  # os.fdopen takes ownership
-                _BotPickler(self.bot, f, protocol=pickle.HIGHEST_PROTOCOL).dump(data)
-                f.flush()
-                os.fsync(f.fileno())
+            # 1. Serialize first: a pickling failure must not cost us the
+            #    backup rotation below, let alone the current file.
+            buf = io.BytesIO()
+            _BotPickler(self.bot, buf, protocol=pickle.HIGHEST_PROTOCOL).dump(data)
 
             # 2. Rotate current file to .bak (best-effort)
             bak_path = target.with_suffix(target.suffix + ".bak")
@@ -83,22 +77,12 @@ def _dump_singlefile(self) -> None:
                 except OSError:
                     logger.warning("Failed to create backup of pickle file")
 
-            # 3. Atomic rename of temp → target
-            os.replace(tmp_path, str(target))
-            tmp_path = None  # success – nothing to clean up
+            # 3. Atomic temp-file → fsync → rename (shared helper, ARCH-148)
+            atomic_write_bytes(target, buf.getvalue())
 
         except Exception:
             logger.exception("Failed to write persistence file")
             raise
-        finally:
-            # Clean up temp file on failure
-            if tmp_fd is not None:
-                os.close(tmp_fd)
-            if tmp_path is not None:
-                try:
-                    os.unlink(tmp_path)
-                except OSError:
-                    pass
 
     # ------------------------------------------------------------------
     # Load: fall back to .bak on corruption
diff --git a/condor/reports/store.py b/condor/reports/store.py
index 94e952fc..7d00e295 100644
--- a/condor/reports/store.py
+++ b/condor/reports/store.py
@@ -6,10 +6,11 @@
 import contextvars
 import json
 import os
-import tempfile
 from contextlib import contextmanager
 from pathlib import Path
 
+from condor.fsutil import atomic_write_json, atomic_write_text
+
 # reports/ is a repository-root output directory, not this source package.
 CHARTS_DIR = Path(__file__).resolve().parents[2] / "reports"
 INDEX_FILE = CHARTS_DIR / "reports_index.json"
@@ -112,45 +113,12 @@ def _read_index() -> list[dict]:
 
 
 def _write_index(entries: list[dict]) -> None:
-    charts_dir = _charts_dir()
-    charts_dir.mkdir(exist_ok=True)
-    tmp = tempfile.NamedTemporaryFile(
-        mode="w", encoding="utf-8", dir=str(charts_dir), suffix=".tmp", delete=False
-    )
-    try:
-        json.dump(entries, tmp, indent=2, ensure_ascii=False)
-        tmp.close()
-        os.replace(tmp.name, str(_index_file()))
-    except Exception:
-        tmp.close()
-        try:
-            os.unlink(tmp.name)
-        except OSError:
-            pass
-        raise
+    atomic_write_json(_index_file(), entries, indent=2, ensure_ascii=False)
 
 
 def _write_report_html(path: Path, content: str) -> None:
     """Atomically create or replace a report HTML file."""
-    tmp = tempfile.NamedTemporaryFile(
-        mode="w",
-        encoding="utf-8",
-        dir=str(path.parent),
-        prefix=f".{path.name}.",
-        suffix=".tmp",
-        delete=False,
-    )
-    try:
-        tmp.write(content)
-        tmp.close()
-        os.replace(tmp.name, path)
-    except Exception:
-        tmp.close()
-        try:
-            os.unlink(tmp.name)
-        except OSError:
-            pass
-        raise
+    atomic_write_text(path, content)
 
 
 def list_reports(
diff --git a/condor/routine_hooks.py b/condor/routine_hooks.py
index 521e01be..2ce551a6 100644
--- a/condor/routine_hooks.py
+++ b/condor/routine_hooks.py
@@ -16,12 +16,12 @@
 
 import json
 import logging
-import os
 import re
-import tempfile
 from pathlib import Path
 from typing import Any
 
+from condor.fsutil import atomic_write_json
+
 logger = logging.getLogger(__name__)
 
 _HOOKS_FILE = Path("data") / "routine_hooks.json"
@@ -45,21 +45,7 @@ def _read_all() -> dict[str, dict]:
 
 
 def _write_all(data: dict[str, dict]) -> None:
-    _HOOKS_FILE.parent.mkdir(parents=True, exist_ok=True)
-    tmp = tempfile.NamedTemporaryFile(
-        mode="w", dir=str(_HOOKS_FILE.parent), suffix=".tmp", delete=False
-    )
-    try:
-        json.dump(data, tmp, indent=2)
-        tmp.close()
-        os.replace(tmp.name, str(_HOOKS_FILE))
-    except Exception:
-        tmp.close()
-        try:
-            os.unlink(tmp.name)
-        except OSError:
-            pass
-        raise
+    atomic_write_json(_HOOKS_FILE, data, indent=2)
 
 
 def _default_config() -> dict:
diff --git a/condor/runtime/registry_file.py b/condor/runtime/registry_file.py
index 2822a00c..01d8fb90 100644
--- a/condor/runtime/registry_file.py
+++ b/condor/runtime/registry_file.py
@@ -20,6 +20,8 @@
 from pathlib import Path
 from typing import Any
 
+from condor.fsutil import atomic_write_json
+
 log = logging.getLogger(__name__)
 
 STATUS_FILENAME = "status.json"
@@ -71,17 +73,13 @@ def write_status(
     current["pid"] = os.getpid()
     current["updated_at"] = time.time()
 
-    tmp = path.with_suffix(".json.tmp")
     try:
-        path.parent.mkdir(parents=True, exist_ok=True)
-        tmp.write_text(json.dumps(current, indent=2), encoding="utf-8")
-        os.replace(tmp, path)  # atomic within a filesystem
+        # Unique temp file per writer, inside the target's directory: several
+        # processes update the same status/meta file (loops, state, delegate),
+        # and a shared temp name would let them tear each other's write.
+        atomic_write_json(path, current, indent=2)
     except Exception:
         log.warning("Could not write status for %s", session_dir, exc_info=True)
-        try:
-            tmp.unlink(missing_ok=True)
-        except Exception:
-            pass
 
 
 def read_status(
diff --git a/tests/test_fsutil.py b/tests/test_fsutil.py
new file mode 100644
index 00000000..e526450b
--- /dev/null
+++ b/tests/test_fsutil.py
@@ -0,0 +1,196 @@
+"""Tests for the shared atomic-write helper (ARCH-148).
+
+Seven copies of tmpfile+os.replace were folded into :mod:`condor.fsutil`; these
+pin the three properties every one of them was written to guarantee — the new
+contents land, a failure mid-write leaves the previous file untouched, and no
+temp file survives either outcome — plus the hardening the merged helper adds.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+import threading
+
+import pytest
+
+from condor.fsutil import atomic_write_bytes, atomic_write_json, atomic_write_text
+
+
+def _tmp_files(directory):
+    return sorted(p.name for p in directory.glob("*.tmp"))
+
+
+# ── Success path ──
+
+
+def test_replaces_existing_file(tmp_path):
+    target = tmp_path / "state.txt"
+    target.write_text("old")
+
+    atomic_write_text(target, "new")
+
+    assert target.read_text() == "new"
+    assert _tmp_files(tmp_path) == []
+
+
+def test_creates_file_and_parent_dirs(tmp_path):
+    target = tmp_path / "deep" / "nested" / "state.txt"
+
+    atomic_write_text(target, "hello")
+
+    assert target.read_text() == "hello"
+    assert _tmp_files(target.parent) == []
+
+
+def test_writes_utf8_regardless_of_locale(tmp_path):
+    target = tmp_path / "memo.md"
+
+    atomic_write_text(target, "café ☕")
+
+    assert target.read_bytes() == "café ☕".encode("utf-8")
+
+
+def test_bytes_and_json_round_trip(tmp_path):
+    blob = tmp_path / "blob.bin"
+    atomic_write_bytes(blob, b"\x00\xff\x10")
+    assert blob.read_bytes() == b"\x00\xff\x10"
+
+    index = tmp_path / "index.json"
+    atomic_write_json(index, [{"id": "a"}], indent=2)
+    assert json.loads(index.read_text(encoding="utf-8")) == [{"id": "a"}]
+    # json kwargs are forwarded verbatim, so callers keep their exact bytes.
+    assert index.read_text(encoding="utf-8").startswith("[\n  {")
+
+
+def test_fsync_can_be_disabled(tmp_path):
+    target = tmp_path / "hot.json"
+
+    atomic_write_json(target, {"tick": 1}, fsync=False)
+
+    assert json.loads(target.read_text(encoding="utf-8")) == {"tick": 1}
+    assert _tmp_files(tmp_path) == []
+
+
+# ── Failure path ──
+
+
+def test_failure_mid_write_leaves_original_intact(tmp_path, monkeypatch):
+    target = tmp_path / "state.txt"
+    target.write_text("original")
+
+    real_replace = os.replace
+
+    def boom(src, dst):
+        # Fail exactly at publication: the temp file is fully written by now,
+        # which is the worst moment for the previous contents.
+        raise OSError("disk full")
+
+    monkeypatch.setattr(os, "replace", boom)
+    with pytest.raises(OSError):
+        atomic_write_text(target, "replacement")
+    monkeypatch.setattr(os, "replace", real_replace)
+
+    assert target.read_text() == "original"
+    assert _tmp_files(tmp_path) == []
+
+
+def test_failure_leaves_no_tmp_and_no_target_when_new(tmp_path, monkeypatch):
+    target = tmp_path / "brand-new.txt"
+
+    def boom(src, dst):
+        raise OSError("disk full")
+
+    monkeypatch.setattr(os, "replace", boom)
+    with pytest.raises(OSError):
+        atomic_write_text(target, "content")
+
+    assert not target.exists()
+    assert _tmp_files(tmp_path) == []
+
+
+def test_unserializable_json_never_touches_the_filesystem(tmp_path):
+    target = tmp_path / "index.json"
+    target.write_text("[]")
+
+    with pytest.raises(TypeError):
+        atomic_write_json(target, {"fn": object()})
+
+    assert target.read_text() == "[]"
+    assert _tmp_files(tmp_path) == []
+
+
+def test_keyboard_interrupt_cleans_up_tmp(tmp_path, monkeypatch):
+    """``except Exception`` would leak the temp file here; ``BaseException`` does not."""
+    target = tmp_path / "state.txt"
+    target.write_text("original")
+
+    def interrupt(src, dst):
+        raise KeyboardInterrupt
+
+    monkeypatch.setattr(os, "replace", interrupt)
+    with pytest.raises(KeyboardInterrupt):
+        atomic_write_bytes(target, b"replacement")
+
+    assert target.read_text() == "original"
+    assert _tmp_files(tmp_path) == []
+
+
+# ── Hardening the merged helper adds ──
+
+
+def test_tmp_name_is_unique_per_writer(tmp_path, monkeypatch):
+    """A fixed temp name would let two writers tear each other's file."""
+    seen: list[str] = []
+    target = tmp_path / "status.json"
+    real_replace = os.replace
+
+    def spy(src, dst):
+        seen.append(os.path.basename(src))
+        return real_replace(src, dst)
+
+    monkeypatch.setattr(os, "replace", spy)
+    atomic_write_text(target, "a")
+    atomic_write_text(target, "b")
+
+    assert len(seen) == 2
+    assert seen[0] != seen[1]
+    # Hidden and target-derived, so a listing of the directory never picks a
+    # half-written file up and a stray one is traceable to its target.
+    assert all(name.startswith(".status.json.") for name in seen)
+    assert all(name.endswith(".tmp") for name in seen)
+
+
+def test_concurrent_writers_never_publish_a_torn_file(tmp_path):
+    target = tmp_path / "shared.txt"
+    payloads = [chr(ord("a") + i) * 20_000 for i in range(8)]
+    barrier = threading.Barrier(len(payloads))
+
+    def writer(text):
+        barrier.wait()
+        for _ in range(10):
+            atomic_write_text(target, text)
+
+    threads = [threading.Thread(target=writer, args=(p,)) for p in payloads]
+    for t in threads:
+        t.start()
+    for t in threads:
+        t.join()
+
+    survivor = target.read_text()
+    assert survivor in payloads  # exactly one writer's payload, not a blend
+    assert _tmp_files(tmp_path) == []
+
+
+def test_new_file_is_private_and_existing_mode_is_preserved(tmp_path):
+    fresh = tmp_path / "fresh.txt"
+    atomic_write_text(fresh, "x")
+    assert stat.S_IMODE(fresh.stat().st_mode) == 0o600
+
+    loose = tmp_path / "loose.txt"
+    loose.write_text("x")
+    loose.chmod(0o644)
+    atomic_write_text(loose, "y")
+    # Rewriting must not silently tighten a file someone widened on purpose.
+    assert stat.S_IMODE(loose.stat().st_mode) == 0o644
diff --git a/tests/test_memory_store.py b/tests/test_memory_store.py
index e4f6f68c..ef9f38c0 100644
--- a/tests/test_memory_store.py
+++ b/tests/test_memory_store.py
@@ -194,14 +194,17 @@ def test_atomic_write_uses_unique_tmp_per_writer(memory_root, monkeypatch):
     target = s.memories_dir / "one.md"
     target.parent.mkdir(parents=True, exist_ok=True)
 
-    orig = Path.write_text
+    # Observed at the rename, not at the write call, so the assertion survives
+    # any change of write mechanism inside condor.fsutil (ARCH-148).
+    import os
 
-    def spy(self, text, *args, **kwargs):
-        if self.name.endswith(".tmp"):
-            seen.append(self.name)
-        return orig(self, text, *args, **kwargs)
+    orig = os.replace
 
-    monkeypatch.setattr(Path, "write_text", spy)
+    def spy(src, dst):
+        seen.append(os.path.basename(src))
+        return orig(src, dst)
+
+    monkeypatch.setattr(os, "replace", spy)
     _atomic_write(target, "a")
     _atomic_write(target, "b")
 
diff --git a/tests/test_skill_store.py b/tests/test_skill_store.py
index d15cff19..8d6cf27f 100644
--- a/tests/test_skill_store.py
+++ b/tests/test_skill_store.py
@@ -562,14 +562,17 @@ def test_atomic_write_uses_unique_tmp_per_writer(project_root, monkeypatch):
     target = s.skills_dir / "one" / "SKILL.md"
     target.parent.mkdir(parents=True, exist_ok=True)
 
-    orig = Path.write_text
+    # Observed at the rename, not at the write call, so the assertion survives
+    # any change of write mechanism inside condor.fsutil (ARCH-148).
+    import os
 
-    def spy(self, text, *args, **kwargs):
-        if self.name.endswith(".tmp"):
-            seen.append(self.name)
-        return orig(self, text, *args, **kwargs)
+    orig = os.replace
 
-    monkeypatch.setattr(Path, "write_text", spy)
+    def spy(src, dst):
+        seen.append(os.path.basename(src))
+        return orig(src, dst)
+
+    monkeypatch.setattr(os, "replace", spy)
     _atomic_write(target, "a")
     _atomic_write(target, "b")
 

From 9d81d6b0efa3562bc2d999f94f9433c2b5095b6e Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Fri, 14 Aug 2026 14:52:34 +0300
Subject: [PATCH 063/116] (fix) SDS: track subscriber callback tasks (CORR-141)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

_fire_callbacks dispatched every subscriber callback with a bare
asyncio.ensure_future and dropped the task. The event loop keeps only a
weak reference, so the task could be garbage-collected mid-await, and an
exception inside the callback surfaced only as asyncio's "Task exception
was never retrieved" at GC time — never on the SDS logger.

Mirror the _track_oneshot pattern from ws_manager (CORR-107): keep a
strong ref in _callback_tasks, discard it on completion, and log the
retrieved exception with the subscriber id. stop() now cancels pending
callback tasks alongside _poll_task.
---
 condor/server_data_service.py    |  44 ++++++++-
 tests/test_sds_callback_tasks.py | 152 +++++++++++++++++++++++++++++++
 2 files changed, 194 insertions(+), 2 deletions(-)
 create mode 100644 tests/test_sds_callback_tasks.py

diff --git a/condor/server_data_service.py b/condor/server_data_service.py
index b6ccd9ee..965df7bf 100644
--- a/condor/server_data_service.py
+++ b/condor/server_data_service.py
@@ -255,6 +255,10 @@ def __init__(self):
         self._last_cleanup = time.time()
         # Sync listeners (e.g. WebSocketManager broadcasts)
         self._listeners: List[Callable] = []
+        # Strong refs to fire-and-forget subscriber-callback tasks so the GC
+        # can't cancel them mid-flight (the event loop only keeps a weak
+        # reference). Entries auto-remove on completion.
+        self._callback_tasks: set[asyncio.Task] = set()
 
     # ------ Fetch registry ------
 
@@ -619,6 +623,10 @@ def stop(self) -> None:
         if self._poll_task and not self._poll_task.done():
             self._poll_task.cancel()
             logger.info("ServerDataService stopped")
+        for task in list(self._callback_tasks):
+            if not task.done():
+                task.cancel()
+        self._callback_tasks.clear()
 
     # ------ Poll loop ------
 
@@ -753,17 +761,49 @@ async def _do_fetch_and_cache(self, key: CacheKey) -> Optional[Any]:
 
         return result
 
+    def _track_callback_task(self, task: asyncio.Task, subscriber_id: str) -> None:
+        """Keep a strong reference to a fire-and-forget subscriber callback
+        until it finishes, so the GC can't silently cancel it mid-await (the
+        event loop only holds a weak reference). The reference is dropped
+        automatically on completion."""
+        self._callback_tasks.add(task)
+        task.add_done_callback(
+            lambda t, sid=subscriber_id: self._on_callback_done(t, sid)
+        )
+
+    def _on_callback_done(self, task: asyncio.Task, subscriber_id: str) -> None:
+        """Release the strong reference and surface failures on this module's
+        logger. Nobody awaits a subscriber callback, so without this a crash
+        would only show up as asyncio's "Task exception was never retrieved"
+        at GC time, leaving the subscriber silently broken."""
+        self._callback_tasks.discard(task)
+        if task.cancelled():
+            return
+        exc = task.exception()
+        if exc is not None:
+            logger.error(
+                "SDS callback error for %s: %s", subscriber_id, exc, exc_info=exc
+            )
+
     def _fire_callbacks(self, key: CacheKey, old_value: Any, new_value: Any) -> None:
-        """Fire subscriber callbacks asynchronously."""
+        """Fire subscriber callbacks asynchronously.
+
+        Each callback runs as a tracked task: a failing subscriber is logged
+        and never blocks the others or the caller.
+        """
         subs = self._subscriptions.get(key)
         if not subs:
             return
         for sub in subs.values():
             if sub.callback:
                 try:
-                    asyncio.ensure_future(sub.callback(key, old_value, new_value))
+                    task = asyncio.ensure_future(
+                        sub.callback(key, old_value, new_value)
+                    )
                 except Exception as e:
                     logger.debug("SDS callback error for %s: %s", sub.subscriber_id, e)
+                else:
+                    self._track_callback_task(task, sub.subscriber_id)
 
     def _cleanup_stale(self) -> None:
         """Remove cache entries with no subscribers and expired TTL."""
diff --git a/tests/test_sds_callback_tasks.py b/tests/test_sds_callback_tasks.py
new file mode 100644
index 00000000..1c45205b
--- /dev/null
+++ b/tests/test_sds_callback_tasks.py
@@ -0,0 +1,152 @@
+"""Tests for CORR-141: SDS subscriber callbacks run as tracked tasks.
+
+``_fire_callbacks`` used to dispatch every subscriber callback with a bare
+``asyncio.ensure_future`` and drop the task: the event loop keeps only a weak
+reference, so the task could be garbage-collected mid-await, and a crash
+inside the callback surfaced only as asyncio's "Task exception was never
+retrieved" at GC time. Callbacks are now tracked with a strong reference and
+their exceptions are retrieved and logged.
+"""
+
+import asyncio
+import gc
+import logging
+
+from condor.server_data_service import ServerDataService, ServerDataType
+
+
+def _make_sds() -> ServerDataService:
+    """Fresh (non-singleton) SDS with no fetchers registered."""
+    sds = ServerDataService()
+
+    async def _fake_get_client(server_name):
+        return object()
+
+    sds._get_client = _fake_get_client
+    return sds
+
+
+def test_fired_callback_survives_gc_and_task_set_drains():
+    """A fired callback keeps a strong ref until it completes, then drains."""
+    ran = {"done": False}
+    started = asyncio.Event()
+
+    async def slow_callback(key, old_value, new_value):
+        started.set()
+        await asyncio.sleep(0.05)
+        ran["done"] = True
+
+    async def _drive():
+        sds = _make_sds()
+        await sds.subscribe(
+            "srv", ServerDataType.PORTFOLIO, "sub", callback=slow_callback
+        )
+
+        sds.put("srv", ServerDataType.PORTFOLIO, {"v": 1})
+        await started.wait()
+
+        # The task is strongly referenced while in flight, so a GC pass in the
+        # middle of the await cannot cancel it.
+        assert len(sds._callback_tasks) == 1, "callback task was not tracked"
+        gc.collect()
+
+        await asyncio.gather(*list(sds._callback_tasks), return_exceptions=True)
+        await asyncio.sleep(0)  # let done-callbacks run
+        return sds
+
+    sds = asyncio.run(_drive())
+
+    assert ran["done"] is True, "callback was lost mid-flight"
+    assert sds._callback_tasks == set(), "done-callback must discard the task"
+
+
+def test_callback_exception_is_logged_and_isolated(caplog):
+    """A raising subscriber is logged on the SDS logger; others still run."""
+    good_ran = {"count": 0}
+
+    async def boom_callback(key, old_value, new_value):
+        raise RuntimeError("subscriber exploded")
+
+    async def good_callback(key, old_value, new_value):
+        good_ran["count"] += 1
+
+    async def _drive():
+        sds = _make_sds()
+        await sds.subscribe(
+            "srv", ServerDataType.PORTFOLIO, "bad_sub", callback=boom_callback
+        )
+        await sds.subscribe(
+            "srv", ServerDataType.PORTFOLIO, "good_sub", callback=good_callback
+        )
+
+        sds.put("srv", ServerDataType.PORTFOLIO, {"v": 1})
+        await asyncio.gather(*list(sds._callback_tasks), return_exceptions=True)
+        await asyncio.sleep(0)  # let done-callbacks run
+        return sds
+
+    with caplog.at_level(logging.ERROR, logger="condor.server_data_service"):
+        sds = asyncio.run(_drive())
+
+    messages = [
+        r.getMessage() for r in caplog.records if r.name == "condor.server_data_service"
+    ]
+    assert any(
+        "bad_sub" in m and "subscriber exploded" in m for m in messages
+    ), f"callback failure was not logged: {messages}"
+
+    assert good_ran["count"] == 1, "a failing subscriber must not block the others"
+    assert sds._callback_tasks == set(), "failed task must still be discarded"
+
+
+def test_publisher_survives_failing_callback():
+    """``put`` never raises because a subscriber callback blew up."""
+
+    async def boom_callback(key, old_value, new_value):
+        raise RuntimeError("subscriber exploded")
+
+    async def _drive():
+        sds = _make_sds()
+        await sds.subscribe(
+            "srv", ServerDataType.PORTFOLIO, "bad_sub", callback=boom_callback
+        )
+
+        sds.put("srv", ServerDataType.PORTFOLIO, {"v": 1})
+        sds.put("srv", ServerDataType.PORTFOLIO, {"v": 2})
+        await asyncio.gather(*list(sds._callback_tasks), return_exceptions=True)
+        await asyncio.sleep(0)
+        return sds
+
+    sds = asyncio.run(_drive())
+
+    # Publisher kept writing through the failures.
+    assert sds.get("srv", ServerDataType.PORTFOLIO) == {"v": 2}
+
+
+def test_stop_cancels_pending_callback_tasks():
+    """``stop()`` cancels in-flight callback tasks and clears the set."""
+    finished = {"done": False}
+
+    async def never_ending_callback(key, old_value, new_value):
+        await asyncio.sleep(30)
+        finished["done"] = True
+
+    async def _drive():
+        sds = _make_sds()
+        await sds.subscribe(
+            "srv", ServerDataType.PORTFOLIO, "sub", callback=never_ending_callback
+        )
+
+        sds.put("srv", ServerDataType.PORTFOLIO, {"v": 1})
+        await asyncio.sleep(0)  # let the task start
+        pending = list(sds._callback_tasks)
+        assert len(pending) == 1
+
+        sds.stop()
+        await asyncio.gather(*pending, return_exceptions=True)
+        return sds, pending
+
+    sds, pending = asyncio.run(_drive())
+
+    assert pending[0].cancelled(), "pending callback task must be cancelled by stop()"
+    assert finished["done"] is False
+    assert sds._callback_tasks == set()

From b328783c9a5ecfc9371ae482af2d56827095bba1 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Fri, 14 Aug 2026 14:59:06 +0300
Subject: [PATCH 064/116] (fix) routine_store: bound the results dict and drop
 it with its instance
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

RoutineStore._results only ever grew. Every execute() mints a fresh
instance_id and nothing ever popped the entry, so each one-shot run pinned
a RoutineResult forever — chart_image raw PNG bytes included — in a process
designed to run for weeks.

Results must still outlive their run: the dashboard fetches a run's chart
PNG only when a user opens that run, and an MCP agent that submitted with
run_async reads it back through get_instance with no deadline. So this is a
count bound, not a TTL.

- remove_instance/stop pop the result: both drop the instance record, and
  every read path resolves the instance first, so the entry was already
  unreachable memory rather than a cache.
- store_result evicts the oldest entries past _MAX_RESULTS (200), a backstop
  for instances kept alive indefinitely with a result per tick. Re-inserting
  refreshes recency so a continuous instance cannot age out under itself.
- _execute_and_record now stores the result only while the instance exists:
  a cancel landing after stop() would otherwise resurrect an unreachable and
  immortal entry.

store_result itself stays ungated — the Telegram executor calls it before it
registers the instance via _sync_instance_to_store, so a gate there would
drop every Telegram-triggered result on its first run.
---
 condor/routine_store.py                |  40 ++++-
 tests/test_routine_result_retention.py | 220 +++++++++++++++++++++++++
 2 files changed, 259 insertions(+), 1 deletion(-)
 create mode 100644 tests/test_routine_result_retention.py

diff --git a/condor/routine_store.py b/condor/routine_store.py
index 63f90513..fbeaf561 100644
--- a/condor/routine_store.py
+++ b/condor/routine_store.py
@@ -146,6 +146,18 @@ def user_data(self) -> dict:
         return self._user_data
 
 
+# How many finished-run results stay resident (CORR-142). Results must outlive
+# their run — the dashboard renders the detail panel after the run ends and only
+# fetches the chart PNG when the user opens that run, and an MCP agent that
+# submitted with `run_async` comes back for it via `get_instance` an unbounded
+# time later. So this is deliberately generous: it is a memory backstop, not a
+# cache TTL. What it prevents is the unbounded case — every `execute()` mints a
+# fresh instance_id, and a RoutineResult can hold a raw PNG in `chart_image`, so
+# an agent running a chart routine on a tick would otherwise pin megabytes a day
+# in a process designed to run for weeks.
+_MAX_RESULTS = 200
+
+
 class RoutineStore:
     """Singleton store for routine instances and results."""
 
@@ -271,11 +283,30 @@ def add_instance(self, instance_id: str, metadata: dict) -> None:
     def remove_instance(self, instance_id: str) -> None:
         self._instances.pop(instance_id, None)
         self._tasks.pop(instance_id, None)
+        # The result dies with its instance. Every read path resolves the
+        # instance first (the dashboard detail and chart endpoints via
+        # _authorized_instance, the MCP tool via get_instance), so a result left
+        # behind here is unreachable memory rather than a cache.
+        self._results.pop(instance_id, None)
 
     # ── Results ──
 
     def store_result(self, instance_id: str, result: RoutineResult) -> None:
+        """Record a run's result, keeping ``_results`` bounded to _MAX_RESULTS.
+
+        Popping before inserting refreshes recency (dicts keep insertion order),
+        so a continuous instance that stores a result every tick stays at the
+        young end and the entries evicted are the oldest untouched ones.
+
+        Not gated on the instance existing: the Telegram path calls this from
+        ``_execute_routine`` *before* it registers the instance via
+        ``_sync_instance_to_store``, so a gate here would drop every
+        Telegram-triggered result on its first run.
+        """
+        self._results.pop(instance_id, None)
         self._results[instance_id] = result
+        while len(self._results) > _MAX_RESULTS:
+            self._results.pop(next(iter(self._results)))
 
     def get_result(self, instance_id: str) -> RoutineResult | None:
         return self._results.get(instance_id)
@@ -457,12 +488,16 @@ async def _execute_and_record(
 
         duration = time.time() - start
         report_id = reports.get_last_report_id()
-        self._results[instance_id] = result
         # Clipped once: the instance record and the conversation note are the
         # same summary, so they cannot tell the user different stories.
         summary = result.text[:500]
 
+        # Both writes are gated on the instance still being there. A cancel that
+        # lands mid-run is recorded here *after* stop() already removed the
+        # instance, and storing the result then would resurrect an entry no read
+        # path can reach — unreachable and, without the gate, immortal.
         if instance_id in self._instances:
+            self.store_result(instance_id, result)
             self._instances[instance_id].update(
                 {
                     "status": (
@@ -708,6 +743,9 @@ def stop(self, instance_id: str) -> bool:
         if instance_id in self._instances:
             self._instances[instance_id]["status"] = "stopped"
             del self._instances[instance_id]
+            # Same reasoning as remove_instance: stop() drops the instance
+            # record entirely, so its result is already unreachable.
+            self._results.pop(instance_id, None)
             return True
         return False
 
diff --git a/tests/test_routine_result_retention.py b/tests/test_routine_result_retention.py
new file mode 100644
index 00000000..cd086fb4
--- /dev/null
+++ b/tests/test_routine_result_retention.py
@@ -0,0 +1,220 @@
+"""CORR-142: the store's result dict is bounded and never outlives its instance.
+
+``RoutineStore._results`` only ever grew: every ``execute()`` mints a fresh
+instance_id, and neither ``remove_instance`` nor ``stop`` dropped the matching
+result — so each one-shot run pinned a ``RoutineResult`` forever, ``chart_image``
+raw PNG bytes included, in a process designed to run for weeks.
+
+Results still have to *outlive their run*: the dashboard renders a run's detail
+after it finishes and fetches the chart PNG only when the user opens that run,
+and an MCP agent that submitted with ``run_async`` reads it back through
+``get_instance`` an unbounded time later. So the fix is a bound, not a TTL —
+a result is dropped when its instance goes away (every read path resolves the
+instance first, so it is unreachable by then anyway) and, as a backstop, the
+oldest entries are evicted once the dict passes ``_MAX_RESULTS``.
+"""
+
+import asyncio
+from types import SimpleNamespace
+
+import pytest
+from pydantic import BaseModel
+
+import condor.reports as rep
+from condor.routine_store import _MAX_RESULTS, RoutineStore
+from routines.base import RoutineResult
+
+
+@pytest.fixture
+def reports_dir(tmp_path, monkeypatch):
+    monkeypatch.setattr(rep, "CHARTS_DIR", tmp_path)
+    monkeypatch.setattr(rep, "INDEX_FILE", tmp_path / "reports_index.json")
+    return tmp_path
+
+
+def _routine(run_fn):
+    class Config(BaseModel):
+        pass
+
+    return SimpleNamespace(
+        name="probe", source="global", config_class=Config, run_fn=run_fn
+    )
+
+
+def _store() -> RoutineStore:
+    store = RoutineStore()
+    store._instances["i1"] = store._new_instance_meta(
+        "probe", {}, "srv", 0, source="web"
+    )
+    return store
+
+
+async def _returns_text(config, ctx):
+    return "run output"
+
+
+def _run(store: RoutineStore, routine) -> None:
+    asyncio.run(
+        store._execute_and_record(
+            "i1", routine, {}, "srv", status_after="completed", fire_hooks=False
+        )
+    )
+
+
+# ── The result dies with its instance ──
+
+
+def test_removing_an_instance_drops_its_result(reports_dir):
+    store = _store()
+    _run(store, _routine(_returns_text))
+    assert store.get_result("i1") is not None
+
+    store.remove_instance("i1")
+
+    assert store.get_result("i1") is None
+    assert "i1" not in store._results
+
+
+def test_stopping_an_instance_drops_its_result(reports_dir):
+    store = _store()
+    _run(store, _routine(_returns_text))
+
+    assert store.stop("i1") is True
+
+    assert store.get_result("i1") is None
+    assert "i1" not in store._results
+
+
+def test_no_orphan_results_after_execute_and_stop(reports_dir):
+    """set(_results) <= set(_instances) survives the store's own lifecycle."""
+    store = _store()
+    assert set(store._results) <= set(store._instances)
+
+    _run(store, _routine(_returns_text))
+    assert set(store._results) <= set(store._instances)
+
+    store.stop("i1")
+    assert set(store._results) <= set(store._instances)
+
+    store.remove_instance("i1")
+    assert set(store._results) <= set(store._instances)
+
+
+# ── The bound is enforced ──
+
+
+def test_results_never_exceed_the_cap():
+    store = RoutineStore()
+    for n in range(_MAX_RESULTS + 50):
+        store.store_result(f"run-{n}", RoutineResult(text=str(n)))
+
+    assert len(store._results) == _MAX_RESULTS
+
+
+def test_the_oldest_results_are_the_ones_evicted():
+    store = RoutineStore()
+    for n in range(_MAX_RESULTS + 50):
+        store.store_result(f"run-{n}", RoutineResult(text=str(n)))
+
+    # The first 50 are gone; everything after them is still resident.
+    assert store.get_result("run-0") is None
+    assert store.get_result("run-49") is None
+    assert store.get_result("run-50") is not None
+
+
+def test_a_recent_result_is_still_retrievable_after_eviction():
+    """The read-latency requirement: a finished run stays readable, chart included."""
+    store = RoutineStore()
+    store.store_result("charted", RoutineResult(text="with chart", chart_image=b"PNG"))
+    for n in range(_MAX_RESULTS - 1):
+        store.store_result(f"run-{n}", RoutineResult(text=str(n)))
+
+    result = store.get_result("charted")
+    assert result is not None
+    assert result.chart_image == b"PNG"
+
+
+def test_restoring_a_result_refreshes_its_recency():
+    """A continuous instance storing every tick must not age out under itself."""
+    store = RoutineStore()
+    store.store_result("ticker", RoutineResult(text="tick 1"))
+    for n in range(_MAX_RESULTS - 1):
+        store.store_result(f"run-{n}", RoutineResult(text=str(n)))
+
+    store.store_result("ticker", RoutineResult(text="tick 2"))
+    for n in range(_MAX_RESULTS - 1):
+        store.store_result(f"later-{n}", RoutineResult(text=str(n)))
+
+    assert len(store._results) == _MAX_RESULTS
+    assert store.get_result("ticker").text == "tick 2"
+
+
+# ── Eviction does not disturb a run in flight ──
+
+
+def test_eviction_does_not_disturb_a_run_in_flight(reports_dir):
+    store = _store()
+    started, released = asyncio.Event(), asyncio.Event()
+
+    async def slow(config, ctx):
+        started.set()
+        await released.wait()
+        return "in-flight output"
+
+    async def scenario():
+        task = asyncio.create_task(
+            store._execute_and_record(
+                "i1",
+                _routine(slow),
+                {},
+                "srv",
+                status_after="completed",
+                fire_hooks=False,
+            )
+        )
+        await started.wait()
+        # Flood the store past the cap while the run is suspended.
+        for n in range(_MAX_RESULTS + 10):
+            store.store_result(f"flood-{n}", RoutineResult(text=str(n)))
+        released.set()
+        await task
+
+    asyncio.run(scenario())
+
+    assert store.get_result("i1").text == "in-flight output"
+    assert store._instances["i1"]["last_result"] == "in-flight output"
+    assert store._instances["i1"]["status"] == "completed"
+    assert len(store._results) == _MAX_RESULTS
+
+
+def test_a_cancel_landing_after_stop_does_not_resurrect_the_result(reports_dir):
+    """_execute_and_record records the cancel *after* stop() removed the instance."""
+    store = _store()
+    started = asyncio.Event()
+
+    async def hangs(config, ctx):
+        started.set()
+        await asyncio.Event().wait()
+        return "never"
+
+    async def scenario():
+        task = asyncio.create_task(
+            store._execute_and_record(
+                "i1",
+                _routine(hangs),
+                {},
+                "srv",
+                status_after="completed",
+                fire_hooks=False,
+            )
+        )
+        store._tasks["i1"] = task
+        await started.wait()
+        assert store.stop("i1") is True
+        await asyncio.gather(task, return_exceptions=True)
+
+    asyncio.run(scenario())
+
+    assert "i1" not in store._instances
+    assert "i1" not in store._results
+    assert store.get_result("i1") is None

From e30346c587b7c507096626e7cd985f488e31c474 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Fri, 14 Aug 2026 15:07:33 +0300
Subject: [PATCH 065/116] (fix) delegate: bound the registry and the retained
 event stream
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

_delegations was append-only — the only write was start_delegation and
nothing ever popped it — and every retained DelegateTask kept the full,
untruncated event stream for the life of the process. An instance whose
agents delegate routinely accreted every transcript it ever produced.

Both bounds are counts, not TTLs. The MCP `delegate(action="get")` contract
is submit-now/collect-later with no deadline, so no grace window is the right
one to expire on; what makes a late collect safe is the disk fallback, not a
timer. /agents/delegations/{task_id} and its /events sibling both fall through
to delegation_history, which reads the .status.json record and the
.events.json sidecar — and both are written in _run's finally block, before
anything can be evicted. The registry-only readers (GET /agents/delegations
and the Telegram /delegations list) are per-process snapshots by contract and
have the merged /delegations/history route as their complete view.

- retire_delegation() runs last in the finally block, once the transcript,
  sidecar and status record are on disk: it re-inserts the entry at the young
  end (so the tail is finish order, not start order — a slow task started
  first must not be evicted first when it finally lands) and evicts the oldest
  terminal entries past MAX_FINISHED_DELEGATIONS (25). Terminal states only,
  so an in-flight delegation is never evicted at any count.
- MAX_EVENTS_PER_DELEGATION (500) bounds one task's stream, dropping the head
  and folding the count into a marker that reaches readers as a plain text
  note rather than a new wire type.
- Tool output/input are clipped at the existing MAX_TOOL_OUTPUT as the sink
  folds them. Both projections already cut the output there, so keeping the
  full string in RAM bought nothing; _clip_output is now idempotent so the
  readers' own clip is a no-op and nothing observable changed. An input is
  only degraded to its clipped string form when it overflows, since an
  Edit/Write call can carry a whole file in its arguments.
- A merged thought/text run rolls into a new event past MAX_CHUNK_CHARS
  (4000): one string growing for ever is a hole no event count can cap.

Closes CORR-143.
---
 condor/agents/delegate.py          | 178 ++++++++++++++++--
 tests/test_delegation_retention.py | 282 +++++++++++++++++++++++++++++
 2 files changed, 444 insertions(+), 16 deletions(-)
 create mode 100644 tests/test_delegation_retention.py

diff --git a/condor/agents/delegate.py b/condor/agents/delegate.py
index f4ee1f36..618e9024 100644
--- a/condor/agents/delegate.py
+++ b/condor/agents/delegate.py
@@ -20,6 +20,15 @@
 when the task starts, so a delegation killed by a restart is reported as
 ``interrupted`` instead of vanishing without a trace. It is never auto-restarted:
 delegations are one-shot and re-running could duplicate side effects.
+
+Ephemeral does not mean free: the registry is bounded on both axes since
+CORR-143. A finished delegation is retired once its transcript, events sidecar
+and status record are on disk, and only the most recent
+:data:`MAX_FINISHED_DELEGATIONS` of them stay resident -- older ones are served
+from :mod:`condor.agents.delegation_history` instead. Within one delegation the
+event stream is bounded too (:data:`MAX_EVENTS_PER_DELEGATION`, with tool
+payloads clipped to what a reader would have been shown anyway), so no single
+runaway session can pin an unbounded transcript.
 """
 
 from __future__ import annotations
@@ -39,10 +48,47 @@
 # Default per-task wall-clock budget; a hung ACP subprocess is cancelled after this.
 DEFAULT_TIMEOUT_S = 900
 
-# Ceiling on a single tool output wherever a transcript is *read* -- the on-disk
+# Ceiling on a single tool payload wherever a transcript is *read* -- the on-disk
 # markdown and the wire projection share it so the two can never disagree about
-# where a huge output was cut. ``dt.events`` itself keeps the full output.
+# where a huge output was cut. Since CORR-143 the event sink applies the same
+# ceiling as it folds, so what a delegation keeps in RAM is what every reader
+# would have shown anyway; :func:`_clip_output` is idempotent precisely so that
+# clipping once at write time and again at read time yields the same string.
 MAX_TOOL_OUTPUT = 2000
+TRUNCATION_MARKER = "\n… (truncated)"
+
+# How many events one delegation retains. The event stream is the heavy half of
+# a DelegateTask, so it is bounded per task and not only across tasks: past this
+# the sink drops the oldest events. Generous on purpose -- an ordinary
+# delegation never reaches it; what it stops is a runaway session pinning an
+# unbounded transcript in a process designed to run for weeks.
+MAX_EVENTS_PER_DELEGATION = 500
+
+# How much of one merged thought/text run stays in a single event. Consecutive
+# chunks are folded into the last entry, so without a roll-over a chatty agent
+# grows one string without bound -- which no count of events can cap. Past this
+# the sink opens a new entry, subject to the event bound like every other one.
+MAX_CHUNK_CHARS = 4000
+
+# The in-memory record of a cut: the sink drops the oldest events past the bound
+# and folds how many into this marker, so a transcript never silently claims to
+# be complete. It reaches readers as a plain text note (``events_for_wire``), so
+# no client has to learn a new event type.
+DROPPED_EVENT_TYPE = "dropped"
+
+# How many *terminal* delegations stay resident (CORR-143). Deliberately a count
+# bound and not a TTL: the MCP ``delegate`` contract is submit-now/collect-later
+# with no deadline, so there is no grace window that is the right one to expire
+# on. What makes a late collect safe is the disk fallback, not a timer --
+# ``GET /agents/delegations/{task_id}`` and its ``/events`` sibling both fall
+# through to :mod:`condor.agents.delegation_history`, which rebuilds the record
+# from the ``{task_id}.status.json`` and ``{task_id}.events.json`` files written
+# in ``_run``'s finally block, i.e. before an entry can ever be evicted. The two
+# registry-only readers (``GET /agents/delegations`` and the ``/delegations``
+# Telegram list) are per-process snapshots by contract and have the merged
+# ``/delegations/history`` route as their complete view. In-flight delegations
+# are never evicted, at any count.
+MAX_FINISHED_DELEGATIONS = 25
 
 # What happens to the conversation that asked for the work when the task ends.
 #
@@ -232,22 +278,35 @@ def _make_event_sink(dt: DelegateTask):
     tl = dt.events
     tc_map: dict[str, dict] = {}
 
+    def append(entry: dict) -> None:
+        tl.append(entry)
+        _bound_events(tl)
+
+    def merge_chunk(kind: str, text: str) -> None:
+        # Roll into a new entry once the current run is long enough: merging for
+        # ever would grow one string without bound, which no count of events can
+        # cap (CORR-143).
+        if tl and tl[-1]["type"] == kind and len(tl[-1]["text"]) < MAX_CHUNK_CHARS:
+            tl[-1]["text"] += text
+        else:
+            append({"type": kind, "text": text})
+
     def sink(event) -> None:
         if isinstance(event, ThoughtChunk):
-            if tl and tl[-1]["type"] == "thought":
-                tl[-1]["text"] += event.text
-            else:
-                tl.append({"type": "thought", "text": event.text})
+            merge_chunk("thought", event.text)
         elif isinstance(event, TextChunk):
-            if tl and tl[-1]["type"] == "text":
-                tl[-1]["text"] += event.text
-            else:
-                tl.append({"type": "text", "text": event.text})
+            merge_chunk("text", event.text)
         elif isinstance(event, (ToolCallEvent, ToolCallUpdate)):
             tc = fold_tool_call_event(tc_map, event)
             if tc is not None:
                 tc["type"] = "tool"
-                tl.append(tc)
+                append(tc)
+            # An output arrives on a *patch*, which the fold applies in place and
+            # reports as ``None`` -- so the payload bound is applied to the
+            # folded entry looked up here, not to the return value.
+            folded = tc_map.get(event.tool_call_id)
+            if folded is not None:
+                _bound_tool_payloads(folded)
 
     return sink
 
@@ -302,6 +361,10 @@ async def _run(dt: DelegateTask, bot, timeout_s: int) -> None:
             # already in the chat and in the transcript.
             if dt.on_complete == ON_COMPLETE_RESUME and dt.status == "done":
                 await _resume_conversation(dt)
+        # Last of all, and only once the transcript, the sidecar and the status
+        # record are on disk: this may drop older finished entries, and nothing
+        # may be evicted that a reader cannot still find in history.
+        retire_delegation(dt)
 
 
 async def stop_delegation(task_id: str) -> bool:
@@ -315,11 +378,88 @@ async def stop_delegation(task_id: str) -> bool:
 
 
 def _clip_output(value) -> str:
-    """Stringify a tool output, bounded at :data:`MAX_TOOL_OUTPUT`."""
+    """Stringify a tool payload, bounded at :data:`MAX_TOOL_OUTPUT`.
+
+    Idempotent: an already-clipped string comes back unchanged, so the sink can
+    apply the bound as the stream arrives (CORR-143) and the two readers can
+    keep applying it on the way out without stacking a second marker.
+    """
     out = str(value)
-    if len(out) > MAX_TOOL_OUTPUT:
-        return out[:MAX_TOOL_OUTPUT] + "\n… (truncated)"
-    return out
+    if out.endswith(TRUNCATION_MARKER) or len(out) <= MAX_TOOL_OUTPUT:
+        return out
+    return out[:MAX_TOOL_OUTPUT] + TRUNCATION_MARKER
+
+
+def _bound_tool_payloads(tc: dict) -> None:
+    """Clip a folded tool entry's payloads to what a reader would have shown.
+
+    The output is what gets big (a market-data dump, a file read), and both
+    projections already cut it at :data:`MAX_TOOL_OUTPUT` -- keeping the full
+    string in RAM bought nothing. The input is normally small and is left in its
+    original shape so the dashboard can render it as JSON; only one that
+    serializes past the same ceiling degrades to its clipped string form, since
+    an ``Edit``/``Write`` call can carry a whole file in its arguments.
+    """
+    import json
+
+    out = tc.get("output")
+    if out is not None:
+        tc["output"] = _clip_output(out)
+    inp = tc.get("input")
+    if inp is not None and not isinstance(inp, str):
+        serialized = json.dumps(inp, default=str)
+        if len(serialized) > MAX_TOOL_OUTPUT:
+            tc["input"] = _clip_output(serialized)
+
+
+def _bound_events(events: list[dict]) -> None:
+    """Keep an event stream under :data:`MAX_EVENTS_PER_DELEGATION`, oldest first.
+
+    The head is what gets dropped: a reader of a runaway session cares about how
+    it ended, and the tail is also what the completion notice is drawn from. The
+    count of dropped events is folded into a leading marker so the cut is
+    visible in the transcript rather than silent.
+    """
+    if len(events) <= MAX_EVENTS_PER_DELEGATION:
+        return
+    if not events or events[0].get("type") != DROPPED_EVENT_TYPE:
+        events.insert(0, {"type": DROPPED_EVENT_TYPE, "count": 0})
+    marker = events[0]
+    while len(events) > MAX_EVENTS_PER_DELEGATION:
+        events.pop(1)  # index 0 is the marker
+        marker["count"] += 1
+
+
+def _dropped_note(count: int) -> str:
+    return f"_… {count} earlier event(s) dropped to bound memory (CORR-143)_"
+
+
+def retire_delegation(dt: "DelegateTask") -> int:
+    """Move a finished delegation to the young end and evict the oldest ones.
+
+    Called once ``_run`` has persisted the transcript, the events sidecar and
+    the status record, so everything evicted here is already readable from disk.
+    Re-inserting refreshes recency (dicts keep insertion order), which makes the
+    registry's tail *finish* order rather than start order -- a slow delegation
+    started first must not be the first evicted when it finally lands.
+
+    Returns how many entries were evicted. Public so the same retirement can be
+    exercised directly rather than only through a live task.
+    """
+    if _delegations.get(dt.task_id) is dt:
+        # Never re-register a task that was already dropped: the pop/insert pair
+        # would resurrect it as the newest entry.
+        _delegations.pop(dt.task_id)
+        _delegations[dt.task_id] = dt
+
+    finished = [t for t, d in _delegations.items() if d.status in TERMINAL_STATES]
+    evicted = 0
+    for task_id in finished[: max(len(finished) - MAX_FINISHED_DELEGATIONS, 0)]:
+        _delegations.pop(task_id, None)
+        evicted += 1
+    if evicted:
+        log.debug("Evicted %s finished delegation(s) from the registry", evicted)
+    return evicted
 
 
 def events_for_wire(events: list[dict]) -> list[dict]:
@@ -338,6 +478,10 @@ def events_for_wire(events: list[dict]) -> list[dict]:
         kind = ev.get("type")
         if kind in ("thought", "text"):
             wire.append({"type": kind, "text": ev.get("text") or ""})
+        elif kind == DROPPED_EVENT_TYPE:
+            # Projected as a text note rather than a new wire type: every client
+            # already renders text, and a cut nobody renders is a silent lie.
+            wire.append({"type": "text", "text": _dropped_note(ev.get("count") or 0)})
         elif kind == "tool":
             inp = ev.get("input")
             out = ev.get("output")
@@ -367,7 +511,9 @@ def _render_session(events: list[dict]) -> str:
     tool_n = 0
     for ev in events:
         kind = ev.get("type")
-        if kind == "thought":
+        if kind == DROPPED_EVENT_TYPE:
+            parts.append(_dropped_note(ev.get("count") or 0))
+        elif kind == "thought":
             text = (ev.get("text") or "").strip()
             if text:
                 quoted = "\n".join(f"> {line}" for line in text.splitlines())
diff --git a/tests/test_delegation_retention.py b/tests/test_delegation_retention.py
new file mode 100644
index 00000000..ed80a29b
--- /dev/null
+++ b/tests/test_delegation_retention.py
@@ -0,0 +1,282 @@
+"""Unit tests for delegation retention -- the memory bounds (CORR-143).
+
+``_delegations`` used to be append-only and every entry kept the full,
+untruncated event stream for the life of the process. These tests pin both
+bounds and, just as importantly, what must NOT be lost to them: a recent
+delegation is still fully retrievable, an evicted one is still readable from
+disk, and an in-flight one is never evicted at any count.
+"""
+
+import asyncio
+
+import pytest
+
+from condor.agents import agent as agent_module
+from condor.agents import consult as consult_module
+from condor.agents import delegate as delegate_module
+from condor.agents.delegate import (
+    MAX_EVENTS_PER_DELEGATION,
+    MAX_FINISHED_DELEGATIONS,
+    MAX_TOOL_OUTPUT,
+    DelegateTask,
+    events_for_wire,
+    get_delegation,
+    retire_delegation,
+    start_delegation,
+)
+from condor.agents.delegation_history import read_history, read_history_events
+
+
+class _FakeBot:
+    async def send_message(self, *a, **kw):
+        pass
+
+
+def _write_agent(root, slug):
+    d = root / slug
+    d.mkdir(parents=True, exist_ok=True)
+    (d / "AGENT.md").write_text(
+        f"---\nname: {slug}\nwhen_to_consult: always\n---\n\nBody.\n"
+    )
+    return d
+
+
+@pytest.fixture(autouse=True)
+def _clean_registry():
+    delegate_module._delegations.clear()
+    yield
+    delegate_module._delegations.clear()
+
+
+def _run_delegation(monkeypatch, task="scan SOL pools", emit=None, result="done ok"):
+    """Drive one delegation to completion, optionally emitting events."""
+
+    async def fake_run(*, event_sink, **kw):
+        if emit is not None:
+            emit(event_sink)
+        return result
+
+    monkeypatch.setattr(consult_module, "_run_agent_to_completion", fake_run)
+
+    async def scenario():
+        dt = await start_delegation(
+            agent_slug="scout",
+            user_id=7,
+            chat_id=42,
+            server_name="local",
+            task=task,
+            bot=_FakeBot(),
+        )
+        await dt._task
+        return dt
+
+    return asyncio.run(scenario())
+
+
+# ── The registry bound ─────────────────────────────────────────────────────
+
+
+def test_finished_delegations_are_bounded_and_evicted_oldest_first(
+    tmp_path, monkeypatch
+):
+    monkeypatch.setattr(agent_module, "_DATA_ROOT", tmp_path)
+    _write_agent(tmp_path, "scout")
+
+    ids = [
+        _run_delegation(monkeypatch, task=f"task {i}").task_id
+        for i in range(MAX_FINISHED_DELEGATIONS + 5)
+    ]
+
+    assert len(delegate_module._delegations) == MAX_FINISHED_DELEGATIONS
+    # The five oldest are gone, the newest survive -- oldest-first eviction.
+    for task_id in ids[:5]:
+        assert get_delegation(task_id) is None
+    for task_id in ids[5:]:
+        assert get_delegation(task_id) is not None
+
+
+def test_an_evicted_delegation_is_still_readable_from_disk(tmp_path, monkeypatch):
+    monkeypatch.setattr(agent_module, "_DATA_ROOT", tmp_path)
+    _write_agent(tmp_path, "scout")
+
+    from condor.acp.client import ThoughtChunk
+
+    def emit(sink):
+        sink(ThoughtChunk(text="weighing the pools"))
+
+    first = _run_delegation(monkeypatch, task="the first one", emit=emit)
+    for i in range(MAX_FINISHED_DELEGATIONS + 1):
+        _run_delegation(monkeypatch, task=f"filler {i}")
+
+    # Evicted from memory...
+    assert get_delegation(first.task_id) is None
+    # ...but nothing was lost: the record and the transcript are on disk, which
+    # is what the /agents/delegations/{task_id} routes fall through to.
+    record = read_history(first.task_id)
+    assert record is not None
+    assert record["status"] == "done"
+    assert record["result"] == "done ok"
+    events, _markdown = read_history_events(first.task_id)
+    assert any(e["type"] == "thought" for e in events)
+
+
+def test_a_recent_delegation_is_still_fully_retrievable(tmp_path, monkeypatch):
+    """The collect-later contract: a poll right after completion hits memory."""
+    monkeypatch.setattr(agent_module, "_DATA_ROOT", tmp_path)
+    _write_agent(tmp_path, "scout")
+
+    from condor.acp.client import ToolCallEvent, ToolCallUpdate
+
+    def emit(sink):
+        sink(
+            ToolCallEvent(
+                tool_call_id="tc-1",
+                title="get_market_data",
+                status="in_progress",
+                input={"pair": "SOL-USDC"},
+            )
+        )
+        sink(ToolCallUpdate(tool_call_id="tc-1", status="completed", output="3 pools"))
+
+    dt = _run_delegation(monkeypatch, emit=emit, result="three pools worth watching")
+
+    live = get_delegation(dt.task_id)
+    assert live is dt
+    assert live.to_dict()["result"] == "three pools worth watching"
+    wire = events_for_wire(live.events)
+    assert [e["type"] for e in wire] == ["tool"]
+    assert wire[0]["output"] == "3 pools"
+    assert wire[0]["input"] == {"pair": "SOL-USDC"}
+
+
+def test_an_in_flight_delegation_is_never_evicted(tmp_path, monkeypatch):
+    monkeypatch.setattr(agent_module, "_DATA_ROOT", tmp_path)
+    _write_agent(tmp_path, "scout")
+
+    running = DelegateTask(
+        task_id="scout-delegate-inflight",
+        agent_slug="scout",
+        user_id=7,
+        chat_id=42,
+        server_name="local",
+        task="a long one",
+    )
+    delegate_module._delegations[running.task_id] = running
+
+    for i in range(MAX_FINISHED_DELEGATIONS * 2):
+        _run_delegation(monkeypatch, task=f"filler {i}")
+
+    assert running.status == "running"
+    assert get_delegation(running.task_id) is running
+    # The bound counts terminal entries only, so the live one rides above it.
+    assert len(delegate_module._delegations) == MAX_FINISHED_DELEGATIONS + 1
+
+
+def test_retiring_a_dropped_delegation_does_not_resurrect_it():
+    """A second retire of an already-evicted task must not re-register it."""
+    dt = DelegateTask(
+        task_id="scout-delegate-gone",
+        agent_slug="scout",
+        user_id=7,
+        chat_id=42,
+        server_name=None,
+        task="t",
+        status="done",
+    )
+    assert retire_delegation(dt) == 0
+    assert get_delegation(dt.task_id) is None
+
+
+# ── The per-entry event bound ──────────────────────────────────────────────
+
+
+def test_the_event_stream_of_one_delegation_is_bounded(tmp_path, monkeypatch):
+    monkeypatch.setattr(agent_module, "_DATA_ROOT", tmp_path)
+    _write_agent(tmp_path, "scout")
+
+    from condor.acp.client import ToolCallEvent
+
+    overflow = 50
+
+    def emit(sink):
+        for i in range(MAX_EVENTS_PER_DELEGATION + overflow):
+            sink(
+                ToolCallEvent(
+                    tool_call_id=f"tc-{i}",
+                    title=f"tool_{i}",
+                    status="completed",
+                    input={"i": i},
+                )
+            )
+
+    dt = _run_delegation(monkeypatch, emit=emit)
+
+    assert len(dt.events) == MAX_EVENTS_PER_DELEGATION
+    # The head is what gets dropped, and the cut is recorded rather than silent.
+    marker = dt.events[0]
+    assert marker["type"] == delegate_module.DROPPED_EVENT_TYPE
+    assert marker["count"] == overflow + 1  # +1: the marker took a slot too
+    assert dt.events[-1]["name"] == f"tool_{MAX_EVENTS_PER_DELEGATION + overflow - 1}"
+    # The marker reaches readers as a plain text note, not a new wire type.
+    wire = events_for_wire(dt.events)
+    assert wire[0]["type"] == "text"
+    assert str(marker["count"]) in wire[0]["text"]
+
+
+def test_a_huge_tool_output_is_clipped_in_memory_not_only_on_the_wire(
+    tmp_path, monkeypatch
+):
+    monkeypatch.setattr(agent_module, "_DATA_ROOT", tmp_path)
+    _write_agent(tmp_path, "scout")
+
+    from condor.acp.client import ToolCallEvent, ToolCallUpdate
+
+    huge = "x" * (MAX_TOOL_OUTPUT * 50)
+
+    def emit(sink):
+        sink(
+            ToolCallEvent(
+                tool_call_id="tc-1",
+                title="get_market_data",
+                status="in_progress",
+                input={"dump": huge},
+            )
+        )
+        sink(ToolCallUpdate(tool_call_id="tc-1", status="completed", output=huge))
+
+    dt = _run_delegation(monkeypatch, emit=emit)
+
+    entry = dt.events[-1]
+    assert len(entry["output"]) < MAX_TOOL_OUTPUT + 100
+    assert entry["output"].endswith(delegate_module.TRUNCATION_MARKER)
+    # A tool input can carry a whole file (an Edit/Write call), so it is bounded
+    # too -- degraded to its clipped string form only when it overflows.
+    assert len(entry["input"]) < MAX_TOOL_OUTPUT + 100
+    # Clipping twice must not stack a second marker: _clip_output is idempotent.
+    assert events_for_wire(dt.events)[-1]["output"] == entry["output"]
+
+
+def test_a_long_reasoning_run_rolls_into_new_events_instead_of_one_string(
+    tmp_path, monkeypatch
+):
+    monkeypatch.setattr(agent_module, "_DATA_ROOT", tmp_path)
+    _write_agent(tmp_path, "scout")
+
+    from condor.acp.client import ThoughtChunk
+
+    chunk = "y" * 500
+
+    def emit(sink):
+        for _ in range(40):  # 20k chars of one uninterrupted thought
+            sink(ThoughtChunk(text=chunk))
+
+    dt = _run_delegation(monkeypatch, emit=emit)
+
+    assert len(dt.events) > 1
+    assert all(e["type"] == "thought" for e in dt.events)
+    assert all(
+        len(e["text"]) <= delegate_module.MAX_CHUNK_CHARS + len(chunk)
+        for e in dt.events
+    )
+    # Nothing was lost by rolling: it is the same reasoning, in more entries.
+    assert "".join(e["text"] for e in dt.events) == chunk * 40

From b898f3cf475867ef001df6dd066defae44812bf1 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Fri, 14 Aug 2026 15:11:32 +0300
Subject: [PATCH 066/116] (perf) executor pre-fetch: transform each page once,
 not the whole list

The progressive pre-fetch broadcast the accumulated snapshot after every
page by re-running _transform_executors over the entire accumulated raw
list, so a row fetched on the first page went through ExecutorInfo.from_raw
once per remaining page. With FIRST_PAGE=50 / NEXT_PAGE=500 / MAX_PREFETCH=5000
a 5k history cost ~27k pydantic validations instead of 5k, all on the event
loop the candle and bots broadcasts share.

_transform_executors is a pure per-item map over a list (extract_executors_list
passes a list straight through), so accumulating page-wise transformed rows
yields the identical snapshot for O(rows) work. all_raw is kept only for the
raw-shape sds.put after the walk. The broadcast payload is copied because
broadcast() retains what it is handed as the channel's last-known data, which
the next page would otherwise mutate underneath it.

Closes PERF-135.
---
 condor/web/ws_manager.py                  |  24 ++-
 tests/test_ws_executor_prefetch_linear.py | 189 ++++++++++++++++++++++
 2 files changed, 207 insertions(+), 6 deletions(-)
 create mode 100644 tests/test_ws_executor_prefetch_linear.py

diff --git a/condor/web/ws_manager.py b/condor/web/ws_manager.py
index b12c1eba..69f2b11c 100644
--- a/condor/web/ws_manager.py
+++ b/condor/web/ws_manager.py
@@ -1469,6 +1469,15 @@ async def _executor_stream(self, channel: str) -> None:
                 sds = get_server_data_service()
                 client = await cm.get_client(server_name)
                 all_raw: list[dict] = []
+                # Rows already through ExecutorInfo, accumulated page by page.
+                # Transforming the *whole* accumulated list on every page made
+                # this quadratic: with FIRST_PAGE/NEXT_PAGE/MAX_PREFETCH below,
+                # a 5k history cost ~27k pydantic validations instead of 5k, all
+                # on the event loop the candle and bots broadcasts share.
+                # ``_transform_executors`` is a pure per-item map over a list
+                # (``extract_executors_list`` passes a list through untouched),
+                # so transforming each page once yields the identical snapshot.
+                transformed: list[dict] = []
                 page_num = 0
                 FIRST_PAGE = 50
                 NEXT_PAGE = 500
@@ -1483,16 +1492,19 @@ async def _executor_stream(self, channel: str) -> None:
                     max_items=MAX_PREFETCH,
                 ):
                     all_raw.extend(page)
-
-                    # Transform and broadcast accumulated results after each page
-                    executors = self._transform_executors(all_raw)
-                    if executors:
-                        await self.broadcast(channel, executors)
+                    transformed.extend(self._transform_executors(page))
+
+                    # Broadcast the accumulated snapshot after each page. It is
+                    # copied because ``broadcast`` retains what it is handed as
+                    # the channel's last-known payload, which the next page
+                    # would otherwise keep mutating underneath it.
+                    if transformed:
+                        await self.broadcast(channel, list(transformed))
                         logger.info(
                             "Executor pre-fetch page %d: %d executors (total %d) for %s",
                             page_num,
                             len(page),
-                            len(executors),
+                            len(transformed),
                             channel,
                         )
                     page_num += 1
diff --git a/tests/test_ws_executor_prefetch_linear.py b/tests/test_ws_executor_prefetch_linear.py
new file mode 100644
index 00000000..47cc9509
--- /dev/null
+++ b/tests/test_ws_executor_prefetch_linear.py
@@ -0,0 +1,189 @@
+"""PERF-135: the executor pre-fetch transforms each raw row exactly once.
+
+The progressive pre-fetch in ``ws_manager._executor_stream`` broadcasts the
+accumulated snapshot after every page. It used to build that snapshot by
+re-running ``_transform_executors`` over the *whole* accumulated raw list, so a
+row fetched on page 1 was pushed through ``ExecutorInfo.from_raw`` once per
+remaining page: O(pages x rows) pydantic validations instead of O(rows), on the
+event loop the candle and bots broadcasts share.
+
+These tests pin the complexity rather than the wording of the fix: they count
+``from_raw`` invocations across a multi-page walk and assert the count is the
+number of rows fetched, for two different page counts, so a re-introduced
+re-transform fails on the count and not on a snapshot comparison. The output is
+pinned separately: every broadcast must still be the full accumulated prefix.
+"""
+
+import asyncio
+
+import pytest
+
+import condor.server_data_service as sds_module
+import config_manager as cm_module
+from condor.web.models import ExecutorInfo
+from condor.web.ws_manager import WebSocketManager
+
+# Mirrored from the pre-fetch so the fake serves *full* pages: a short page ends
+# the walk, which is how each scenario below terminates on its last page.
+WS_FIRST_PAGE = 50
+WS_NEXT_PAGE = 500
+
+
+def _rows(start, count):
+    """``count`` distinct raw executor rows numbered from ``start``."""
+    return [
+        {
+            "id": f"e{i}",
+            "type": "position_executor",
+            "config": {"connector_name": "binance", "trading_pair": "BTC-USDT"},
+            "status": "TERMINATED",
+        }
+        for i in range(start, start + count)
+    ]
+
+
+class _PagingClient:
+    """Serves a fixed list of pages, advancing the cursor on each one."""
+
+    def __init__(self, pages):
+        self._pages = pages
+        self.calls = []
+        self.executors = self._Executors(self)
+
+    class _Executors:
+        def __init__(self, outer):
+            self._outer = outer
+
+        async def search_executors(self, **kwargs):
+            outer = self._outer
+            index = len(outer.calls)
+            outer.calls.append(kwargs)
+            page = outer._pages[index] if index < len(outer._pages) else []
+            cursor = f"c{index + 1}" if index + 1 < len(outer._pages) else None
+            return {"executors": page, "next_cursor": cursor}
+
+
+class _FakeSDS:
+    """Empty-but-present cache, so the stream reaches the pre-fetch under test.
+
+    ``get`` returning ``[]`` (not ``None``) skips the 3s wait for a concurrent
+    REST fill without ever populating ``_last_data``, which is what gates the
+    pre-fetch.
+    """
+
+    def __init__(self):
+        self.puts = []
+
+    def get(self, server_name, data_type):
+        return []
+
+    def put(self, server_name, data_type, value):
+        self.puts.append(value)
+
+
+def _run_prefetch(monkeypatch, pages):
+    """Drive one full pre-fetch over ``pages``; return what it did.
+
+    Returns ``(from_raw_calls, broadcasts, sds_puts)``.
+    """
+    client = _PagingClient(pages)
+    sds = _FakeSDS()
+
+    class _FakeCM:
+        async def get_client(self, server_name):
+            return client
+
+    monkeypatch.setattr(sds_module, "get_server_data_service", lambda: sds)
+    monkeypatch.setattr(cm_module, "get_config_manager", lambda: _FakeCM())
+
+    # Count every raw row pushed through the pydantic transform. This is the
+    # cost the item is about; the fix is only correct if it is O(total rows).
+    calls = {"n": 0}
+    real_from_raw = ExecutorInfo.from_raw.__func__
+
+    @classmethod
+    def _counting_from_raw(cls, ex):
+        calls["n"] += 1
+        return real_from_raw(cls, ex)
+
+    monkeypatch.setattr(ExecutorInfo, "from_raw", _counting_from_raw)
+
+    manager = WebSocketManager()
+    broadcasts = []
+
+    async def _record(channel, data):
+        broadcasts.append(data)
+
+    manager.broadcast = _record
+
+    async def _no_ws_stream(*args, **kwargs):
+        return None
+
+    # The pre-fetch is under test; the live socket that follows it is not.
+    manager._run_ws_stream = _no_ws_stream
+
+    asyncio.run(manager._executor_stream("executors:srv"))
+    return calls["n"], broadcasts, sds.puts
+
+
+def _pages_of(sizes):
+    """Consecutive pages of the given sizes, with globally unique row ids."""
+    pages = []
+    start = 0
+    for size in sizes:
+        pages.append(_rows(start, size))
+        start += size
+    return pages
+
+
+@pytest.mark.parametrize(
+    "sizes",
+    [
+        # Two pages: quadratic work would be 50 + 250 = 300 for 250 rows.
+        [WS_FIRST_PAGE, 200],
+        # Five pages: quadratic work would be 50 + 550 + 1050 + 1550 + 1750 =
+        # 4950 for 1750 rows -- the gap grows with the page count, which is
+        # exactly what makes the count a complexity assertion and not a
+        # constant-factor one.
+        [WS_FIRST_PAGE, WS_NEXT_PAGE, WS_NEXT_PAGE, WS_NEXT_PAGE, 200],
+    ],
+)
+def test_prefetch_transforms_each_row_exactly_once(monkeypatch, sizes):
+    """``from_raw`` runs once per fetched row, whatever the page count."""
+    pages = _pages_of(sizes)
+    total_rows = sum(sizes)
+
+    from_raw_calls, broadcasts, _ = _run_prefetch(monkeypatch, pages)
+
+    assert len(broadcasts) == len(pages), "one broadcast per page"
+    assert from_raw_calls == total_rows, (
+        "the accumulated list was re-transformed: "
+        f"{from_raw_calls} validations for {total_rows} rows"
+    )
+
+
+def test_prefetch_broadcasts_the_full_accumulated_snapshot(monkeypatch):
+    """Each page still broadcasts every row seen so far, in order."""
+    sizes = [WS_FIRST_PAGE, WS_NEXT_PAGE, 200]
+    pages = _pages_of(sizes)
+    all_raw = [row for page in pages for row in page]
+
+    _, broadcasts, puts = _run_prefetch(monkeypatch, pages)
+
+    expected_full = WebSocketManager._transform_executors(all_raw)
+    assert (
+        broadcasts[-1] == expected_full
+    ), "final snapshot differs from a whole-list transform"
+
+    # Every intermediate broadcast is the prefix of that same list.
+    seen = 0
+    for page, payload in zip(pages, broadcasts):
+        seen += len(page)
+        assert payload == expected_full[:seen]
+
+    # And the snapshots are independent: a later page must not mutate an
+    # already-broadcast payload (``broadcast`` retains what it is handed).
+    assert len(broadcasts[0]) == WS_FIRST_PAGE
+
+    assert len(puts) == 1, "the pre-fetch did not reach its sds.put"
+    assert puts[0] == all_raw, "SDS must still receive the complete raw list"

From d0ecf7a178ad8de12a4a2aa6cf8a63d76792cc72 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Fri, 14 Aug 2026 15:15:51 +0300
Subject: [PATCH 067/116] (perf) coalesce concurrent REST candle fetches
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The /market/candles TTL cache only helps requests that arrive after one
has finished. A dashboard rendering a grid of executor panels for the
same pair and window misses a cold cache in all of them at once, and
each miss fired its own upstream call — N duplicate GeckoTerminal
requests against the process-wide rate budget, or N duplicate
historical-candle calls to the API server.

Add per-key in-flight coalescing next to _candle_cache, keyed exactly
like it, using the same idiom as _snapshot_inflight in
condor/fetchers/bot_performance.py: one task per key, reused only from
the loop that created it, popped by a done-callback so a failure is
retried rather than remembered. The upstream fetch (both the
GeckoTerminal and the post-ARCH-146 fetch_historical_candles legs) moves
into _fetch_candles_upstream so waiters can share one execution; the
await is shielded so a disconnecting browser cannot cancel the shared
fetch out from under the other waiters. TTL and size behaviour unchanged.
---
 condor/web/routes/market.py     | 137 +++++++++++++++++-------
 tests/test_candle_coalescing.py | 180 ++++++++++++++++++++++++++++++++
 2 files changed, 280 insertions(+), 37 deletions(-)
 create mode 100644 tests/test_candle_coalescing.py

diff --git a/condor/web/routes/market.py b/condor/web/routes/market.py
index 34137bba..44c8ef56 100644
--- a/condor/web/routes/market.py
+++ b/condor/web/routes/market.py
@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import asyncio
 import logging
 import time
 
@@ -29,6 +30,17 @@ def _candle_cache_put(key: tuple, value: list, now: float) -> None:
         _candle_cache.pop(next(iter(_candle_cache)))
 
 
+# In-flight coalescing, keyed exactly like _candle_cache. The TTL cache only
+# helps requests that arrive *after* one has finished; a dashboard rendering a
+# grid of executor panels for the same pair and window misses a cold cache in
+# all of them at once, and each miss used to fire its own upstream call — N
+# duplicate GeckoTerminal requests against the process-wide rate budget, or N
+# duplicate historical-candle calls to the API server. Same idiom as
+# `_snapshot_inflight` in condor/fetchers/bot_performance.py: one task per key,
+# popped by a done-callback so a failure is retried rather than remembered.
+_candle_inflight: dict[tuple, tuple[asyncio.AbstractEventLoop, asyncio.Task]] = {}
+
+
 from condor.fetchers.market_data import fetch_historical_candles
 from condor.web.auth import get_current_user
 from condor.web.models import (
@@ -419,6 +431,63 @@ async def get_order_book(
     )
 
 
+async def _fetch_candles_upstream(
+    cm,
+    name: str,
+    connector: str,
+    trading_pair: str,
+    interval: str,
+    limit: int,
+    start_time: float | None,
+    end_time: float | None,
+    pool_address: str | None,
+) -> list[CandleData]:
+    """Fetch one window of candles upstream, with no caching of its own.
+
+    Split out of the route so concurrent requests on the same cache key can
+    share a single execution of it (see `_candle_inflight`). Raises exactly what
+    the route used to raise inline, so every waiter on a failing fetch sees the
+    same error and nothing is cached.
+    """
+    # Pairs with no CandlesFactory feed never reach the client below — that path
+    # 502s for them. A GeckoTerminal-backed connector (a DEX network, or an
+    # on-chain venue like xrpl) or an explicit pool_address routes there instead.
+    if pool_address or dex_candles.uses_gecko_candles(connector):
+        return await _fetch_dex_candles(
+            connector, pool_address, trading_pair, interval, start_time, end_time
+        )
+
+    client = await cm.get_client(name)
+    try:
+        rows = await fetch_historical_candles(
+            client,
+            connector,
+            trading_pair,
+            interval,
+            # No start_time means no time range to ask for: go straight to the
+            # plain `limit`-sized window.
+            start_time=int(start_time) if start_time is not None else None,
+            end_time=int(end_time) if end_time else int(time.time()),
+            limit=limit,
+            fallback_on_error=True,
+            strict=True,
+        )
+    except (TypeError, ValueError):
+        # A malformed row (strict=True) is a bug in the payload, not an upstream
+        # outage — surface it as-is, as this route always has.
+        raise
+    except Exception as e:
+        logger.exception(
+            "Failed to fetch candles for %s on %s of '%s'",
+            trading_pair,
+            connector,
+            name,
+        )
+        raise upstream_error("Failed to fetch candles", e)
+
+    return [CandleData(**row) for row in rows]
+
+
 @router.get("/servers/{name}/market/candles", response_model=list[CandleData])
 async def get_candles(
     name: str,
@@ -461,45 +530,39 @@ async def get_candles(
     if cached and (now - cached[0]) < _CANDLE_CACHE_TTL:
         return cached[1]
 
-    # Pairs with no CandlesFactory feed never reach the client below — that path
-    # 502s for them. A GeckoTerminal-backed connector (a DEX network, or an
-    # on-chain venue like xrpl) or an explicit pool_address routes there instead.
-    if pool_address or dex_candles.uses_gecko_candles(connector):
-        candles = await _fetch_dex_candles(
-            connector, pool_address, trading_pair, interval, start_time, end_time
-        )
-        _candle_cache_put(cache_key, candles, now)
-        return candles
-
-    client = await cm.get_client(name)
-    try:
-        rows = await fetch_historical_candles(
-            client,
-            connector,
-            trading_pair,
-            interval,
-            # No start_time means no time range to ask for: go straight to the
-            # plain `limit`-sized window.
-            start_time=int(start_time) if start_time is not None else None,
-            end_time=int(end_time) if end_time else int(time.time()),
-            limit=limit,
-            fallback_on_error=True,
-            strict=True,
-        )
-    except (TypeError, ValueError):
-        # A malformed row (strict=True) is a bug in the payload, not an upstream
-        # outage — surface it as-is, as this route always has.
-        raise
-    except Exception as e:
-        logger.exception(
-            "Failed to fetch candles for %s on %s of '%s'",
-            trading_pair,
-            connector,
-            name,
+    # Cache miss: share one upstream fetch with every concurrent request on this
+    # key. Reuse an in-flight task only from the loop that created it — a task is
+    # bound to its loop and awaiting it from another one raises.
+    loop = asyncio.get_running_loop()
+    inflight = _candle_inflight.get(cache_key)
+    task = (
+        inflight[1]
+        if inflight is not None and inflight[0] is loop and not inflight[1].done()
+        # A finished task lingers until its done-callback runs; joining it would
+        # hand a fresh request the previous fetch's outcome (a failure included).
+        else None
+    )
+    if task is None:
+        task = asyncio.ensure_future(
+            _fetch_candles_upstream(
+                cm,
+                name,
+                connector,
+                trading_pair,
+                interval,
+                limit,
+                start_time,
+                end_time,
+                pool_address,
+            )
         )
-        raise upstream_error("Failed to fetch candles", e)
+        _candle_inflight[cache_key] = (loop, task)
+        task.add_done_callback(lambda _t, k=cache_key: _candle_inflight.pop(k, None))
 
-    candles = [CandleData(**row) for row in rows]
+    # Shielded: a browser that disconnects mid-request cancels this handler, and
+    # an unshielded `await task` would cancel the shared fetch out from under
+    # every other waiter on the same key.
+    candles = await asyncio.shield(task)
     _candle_cache_put(cache_key, candles, now)
     return candles
 
diff --git a/tests/test_candle_coalescing.py b/tests/test_candle_coalescing.py
new file mode 100644
index 00000000..a642afc6
--- /dev/null
+++ b/tests/test_candle_coalescing.py
@@ -0,0 +1,180 @@
+"""In-flight coalescing for GET /market/candles (PERF-137).
+
+Concurrent identical chart requests (a grid of executor panels on the same pair
+and window) must share ONE upstream fetch instead of firing N.
+"""
+
+import asyncio
+
+import pytest
+
+import condor.web.routes.market as market
+from condor.web.models import WebUser
+
+
+@pytest.fixture(autouse=True)
+def _clean_state():
+    market._candle_cache.clear()
+    market._candle_inflight.clear()
+    yield
+    market._candle_cache.clear()
+    market._candle_inflight.clear()
+
+
+class _Cm:
+    """Config manager double: grants access and hands back a fake client."""
+
+    def __init__(self, client):
+        self._client = client
+
+    def has_server_access(self, user_id, name):
+        return True
+
+    async def get_client(self, name):
+        return self._client
+
+
+class _CountingClient:
+    """Counts historical-candle calls and holds them open until released."""
+
+    def __init__(self, gate=None, fail=False):
+        self.calls = 0
+        self._gate = gate
+        self._fail = fail
+
+    @property
+    def market_data(self):
+        return self
+
+    async def get_historical_candles(self, *a, **kw):
+        self.calls += 1
+        if self._gate is not None:
+            await self._gate
+        if self._fail:
+            raise RuntimeError("upstream down")
+        return [
+            {
+                "timestamp": 1000.0,
+                "open": 1.0,
+                "high": 2.0,
+                "low": 0.5,
+                "close": 1.5,
+                "volume": 10.0,
+            }
+        ]
+
+    async def get_candles(self, *a, **kw):
+        # The fallback leg of the ladder. `fetch_historical_candles` is called
+        # with fallback_on_error=True, so a fetch only fails outright when this
+        # leg fails too.
+        if self._fail:
+            raise RuntimeError("upstream down")
+        return []
+
+
+def _install(monkeypatch, client):
+    monkeypatch.setattr(
+        "condor.web.routes.market.get_config_manager", lambda: _Cm(client), raising=True
+    )
+
+
+def _call(**overrides):
+    params = dict(
+        connector="binance",
+        trading_pair="BTC-USDT",
+        interval="1m",
+        limit=100,
+        start_time=1_700_000_000.0,
+        end_time=1_700_003_600.0,
+        pool_address=None,
+        user=WebUser(id=1, role="user"),
+    )
+    params.update(overrides)
+    return market.get_candles("srv", **params)
+
+
+def test_concurrent_identical_requests_share_one_upstream_fetch(monkeypatch):
+    async def scenario():
+        gate = asyncio.get_running_loop().create_future()
+        client = _CountingClient(gate=gate)
+        _install(monkeypatch, client)
+
+        tasks = [asyncio.ensure_future(_call()) for _ in range(5)]
+        # Let every request reach the (gated) upstream call before releasing it.
+        await asyncio.sleep(0)
+        await asyncio.sleep(0)
+        gate.set_result(None)
+        results = await asyncio.gather(*tasks)
+        return client.calls, results
+
+    calls, results = asyncio.run(scenario())
+    assert calls == 1
+    assert all(r == results[0] for r in results)
+    assert len(results[0]) == 1
+
+
+def test_requests_with_different_keys_are_not_coalesced(monkeypatch):
+    async def scenario():
+        gate = asyncio.get_running_loop().create_future()
+        client = _CountingClient(gate=gate)
+        _install(monkeypatch, client)
+
+        tasks = [
+            asyncio.ensure_future(_call()),
+            asyncio.ensure_future(_call(trading_pair="ETH-USDT")),
+            asyncio.ensure_future(_call(interval="5m")),
+        ]
+        await asyncio.sleep(0)
+        await asyncio.sleep(0)
+        gate.set_result(None)
+        await asyncio.gather(*tasks)
+        return client.calls
+
+    assert asyncio.run(scenario()) == 3
+
+
+def test_failing_fetch_reaches_every_waiter_and_is_not_cached(monkeypatch):
+    async def scenario():
+        gate = asyncio.get_running_loop().create_future()
+        failing = _CountingClient(gate=gate, fail=True)
+        _install(monkeypatch, failing)
+
+        tasks = [asyncio.ensure_future(_call()) for _ in range(3)]
+        await asyncio.sleep(0)
+        await asyncio.sleep(0)
+        gate.set_result(None)
+        errors = await asyncio.gather(*tasks, return_exceptions=True)
+
+        # Nothing cached, nothing left in flight: the next request retries.
+        cached = dict(market._candle_cache)
+        inflight = dict(market._candle_inflight)
+
+        healthy = _CountingClient()
+        _install(monkeypatch, healthy)
+        retried = await _call()
+        return errors, cached, inflight, failing.calls, healthy.calls, retried
+
+    errors, cached, inflight, fail_calls, ok_calls, retried = asyncio.run(scenario())
+    assert fail_calls == 1
+    assert len(errors) == 3
+    assert all(isinstance(e, Exception) for e in errors)
+    assert cached == {}
+    assert inflight == {}
+    # The retry actually hit upstream and succeeded.
+    assert ok_calls == 1
+    assert len(retried) == 1
+
+
+def test_cache_still_answers_after_the_shared_fetch_completes(monkeypatch):
+    """Coalescing does not replace the TTL cache — the second wave is a hit."""
+
+    async def scenario():
+        client = _CountingClient()
+        _install(monkeypatch, client)
+        first = await _call()
+        second = await _call()
+        return client.calls, first, second
+
+    calls, first, second = asyncio.run(scenario())
+    assert calls == 1
+    assert first is second

From 873659413f4e07faf5b2e439a9fdc0fa05242d12 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Fri, 14 Aug 2026 15:18:37 +0300
Subject: [PATCH 068/116] (refactor) journal: drop dead JournalManager API
 surface

- __init__: remove strategy_name/strategy_description, which were never
  assigned nor read; the engine passed real values and got nothing.
- get_pnl_series: remove the `hours` parameter, which the body ignored.
  The only caller renders a whole-session equity curve, so honouring a
  24h window would have silently truncated it.
- delete _parse_ticks, get_data_dir and size_bytes: zero callers repo-wide.
---
 condor/agents/engine.py  |  2 --
 condor/agents/journal.py | 38 +-------------------------------------
 2 files changed, 1 insertion(+), 39 deletions(-)

diff --git a/condor/agents/engine.py b/condor/agents/engine.py
index 5d586b6a..f5d443b5 100644
--- a/condor/agents/engine.py
+++ b/condor/agents/engine.py
@@ -172,8 +172,6 @@ def __post_init__(self):
 
             self.journal = JournalManager(
                 self.agent_id,
-                strategy_name=self.strategy.name,
-                strategy_description=self.strategy.description,
                 session_dir=self.session_dir,
                 agent_dir=strategy_dir,
             )
diff --git a/condor/agents/journal.py b/condor/agents/journal.py
index ce06e701..cff6a4b6 100644
--- a/condor/agents/journal.py
+++ b/condor/agents/journal.py
@@ -309,8 +309,6 @@ class JournalManager:
     def __init__(
         self,
         agent_id: str,
-        strategy_name: str = "",
-        strategy_description: str = "",
         session_dir: Path | None = None,
         agent_dir: Path | None = None,
     ):
@@ -890,32 +888,6 @@ def _parse_executors(self) -> list[dict]:
         self._parsed_cache["executors"] = results
         return results
 
-    def _parse_ticks(self) -> list[dict]:
-        self.read_full()  # refresh parsed cache if the file changed
-        cached = self._parsed_cache.get("ticks")
-        if cached is not None:
-            return cached
-        section = self._get_section("Ticks")
-        results = []
-        for line in section.splitlines():
-            if not line.startswith(TICK_LINE_PREFIX):
-                continue
-            entry: dict[str, Any] = {}
-            parts = line[2:].split(" | ")
-            for part in parts:
-                if part.startswith("tick#"):
-                    entry["tick"] = int(part.replace("tick#", ""))
-                elif part.startswith("actions="):
-                    entry["actions"] = int(part.replace("actions=", ""))
-                else:
-                    if re.match(r"\d{4}-\d{2}-\d{2}", part.strip()):
-                        entry["timestamp"] = part.strip()
-                    else:
-                        entry["summary"] = part.strip()
-            results.append(entry)
-        self._parsed_cache["ticks"] = results
-        return results
-
     def _parse_snapshots(self) -> list[dict]:
         self.read_full()  # refresh parsed cache if the file changed
         cached = self._parsed_cache.get("snapshots")
@@ -986,7 +958,7 @@ def get_drawdown_pct(self) -> float:
             return 0.0
         return drawdown / exposure * 100
 
-    def get_pnl_series(self, hours: int = 24) -> list[dict]:
+    def get_pnl_series(self) -> list[dict]:
         return [
             {"timestamp": s.get("timestamp", ""), "pnl": s.get("pnl", 0)}
             for s in self._parse_snapshots()
@@ -1064,14 +1036,6 @@ def entry_count(self) -> int:
         section = self._get_section("Recent Actions")
         return len([l for l in section.splitlines() if l.startswith("- ")])
 
-    def get_data_dir(self) -> Path:
-        """Return the session data directory."""
-        return self._session_dir
-
-    def size_bytes(self) -> int:
-        """Current file size."""
-        return self._path.stat().st_size if self._path.exists() else 0
-
 
 def _normalize(text: str) -> str:
     """Lowercase, strip punctuation, collapse whitespace."""

From 90f06acc15ebd31c4333246695f92fbe274cb561 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Fri, 14 Aug 2026 15:22:10 +0300
Subject: [PATCH 069/116] (fix) SEC-153: credential add/delete requires server
 owner
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

POST /settings/credentials and DELETE /settings/credentials/{connector}
gated only on has_server_access, whose default is TRADER. A user the owner
shared a server with for trading could delete the owner's exchange keys off
the backend master_account — killing the owner's running bots' connectivity —
or overwrite them by re-adding the same connector with their own keys,
routing the owner's strategies through an account the owner does not control.

Credential management is destructive server configuration, the same class as
update_server/delete_server, which already call _require_owner. Draw the same
line here (admins keep the bypass that helper grants everywhere else).
Read-only list_credentials returns connector names only and stays at TRADER.
---
 condor/web/routes/settings.py            |   5 +
 tests/test_web_credentials_owner_only.py | 166 +++++++++++++++++++++++
 2 files changed, 171 insertions(+)
 create mode 100644 tests/test_web_credentials_owner_only.py

diff --git a/condor/web/routes/settings.py b/condor/web/routes/settings.py
index 7edada08..35454bd5 100644
--- a/condor/web/routes/settings.py
+++ b/condor/web/routes/settings.py
@@ -654,6 +654,9 @@ async def add_credential(
     cm = get_config_manager()
     if not cm.has_server_access(user.id, server):
         raise HTTPException(status_code=403, detail="No access")
+    # Credentials are server configuration, not trading: a shared trader must not
+    # overwrite the owner's exchange keys. Same line update_server/delete_server draw.
+    _require_owner(cm, user.id, server)
     client = await _get_client(cm, server)
     try:
         result = await client.accounts.add_credential(
@@ -682,6 +685,8 @@ async def delete_credential(
     cm = get_config_manager()
     if not cm.has_server_access(user.id, server):
         raise HTTPException(status_code=403, detail="No access")
+    # Deleting a key kills the owner's running bots' connectivity — owner only.
+    _require_owner(cm, user.id, server)
     client = await _get_client(cm, server)
     try:
         result = await client.accounts.delete_credential(
diff --git a/tests/test_web_credentials_owner_only.py b/tests/test_web_credentials_owner_only.py
new file mode 100644
index 00000000..ecd0c36a
--- /dev/null
+++ b/tests/test_web_credentials_owner_only.py
@@ -0,0 +1,166 @@
+"""Exchange credential add/delete is owner-only (SEC-153).
+
+`has_server_access` defaults to TRADER, so a user the owner shared a server with
+for trading could delete the owner's exchange API keys off the backend — killing
+the owner's running bots — or overwrite them by re-adding the same connector with
+their own keys. Credential management is server configuration, like
+update_server/delete_server, and must draw the same `_require_owner` line.
+
+These tests pin all three principals: owner passes, non-owner trader is refused,
+admin keeps the bypass `_require_owner` already grants everywhere else.
+"""
+
+import pytest
+from fastapi import FastAPI
+from starlette.testclient import TestClient
+
+import condor.web.routes.settings as settings_routes
+from condor.server_data_service import ServerDataType
+from condor.web.auth import get_current_user
+from condor.web.models import WebUser
+from config_manager import ServerPermission
+
+SERVER = "alpha"
+OWNER = WebUser(id=1, username="owner", first_name="O", role="user")
+TRADER = WebUser(id=2, username="trader", first_name="T", role="user")
+ADMIN = WebUser(id=3, username="admin", first_name="A", role="admin")
+
+
+class FakeAccounts:
+    def __init__(self):
+        self.added = []
+        self.deleted = []
+
+    async def add_credential(self, account_name, connector_name, credentials):
+        self.added.append((account_name, connector_name, credentials))
+        return {"ok": True}
+
+    async def delete_credential(self, account_name, connector_name):
+        self.deleted.append((account_name, connector_name))
+        return {"ok": True}
+
+
+class FakeClient:
+    def __init__(self):
+        self.accounts = FakeAccounts()
+
+
+class FakeConfigManager:
+    """Owner id 1, trader id 2 shared, admin id 3 with no grant on the server."""
+
+    def __init__(self, client):
+        self._client = client
+
+    def get_server_permission(self, user_id, server_name):
+        if server_name != SERVER:
+            return None
+        if user_id == OWNER.id:
+            return ServerPermission.OWNER
+        if user_id == TRADER.id:
+            return ServerPermission.TRADER
+        return None
+
+    def has_server_access(self, user_id, server_name, min_permission=None):
+        # Admins reach every server, mirroring the real manager.
+        if self.is_admin(user_id):
+            return server_name == SERVER
+        return self.get_server_permission(user_id, server_name) is not None
+
+    def is_admin(self, user_id):
+        return user_id == ADMIN.id
+
+    async def get_client(self, server_name):
+        return self._client
+
+
+class FakeSDS:
+    def __init__(self):
+        self.invalidated = []
+
+    def invalidate(self, server, data_type):
+        self.invalidated.append((server, data_type))
+
+
+@pytest.fixture
+def env(monkeypatch):
+    client = FakeClient()
+    cm = FakeConfigManager(client)
+    sds = FakeSDS()
+    monkeypatch.setattr(settings_routes, "get_config_manager", lambda: cm)
+    monkeypatch.setattr(
+        "condor.server_data_service.get_server_data_service", lambda: sds
+    )
+    app = FastAPI()
+    app.include_router(settings_routes.router)
+    return app, client, sds
+
+
+def as_user(app, user):
+    app.dependency_overrides[get_current_user] = lambda: user
+    return TestClient(app)
+
+
+def post_credential(http):
+    return http.post(
+        "/settings/credentials",
+        params={"server": SERVER},
+        json={"connector_name": "binance", "credentials": {"api_key": "k"}},
+    )
+
+
+def delete_credential(http):
+    return http.delete("/settings/credentials/binance", params={"server": SERVER})
+
+
+def test_owner_can_add_and_delete_credentials(env):
+    app, client, sds = env
+
+    assert post_credential(as_user(app, OWNER)).status_code == 200
+    assert client.accounts.added == [("master_account", "binance", {"api_key": "k"})]
+
+    assert delete_credential(as_user(app, OWNER)).status_code == 200
+    assert client.accounts.deleted == [("master_account", "binance")]
+    assert (SERVER, ServerDataType.PORTFOLIO) in sds.invalidated
+
+
+def test_shared_trader_cannot_add_or_delete_credentials(env):
+    app, client, _ = env
+    http = as_user(app, TRADER)
+
+    add = post_credential(http)
+    assert add.status_code == 403
+    assert add.json()["detail"] == "Owner access required"
+
+    delete = delete_credential(http)
+    assert delete.status_code == 403
+    assert delete.json()["detail"] == "Owner access required"
+
+    # The backend was never touched on either attempt.
+    assert client.accounts.added == []
+    assert client.accounts.deleted == []
+
+
+def test_admin_keeps_the_owner_bypass(env):
+    """`_require_owner` lets admins through everywhere else in this file."""
+    app, client, _ = env
+    http = as_user(app, ADMIN)
+
+    assert post_credential(http).status_code == 200
+    assert delete_credential(http).status_code == 200
+    assert client.accounts.added and client.accounts.deleted
+
+
+def test_trader_can_still_list_credentials(env):
+    """Listing returns connector names only and stays at TRADER level."""
+    app, client, _ = env
+
+    async def list_account_credentials(account_name):
+        return ["binance"]
+
+    client.accounts.list_account_credentials = list_account_credentials
+
+    resp = as_user(app, TRADER).get("/settings/credentials", params={"server": SERVER})
+    assert resp.status_code == 200
+    assert resp.json()["credentials"] == [
+        {"connector_name": "binance", "connector_type": ""}
+    ]

From 445312d64a19b1bd82fe585c125ffcc51853306b Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Fri, 14 Aug 2026 15:29:24 +0300
Subject: [PATCH 070/116] (refactor) move the portfolio-history poll into
 ServerDataService
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The REST route module held module-level polling state (_history_cache,
_refresh_tasks, _last_request_time) and hand-rolled the whole lifecycle:
warm + prime, a 120s refresh loop with a 10-min idle timeout, per-range
TTLs, and an unsubscribe entry point. ws_manager drove it by importing
warm_portfolio_history and stop_history_refresh out of the route file,
coupling the WS layer to a REST module.

All of that already exists in ServerDataService — subscription-scoped
polling, per-server rate limiting, health/backoff — plus the single-flight
coalescing the hand-rolled TTL cache lacked, where two concurrent reads of
an expired (server, range) pair both hit the backend.

PORTFOLIO_HISTORY becomes a data type keyed by range_key, fed by
fetch_portfolio_history in condor.fetchers.portfolio. ws_manager subscribes
the four ranges alongside the PORTFOLIO subscription and drops them on the
last-subscriber-leaves path, so it no longer imports the route module. The
endpoint reads through get_or_fetch and returns the same shape.

DataTypeDefaults grows an optional ttl_by_param so the four per-range TTLs
survive the move — SDS TTLs were per-data-type, and a 1D window going stale
in minutes cannot share a TTL with a 3M one.

The idle timeout is gone by design: the poll is now scoped to its
subscribers, which is what the WS lifecycle already meant to express.
---
 condor/fetchers/__init__.py         |   3 +-
 condor/fetchers/portfolio.py        |  26 +-
 condor/server_data_service.py       |  33 ++-
 condor/web/routes/portfolio.py      | 145 +----------
 condor/web/ws_manager.py            |  82 +++++-
 tests/test_portfolio_history_sds.py | 377 ++++++++++++++++++++++++++++
 6 files changed, 518 insertions(+), 148 deletions(-)
 create mode 100644 tests/test_portfolio_history_sds.py

diff --git a/condor/fetchers/__init__.py b/condor/fetchers/__init__.py
index ad80054a..e305cf52 100644
--- a/condor/fetchers/__init__.py
+++ b/condor/fetchers/__init__.py
@@ -63,13 +63,14 @@
     fetch_tickers,
 )
 from condor.fetchers.orders import fetch_active_orders
-from condor.fetchers.portfolio import fetch_portfolio
+from condor.fetchers.portfolio import fetch_portfolio, fetch_portfolio_history
 from condor.fetchers.positions import fetch_positions
 from condor.fetchers.server_status import fetch_server_status
 from condor.fetchers.trading_rules import fetch_trading_rules
 
 __all__ = [
     "fetch_portfolio",
+    "fetch_portfolio_history",
     "fetch_positions",
     "fetch_active_orders",
     "fetch_trading_rules",
diff --git a/condor/fetchers/portfolio.py b/condor/fetchers/portfolio.py
index 3d39bcac..e69c2a67 100644
--- a/condor/fetchers/portfolio.py
+++ b/condor/fetchers/portfolio.py
@@ -1,18 +1,42 @@
 """Fetch portfolio / balance data from Hummingbot API."""
 
 import logging
-from typing import Any, Dict, List, Optional
+import time
+from typing import Any, Dict, List, Optional, Tuple
 
 from condor.fetchers.connectors import fetch_available_cex_connectors
 
 logger = logging.getLogger(__name__)
 
+# Selectable history windows: range key -> (lookback seconds, candle interval).
+# Lives here rather than in the REST route because both the route and the WS
+# manager (which subscribes one SDS key per range) need it, and neither layer
+# may import the other.
+PORTFOLIO_HISTORY_RANGES: Dict[str, Tuple[int, str]] = {
+    "1D": (86400, "5m"),
+    "1W": (604800, "1h"),
+    "1M": (2592000, "4h"),
+    "3M": (7776000, "1d"),
+}
+
+# Poll cadence for a subscribed history range (seconds).
+PORTFOLIO_HISTORY_INTERVAL = 120
+
 
 async def fetch_portfolio(client, **_kw) -> Any:
     """Fetch full portfolio state from a server."""
     return await client.portfolio.get_state()
 
 
+async def fetch_portfolio_history(client, range_key: str = "1D", **_kw) -> Any:
+    """Fetch the raw portfolio history snapshots for one range window."""
+    range_seconds, interval = PORTFOLIO_HISTORY_RANGES[range_key]
+    start_time = int(time.time()) - range_seconds
+    return await client.portfolio.get_history(
+        start_time=start_time, interval=interval, limit=500
+    )
+
+
 async def fetch_portfolio_refreshed(client, **_kw) -> Any:
     """Fetch portfolio state with refresh=True to force exchange re-fetch."""
     return await client.portfolio.get_state(refresh=True)
diff --git a/condor/server_data_service.py b/condor/server_data_service.py
index 965df7bf..84815bee 100644
--- a/condor/server_data_service.py
+++ b/condor/server_data_service.py
@@ -34,6 +34,7 @@ class ServerDataType(Enum):
     """All data types fetchable from a Hummingbot server."""
 
     PORTFOLIO = "portfolio"
+    PORTFOLIO_HISTORY = "portfolio_history"
     PRICES = "prices"
     POSITIONS = "positions"
     ACTIVE_ORDERS = "active_orders"
@@ -56,10 +57,33 @@ class DataTypeDefaults:
 
     interval: float  # Default polling interval (seconds)
     ttl: float  # How long cached data is considered valid
+    # Optional per-param TTL override: (param_name, {param_value: ttl}). Some
+    # data types cache variants that go stale at very different rates — a 1D
+    # portfolio-history window is worthless after minutes while a 3M one holds
+    # for hours — and the key params say which variant this is.
+    ttl_by_param: Optional[Tuple[str, Dict[str, float]]] = None
+
+    def ttl_for(self, params: Dict[str, str]) -> float:
+        """TTL for a specific cache key's params."""
+        if not self.ttl_by_param:
+            return self.ttl
+        param_name, table = self.ttl_by_param
+        return table.get(params.get(param_name, ""), self.ttl)
 
 
 _DEFAULTS: Dict[ServerDataType, DataTypeDefaults] = {
     ServerDataType.PORTFOLIO: DataTypeDefaults(interval=10, ttl=60),
+    # History is polled at one cadence for every range (what the dashboard's
+    # hand-rolled refresh loop did), but each range stays valid for as long as
+    # its own resolution warrants once nobody is subscribed.
+    ServerDataType.PORTFOLIO_HISTORY: DataTypeDefaults(
+        interval=120,
+        ttl=120,
+        ttl_by_param=(
+            "range_key",
+            {"1D": 120, "1W": 600, "1M": 3600, "3M": 7200},
+        ),
+    ),
     ServerDataType.PRICES: DataTypeDefaults(interval=3, ttl=30),
     ServerDataType.POSITIONS: DataTypeDefaults(interval=10, ttl=60),
     ServerDataType.ACTIVE_ORDERS: DataTypeDefaults(interval=10, ttl=60),
@@ -368,7 +392,7 @@ def get(self, server: str, data_type: ServerDataType, **params) -> Optional[Any]
         age = time.time() - entry.fetched_at
 
         # Cached data is usable until the TTL expires
-        return entry.value if age <= defaults.ttl else None
+        return entry.value if age <= defaults.ttl_for(key.params_dict) else None
 
     async def get_or_fetch(
         self, server: str, data_type: ServerDataType, **params
@@ -813,7 +837,10 @@ def _cleanup_stale(self) -> None:
             if key in self._subscriptions and self._subscriptions[key]:
                 continue  # Active subscribers, keep
             defaults = _DEFAULTS.get(key.data_type)
-            if defaults and now - entry.fetched_at > defaults.ttl * 2:
+            if (
+                defaults
+                and now - entry.fetched_at > defaults.ttl_for(key.params_dict) * 2
+            ):
                 stale.append(key)
         for key in stale:
             del self._cache[key]
@@ -875,6 +902,7 @@ def register_default_fetches() -> None:
         fetch_current_price,
         fetch_executors,
         fetch_portfolio,
+        fetch_portfolio_history,
         fetch_positions,
         fetch_server_status,
         fetch_ticker_pool,
@@ -886,6 +914,7 @@ def register_default_fetches() -> None:
     sds = get_server_data_service()
 
     sds.register_fetch(ServerDataType.PORTFOLIO, fetch_portfolio)
+    sds.register_fetch(ServerDataType.PORTFOLIO_HISTORY, fetch_portfolio_history)
     sds.register_fetch(ServerDataType.PRICES, fetch_current_price)
     # strict=True on the cached reads: a failed call must reach
     # _do_fetch_and_cache's except branch (record_error, keep the last good
diff --git a/condor/web/routes/portfolio.py b/condor/web/routes/portfolio.py
index cf729131..90e69a30 100644
--- a/condor/web/routes/portfolio.py
+++ b/condor/web/routes/portfolio.py
@@ -1,14 +1,12 @@
 from __future__ import annotations
 
-import asyncio
 import logging
-import time
-from dataclasses import dataclass
 from datetime import datetime, timezone
 from typing import Any
 
 from fastapi import APIRouter, Depends, HTTPException, Query
 
+from condor.fetchers.portfolio import PORTFOLIO_HISTORY_RANGES
 from condor.web.auth import get_current_user
 from condor.web.models import (
     BalanceItem,
@@ -24,33 +22,6 @@
 
 router = APIRouter(tags=["portfolio"])
 
-# ---------------------------------------------------------------------------
-# Portfolio history cache
-# ---------------------------------------------------------------------------
-
-_RANGE_TTLS: dict[str, int] = {
-    "1D": 120,
-    "1W": 600,
-    "1M": 3600,
-    "3M": 7200,
-}
-
-_WARM_INTERVAL = 120  # Re-warm every 2 min (matches shortest TTL)
-_IDLE_TIMEOUT = 600  # Stop refresh loop after 10 min with no requests
-
-
-@dataclass
-class _CacheEntry:
-    data: Any = None
-    fetched_at: float = 0.0
-    ttl: int = 120
-
-
-# (server, range, False) -> CacheEntry  (breakdown doesn't affect fetched data)
-_history_cache: dict[tuple[str, str, bool], _CacheEntry] = {}
-_refresh_tasks: dict[str, asyncio.Task] = {}
-_last_request_time: dict[str, float] = {}  # server -> last request ts
-
 
 @router.get("/servers/{name}/portfolio", response_model=PortfolioResponse)
 async def get_portfolio(
@@ -196,106 +167,6 @@ def _dedupe_hyperliquid_unified(connectors: list[ConnectorBalance]) -> None:
     )
 
 
-RANGE_CONFIG = {
-    "1D": (86400, "5m"),
-    "1W": (604800, "1h"),
-    "1M": (2592000, "4h"),
-    "3M": (7776000, "1d"),
-}
-
-
-async def _fetch_history(server: str, range_key: str) -> Any:
-    """Fetch portfolio history from the Hummingbot API (no caching)."""
-    cm = get_config_manager()
-    client = await cm.get_client(server)
-    range_seconds, interval = RANGE_CONFIG[range_key]
-    start_time = int(time.time()) - range_seconds
-    return await client.portfolio.get_history(
-        start_time=start_time, interval=interval, limit=500
-    )
-
-
-async def _get_cached_history(
-    server: str, range_key: str, breakdown: bool = False
-) -> Any:
-    """Return cached history if fresh, otherwise fetch, cache, and return.
-
-    The raw data is the same regardless of *breakdown* (parsing happens in the
-    endpoint), so we cache without the breakdown flag to avoid duplicate fetches.
-    """
-    key = (server, range_key, False)
-    entry = _history_cache.get(key)
-    now = time.time()
-
-    if entry and entry.data is not None and (now - entry.fetched_at) < entry.ttl:
-        return entry.data
-
-    # Fetch fresh data
-    data = await _fetch_history(server, range_key)
-    _history_cache[key] = _CacheEntry(
-        data=data, fetched_at=time.time(), ttl=_RANGE_TTLS[range_key]
-    )
-    return data
-
-
-async def warm_portfolio_history(server: str) -> None:
-    """Pre-fetch all 4 history ranges into cache, then start a refresh loop."""
-    logger.info("Warming portfolio history cache for %s", server)
-    _last_request_time[server] = time.time()
-
-    # Initial warm: fetch all ranges concurrently (no breakdown)
-    tasks = []
-    for range_key in RANGE_CONFIG:
-        tasks.append(_get_cached_history(server, range_key, False))
-    results = await asyncio.gather(*tasks, return_exceptions=True)
-    for range_key, result in zip(RANGE_CONFIG, results):
-        if isinstance(result, Exception):
-            logger.warning("Warm cache failed for %s/%s: %s", server, range_key, result)
-
-    # Start background refresh loop if not already running
-    if server not in _refresh_tasks or _refresh_tasks[server].done():
-        _refresh_tasks[server] = asyncio.create_task(_refresh_loop(server))
-
-
-async def _refresh_loop(server: str) -> None:
-    """Periodically re-warm cache; exits after idle timeout."""
-    logger.info("Portfolio history refresh loop started for %s", server)
-    try:
-        while True:
-            await asyncio.sleep(_WARM_INTERVAL)
-            last = _last_request_time.get(server, 0)
-            if time.time() - last > _IDLE_TIMEOUT:
-                logger.info(
-                    "Portfolio history refresh loop idle for %s, stopping", server
-                )
-                return
-
-            tasks = []
-            for range_key in RANGE_CONFIG:
-                tasks.append(_fetch_history(server, range_key))
-            results = await asyncio.gather(*tasks, return_exceptions=True)
-            for range_key, result in zip(RANGE_CONFIG, results):
-                if isinstance(result, Exception):
-                    logger.debug(
-                        "Refresh failed for %s/%s: %s", server, range_key, result
-                    )
-                    continue
-                key = (server, range_key, False)
-                _history_cache[key] = _CacheEntry(
-                    data=result, fetched_at=time.time(), ttl=_RANGE_TTLS[range_key]
-                )
-    except asyncio.CancelledError:
-        logger.info("Portfolio history refresh loop cancelled for %s", server)
-
-
-def stop_history_refresh(server: str) -> None:
-    """Cancel the background refresh loop for a server."""
-    task = _refresh_tasks.pop(server, None)
-    if task and not task.done():
-        task.cancel()
-        logger.info("Stopped portfolio history refresh for %s", server)
-
-
 @router.get(
     "/servers/{name}/portfolio/history", response_model=PortfolioHistoryResponse
 )
@@ -309,16 +180,20 @@ async def get_portfolio_history(
     if not cm.has_server_access(user.id, name):
         raise HTTPException(status_code=403, detail="No access to this server")
 
-    _last_request_time[name] = time.time()
+    from condor.server_data_service import ServerDataType, get_server_data_service
 
+    # The raw snapshots are the same regardless of *breakdown* (parsing happens
+    # below), so the cache key is the range alone. SDS coalesces concurrent
+    # reads of the same expired key into one backend fetch.
     try:
-        history = await _get_cached_history(name, range, breakdown)
+        history = await get_server_data_service().get_or_fetch(
+            name, ServerDataType.PORTFOLIO_HISTORY, range_key=range
+        )
     except Exception as e:
         logger.warning("Failed to get portfolio history: %s", e)
-        _, interval = RANGE_CONFIG[range]
-        return PortfolioHistoryResponse(server=name, points=[], interval=interval)
+        history = None
 
-    _, interval = RANGE_CONFIG[range]
+    _, interval = PORTFOLIO_HISTORY_RANGES[range]
 
     logger.debug("Portfolio history response shape: %s", type(history))
     if isinstance(history, dict):
diff --git a/condor/web/ws_manager.py b/condor/web/ws_manager.py
index 69f2b11c..6037a380 100644
--- a/condor/web/ws_manager.py
+++ b/condor/web/ws_manager.py
@@ -363,13 +363,12 @@ def _maybe_unsub_sds(self, channel: str) -> None:
             sds.unsubscribe(cache_key, "ws_manager")
             logger.debug("WS unsubscribed SDS for channel %s", channel)
 
-            # Stop portfolio history refresh when no subscribers remain
+            # The history ranges ride on this subscription — drop them too, or
+            # their polls would outlive the last dashboard client watching.
             if channel.startswith("portfolio:"):
-                from condor.web.routes.portfolio import stop_history_refresh
-
                 server_name = channel.split(":")[1] if ":" in channel else ""
                 if server_name:
-                    stop_history_refresh(server_name)
+                    self._unsubscribe_portfolio_history(server_name)
 
     # -- Message handling --
 
@@ -604,19 +603,84 @@ async def _subscribe_sds(self, channel: str) -> None:
                 if result != prev:
                     await self.broadcast(channel, result)
 
-            # Pre-warm portfolio history cache on subscription
+            # Portfolio history rides on the portfolio subscription: one SDS
+            # key per range, primed now and polled until the last client leaves.
             if prefix == "portfolio":
-                from condor.web.routes.portfolio import warm_portfolio_history
-
                 self._track_oneshot(
                     asyncio.create_task(
-                        warm_portfolio_history(server_name),
-                        name=f"warm_portfolio_history:{server_name}",
+                        self._subscribe_portfolio_history(channel, server_name),
+                        name=f"portfolio_history:{server_name}",
                     )
                 )
         except Exception as e:
             logger.debug("Failed to subscribe SDS for %s: %s", channel, e)
 
+    async def _subscribe_portfolio_history(
+        self, channel: str, server_name: str
+    ) -> None:
+        """Subscribe one SDS key per history range behind a portfolio channel.
+
+        Runs off the subscribe path as a one-shot task: SDS primes each key with
+        a real backend fetch and the WS client must not wait for four of them.
+        Subscribing is idempotent per (key, subscriber), so a second client on
+        the same channel never starts a second poll. If the channel is torn down
+        while the priming is in flight, unsubscribe again — otherwise the poll
+        would outlive its last subscriber.
+        """
+        from condor.fetchers.portfolio import (
+            PORTFOLIO_HISTORY_INTERVAL,
+            PORTFOLIO_HISTORY_RANGES,
+        )
+        from condor.server_data_service import ServerDataType, get_server_data_service
+
+        sds = get_server_data_service()
+
+        async def _sub(range_key: str) -> None:
+            try:
+                await sds.subscribe(
+                    server=server_name,
+                    data_type=ServerDataType.PORTFOLIO_HISTORY,
+                    subscriber_id="ws_manager",
+                    interval=PORTFOLIO_HISTORY_INTERVAL,
+                    range_key=range_key,
+                )
+            except Exception as e:
+                logger.debug(
+                    "Failed to subscribe portfolio history %s/%s: %s",
+                    server_name,
+                    range_key,
+                    e,
+                )
+
+        await asyncio.gather(*[_sub(rk) for rk in PORTFOLIO_HISTORY_RANGES])
+
+        if channel not in self._sds_subscriptions:
+            self._unsubscribe_portfolio_history(server_name)
+
+    def _unsubscribe_portfolio_history(self, server_name: str) -> None:
+        """Drop this manager's history subscriptions for a server.
+
+        SDS stops polling a key once it has no subscribers left, so this is what
+        ends the history refresh.
+        """
+        from condor.fetchers.portfolio import PORTFOLIO_HISTORY_RANGES
+        from condor.server_data_service import (
+            CacheKey,
+            ServerDataType,
+            get_server_data_service,
+        )
+
+        sds = get_server_data_service()
+        for range_key in PORTFOLIO_HISTORY_RANGES:
+            sds.unsubscribe(
+                CacheKey.make(
+                    server_name,
+                    ServerDataType.PORTFOLIO_HISTORY,
+                    range_key=range_key,
+                ),
+                "ws_manager",
+            )
+
     # -- SDS listener (legacy-compatible signature) --
 
     @staticmethod
diff --git a/tests/test_portfolio_history_sds.py b/tests/test_portfolio_history_sds.py
new file mode 100644
index 00000000..8b2685ee
--- /dev/null
+++ b/tests/test_portfolio_history_sds.py
@@ -0,0 +1,377 @@
+"""Tests for ARCH-145: portfolio history is a ServerDataService data type.
+
+``condor/web/routes/portfolio.py`` used to hold module-level polling state
+(``_history_cache``/``_refresh_tasks``/``_last_request_time``) and hand-roll the
+whole subscription lifecycle — prime, 120s refresh loop, idle timeout,
+per-range TTL — while ``ws_manager`` imported that REST route module to start
+and stop it. That is what SDS already does, minus the single-flight coalescing
+the hand-rolled cache lacked.
+
+The three things a silent regression would break, and that these tests pin:
+the endpoint still serves the same payload, the poll really starts when a
+portfolio WS subscriber appears and really stops when the last one leaves, and
+a second subscriber never spawns a duplicate poll.
+"""
+
+import asyncio
+from pathlib import Path
+
+import pytest
+
+from condor.fetchers.portfolio import (
+    PORTFOLIO_HISTORY_INTERVAL,
+    PORTFOLIO_HISTORY_RANGES,
+    fetch_portfolio_history,
+)
+from condor.server_data_service import (
+    _DEFAULTS,
+    CacheKey,
+    ServerDataService,
+    ServerDataType,
+)
+from condor.web.models import WebUser
+from condor.web.routes.portfolio import get_portfolio_history
+from condor.web.ws_manager import WebSocketManager, _Connection
+
+_USER = WebUser(id=1, role="admin")
+
+# Two snapshots of one account: BTC 100 -> 120, ETH 50 -> 40.
+_HISTORY = [
+    {
+        "timestamp": 1000,
+        "state": {
+            "master": {
+                "binance": [
+                    {"token": "BTC", "value": 100.0},
+                    {"token": "ETH", "value": 50.0},
+                ]
+            }
+        },
+    },
+    {
+        "timestamp": 2000,
+        "state": {
+            "master": {
+                "binance": [
+                    {"token": "BTC", "value": 120.0},
+                    {"token": "ETH", "value": 40.0},
+                ]
+            }
+        },
+    },
+]
+
+
+class _FakePortfolio:
+    def __init__(self, client):
+        self._client = client
+
+    async def get_history(self, **kwargs):
+        self._client.history_calls.append(kwargs)
+        if self._client.delay:
+            await asyncio.sleep(self._client.delay)
+        return _HISTORY
+
+    async def get_state(self, **kwargs):
+        self._client.state_calls.append(kwargs)
+        return {"master": {"binance": []}}
+
+
+class FakeClient:
+    """Hummingbot client recording every history request."""
+
+    def __init__(self, delay: float = 0.0):
+        self.history_calls: list[dict] = []
+        self.state_calls: list[dict] = []
+        self.delay = delay
+        self.portfolio = _FakePortfolio(self)
+
+
+class _FakeCM:
+    def has_server_access(self, user_id, name, *a, **kw):
+        return True
+
+
+def _make_sds(client: FakeClient) -> ServerDataService:
+    """Fresh (non-singleton) SDS wired to a fake client, history registered."""
+    sds = ServerDataService()
+
+    async def _fake_get_client(server_name):
+        return client
+
+    sds._get_client = _fake_get_client
+    sds.register_fetch(ServerDataType.PORTFOLIO_HISTORY, fetch_portfolio_history)
+    from condor.fetchers.portfolio import fetch_portfolio
+
+    sds.register_fetch(ServerDataType.PORTFOLIO, fetch_portfolio)
+    return sds
+
+
+@pytest.fixture
+def env(monkeypatch):
+    """Bind the REST route and the WS manager to one fresh SDS + fake client."""
+
+    def _bind(delay: float = 0.0):
+        client = FakeClient(delay=delay)
+        sds = _make_sds(client)
+        monkeypatch.setattr(
+            "condor.server_data_service.get_server_data_service", lambda: sds
+        )
+        monkeypatch.setattr(
+            "condor.web.routes.portfolio.get_config_manager", lambda: _FakeCM()
+        )
+        return sds, client
+
+    return _bind
+
+
+# ── the payload the dashboard receives ──
+
+
+def test_endpoint_serves_the_same_payload_through_sds(env):
+    """Totals, timestamps and interval are unchanged by the migration."""
+    sds, client = env()
+
+    resp = asyncio.run(get_portfolio_history(name="srv", range="1D", user=_USER))
+
+    assert resp.server == "srv"
+    assert resp.interval == "5m"
+    assert [(p.timestamp, p.total_usd) for p in resp.points] == [
+        (1000.0, 150.0),
+        (2000.0, 160.0),
+    ]
+    assert len(client.history_calls) == 1
+    assert client.history_calls[0]["interval"] == "5m"
+    assert client.history_calls[0]["limit"] == 500
+
+
+def test_endpoint_still_builds_the_token_breakdown(env):
+    """``breakdown=true`` keeps returning per-token values and top tokens."""
+    sds, client = env()
+
+    resp = asyncio.run(
+        get_portfolio_history(name="srv", range="1D", breakdown=True, user=_USER)
+    )
+
+    assert resp.top_tokens == ["BTC", "ETH"]
+    assert [p.tokens for p in resp.points] == [
+        {"BTC": 100.0, "ETH": 50.0},
+        {"BTC": 120.0, "ETH": 40.0},
+    ]
+
+
+def test_second_read_of_a_fresh_range_is_served_from_cache(env):
+    """The cache still absorbs repeat reads — one backend call for two reads."""
+    sds, client = env()
+
+    async def _drive():
+        await get_portfolio_history(name="srv", range="1W", user=_USER)
+        return await get_portfolio_history(name="srv", range="1W", user=_USER)
+
+    resp = asyncio.run(_drive())
+
+    assert resp.interval == "1h"
+    assert len(client.history_calls) == 1
+
+
+def test_concurrent_expired_reads_coalesce_to_one_fetch(env):
+    """The gap the hand-rolled TTL cache had: two concurrent cold reads of the
+    same range must issue one backend request, not two."""
+    sds, client = env(delay=0.05)
+
+    async def _drive():
+        return await asyncio.gather(
+            get_portfolio_history(name="srv", range="1M", user=_USER),
+            get_portfolio_history(name="srv", range="1M", user=_USER),
+        )
+
+    first, second = asyncio.run(_drive())
+
+    assert len(client.history_calls) == 1, "concurrent cold reads must coalesce"
+    assert first.points == second.points
+
+
+def test_each_range_is_cached_separately(env):
+    """Ranges are distinct cache keys — switching range refetches."""
+    sds, client = env()
+
+    async def _drive():
+        for range_key in PORTFOLIO_HISTORY_RANGES:
+            await get_portfolio_history(name="srv", range=range_key, user=_USER)
+
+    asyncio.run(_drive())
+
+    assert len(client.history_calls) == len(PORTFOLIO_HISTORY_RANGES)
+    assert {c["interval"] for c in client.history_calls} == {
+        interval for _, interval in PORTFOLIO_HISTORY_RANGES.values()
+    }
+
+
+def test_per_range_ttls_survived_the_move():
+    """The old _RANGE_TTLS table now lives on the data type's defaults."""
+    defaults = _DEFAULTS[ServerDataType.PORTFOLIO_HISTORY]
+
+    assert defaults.interval == PORTFOLIO_HISTORY_INTERVAL
+    assert {
+        rk: defaults.ttl_for({"range_key": rk}) for rk in PORTFOLIO_HISTORY_RANGES
+    } == {"1D": 120, "1W": 600, "1M": 3600, "3M": 7200}
+
+
+# ── the lifecycle ws_manager drives ──
+
+
+def _history_keys(server: str) -> list[CacheKey]:
+    return [
+        CacheKey.make(server, ServerDataType.PORTFOLIO_HISTORY, range_key=rk)
+        for rk in PORTFOLIO_HISTORY_RANGES
+    ]
+
+
+async def _drain(manager: WebSocketManager) -> None:
+    """Await the one-shot tasks the manager currently holds."""
+    await asyncio.gather(*list(manager._oneshot_tasks), return_exceptions=True)
+    await asyncio.sleep(0)
+
+
+def _expire(sds: ServerDataService) -> None:
+    """Age every cache entry past its interval so the next tick is due."""
+    for entry in sds._cache.values():
+        entry.fetched_at = 0.0
+
+
+def test_poll_starts_with_the_portfolio_subscriber_and_stops_with_it(env):
+    """A silently-never-started poll is a dead chart no shape test would catch:
+    drive real poll ticks before and after the subscriber leaves."""
+    sds, client = env()
+
+    async def _drive():
+        manager = WebSocketManager()
+        conn = _Connection(_FakeWS(), user_id=1)
+        conn.channels.add("portfolio:srv")
+        manager._connections.append(conn)
+
+        await manager._subscribe_sds("portfolio:srv")
+        await _drain(manager)
+        subscribed = len(sds._subscriptions)
+        primed = len(client.history_calls)
+
+        # The poll runs while the subscriber is there.
+        _expire(sds)
+        await sds._poll_tick()
+        polled = len(client.history_calls)
+
+        # Last subscriber leaves.
+        conn.channels.discard("portfolio:srv")
+        manager._maybe_unsub_sds("portfolio:srv")
+        after_unsub = len(client.history_calls)
+
+        _expire(sds)
+        await sds._poll_tick()
+        return subscribed, primed, polled, after_unsub, len(client.history_calls), sds
+
+    subscribed, primed, polled, after_unsub, final, sds = asyncio.run(_drive())
+
+    # One key per range, plus the PORTFOLIO subscription itself.
+    assert subscribed == len(PORTFOLIO_HISTORY_RANGES) + 1
+    assert primed == len(PORTFOLIO_HISTORY_RANGES), "every range primed on subscribe"
+    assert polled == primed + len(PORTFOLIO_HISTORY_RANGES), "poll must be running"
+    assert final == after_unsub, "poll must stop once the last subscriber leaves"
+    assert not any(k in sds._subscriptions for k in _history_keys("srv"))
+
+
+def test_history_subscriptions_use_the_previous_refresh_cadence(env):
+    """The loop re-warmed every range every 120s; the subscriptions must too."""
+    sds, _client = env()
+
+    async def _drive():
+        manager = WebSocketManager()
+        await manager._subscribe_sds("portfolio:srv")
+        await _drain(manager)
+        return {
+            key: [s.interval for s in subs.values()]
+            for key, subs in sds._subscriptions.items()
+            if key.data_type is ServerDataType.PORTFOLIO_HISTORY
+        }
+
+    intervals = asyncio.run(_drive())
+
+    assert len(intervals) == len(PORTFOLIO_HISTORY_RANGES)
+    assert all(iv == [PORTFOLIO_HISTORY_INTERVAL] for iv in intervals.values())
+
+
+def test_second_subscriber_does_not_spawn_a_duplicate_poll(env):
+    """Two clients on the same channel share one poll per range."""
+    sds, client = env()
+
+    async def _drive():
+        manager = WebSocketManager()
+        for user_id in (1, 2):
+            conn = _Connection(_FakeWS(), user_id=user_id)
+            conn.channels.add("portfolio:srv")
+            manager._connections.append(conn)
+            await manager._subscribe_sds("portfolio:srv")
+            await _drain(manager)
+
+        _expire(sds)
+        before = len(client.history_calls)
+        await sds._poll_tick()
+        return before, len(client.history_calls) - before, sds
+
+    primed, per_tick, sds = asyncio.run(_drive())
+
+    assert primed == len(PORTFOLIO_HISTORY_RANGES), "no second priming round"
+    assert per_tick == len(PORTFOLIO_HISTORY_RANGES), "one fetch per range per tick"
+    for key in _history_keys("srv"):
+        assert list(sds._subscriptions[key]) == ["ws_manager"]
+
+
+def test_first_client_leaving_keeps_the_poll_alive_for_the_second(env):
+    """Only the *last* subscriber leaving stops the history poll."""
+    sds, _client = env()
+
+    async def _drive():
+        manager = WebSocketManager()
+        conns = []
+        for user_id in (1, 2):
+            conn = _Connection(_FakeWS(), user_id=user_id)
+            conn.channels.add("portfolio:srv")
+            manager._connections.append(conn)
+            conns.append(conn)
+        await manager._subscribe_sds("portfolio:srv")
+        await _drain(manager)
+
+        manager.disconnect(conns[0])
+        return all(k in sds._subscriptions for k in _history_keys("srv"))
+
+    assert asyncio.run(_drive()) is True
+
+
+def test_ws_manager_does_not_import_the_rest_route_module():
+    """The coupling this item removed must not creep back in."""
+    source = Path("condor/web/ws_manager.py").read_text()
+
+    assert "routes.portfolio" not in source
+    assert "routes import portfolio" not in source
+
+
+def test_route_module_holds_no_polling_state():
+    """No module-level cache, task dict or refresh loop left in the route."""
+    import condor.web.routes.portfolio as route
+
+    for leftover in (
+        "_history_cache",
+        "_refresh_tasks",
+        "_last_request_time",
+        "_refresh_loop",
+        "warm_portfolio_history",
+        "stop_history_refresh",
+    ):
+        assert not hasattr(route, leftover), f"{leftover} survived the migration"
+
+
+class _FakeWS:
+    def __init__(self):
+        self.sent: list[dict] = []
+
+    async def send_json(self, payload: dict) -> None:
+        self.sent.append(payload)

From e854452cfd415e678baacd60b45774dfc12c9482 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Fri, 14 Aug 2026 15:35:35 +0300
Subject: [PATCH 071/116] (refactor) SDS listeners get the typed CacheKey
 (ARCH-155)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

_notify_listeners hand-built DataManager-era key strings (cex_prices:*,
cex_balances:*, bots_status, executors) for its single listener,
ws_manager._on_data_update, which split the PRICES one back apart to
rebuild a different prefix and ignored the rest. The DataManager those
strings spoke for was deleted by READ-049.

Listeners now receive the key itself: cb(key: CacheKey, value). Channel
naming moves into ws_manager.channel_for_key, which reads the params off
the key via _CHANNEL_KEY_PARAMS — one table that also drives the inverse
direction (channel segments -> key params when subscribing), so a
parameterized data type is addressable from a single source of truth
instead of string munging kept in sync by convention across two files.

Parameterized keys are now routed, not flattened: a key whose params do
not address the channel (portfolio history's range_key, an account-scoped
portfolio write) resolves to no channel instead of landing on the
server-wide one.

Also fixes remove_listener comparing bound methods by identity, which
never matched: stop() left a dead manager wired to the SDS singleton.
---
 condor/server_data_service.py          |  39 ++---
 condor/web/ws_manager.py               |  81 +++++++---
 tests/test_sds_listener_typed_keys.py  | 202 +++++++++++++++++++++++++
 tests/test_ws_manager_oneshot_tasks.py |  21 +--
 4 files changed, 282 insertions(+), 61 deletions(-)
 create mode 100644 tests/test_sds_listener_typed_keys.py

diff --git a/condor/server_data_service.py b/condor/server_data_service.py
index 84815bee..96a02b8f 100644
--- a/condor/server_data_service.py
+++ b/condor/server_data_service.py
@@ -462,40 +462,29 @@ def invalidate_server(self, server: str) -> None:
             len(keys_to_remove),
         )
 
-    # ------ Listener compatibility (for WebSocketManager) ------
+    # ------ Cache-write listeners (for WebSocketManager) ------
 
     def add_listener(self, callback: Callable) -> None:
-        """Add a sync listener: callback(server_name, cache_key_str, data_type_name, value)"""
+        """Add a sync listener: ``callback(key: CacheKey, value: Any)``.
+
+        Fired on every cache write. The listener gets the typed key — server,
+        data type and params — so it never has to parse anything back out of a
+        formatted string.
+        """
         self._listeners.append(callback)
 
     def remove_listener(self, callback: Callable) -> None:
-        self._listeners = [cb for cb in self._listeners if cb is not callback]
+        # Compared by equality, not identity: the only listener is a bound
+        # method (``ws_manager._on_data_update``), and attribute access builds a
+        # fresh method object every time, so ``is`` never matched the one that
+        # was registered and stop() left a dead manager wired to the singleton.
+        self._listeners = [cb for cb in self._listeners if cb != callback]
 
     def _notify_listeners(self, key: CacheKey, value: Any) -> None:
-        """Notify listeners with server/channel/data_type/value arguments.
-
-        The WS manager uses the data_type name string to map to channels.
-        """
-        if not self._listeners:
-            return
-
-        # Build a channel-compatible cache_key string
-        params = key.params_dict
-        if key.data_type == ServerDataType.PRICES:
-            cache_key_str = f"cex_prices:{params.get('connector_name', '')}:{params.get('trading_pair', '')}"
-        elif key.data_type == ServerDataType.PORTFOLIO:
-            account = params.get("account_name", "")
-            cache_key_str = f"cex_balances:{account}" if account else "portfolio"
-        elif key.data_type == ServerDataType.BOTS_STATUS:
-            cache_key_str = "bots_status"
-        elif key.data_type == ServerDataType.EXECUTORS:
-            cache_key_str = "executors"
-        else:
-            cache_key_str = key.data_type.value
-
+        """Hand the written key and its value to every listener, unchanged."""
         for cb in self._listeners:
             try:
-                cb(key.server, cache_key_str, key.data_type, value)
+                cb(key, value)
             except Exception as e:
                 logger.debug("SDS listener error: %s", e)
 
diff --git a/condor/web/ws_manager.py b/condor/web/ws_manager.py
index 6037a380..00558020 100644
--- a/condor/web/ws_manager.py
+++ b/condor/web/ws_manager.py
@@ -5,7 +5,7 @@
 import logging
 import math
 import time
-from typing import Any, Awaitable, Callable, Optional
+from typing import TYPE_CHECKING, Any, Awaitable, Callable, Optional
 
 from fastapi import WebSocket
 
@@ -13,6 +13,9 @@
 from condor.fetchers.market_data import fetch_historical_candles, normalize_candle
 from condor.web.auth import decode_jwt
 
+if TYPE_CHECKING:
+    from condor.server_data_service import CacheKey
+
 logger = logging.getLogger(__name__)
 
 # Mapping from WS channel prefix to ServerDataType
@@ -23,13 +26,52 @@
     "prices": "PRICES",
 }
 
-# Reverse mapping for listener compatibility
+# Reverse mapping, for naming the channel a cache write belongs to
 _SDT_TO_CHANNEL_PREFIX = {
     "PORTFOLIO": "portfolio",
     "BOTS_STATUS": "bots",
     "PRICES": "prices",
 }
 
+# CacheKey params a data type's channel is scoped by, in channel-segment order.
+# A data type absent from this table has a server-wide channel (`{prefix}:{server}`)
+# and its key must carry no params at all — an account-scoped portfolio or any
+# other parameterized variant is a *different* dataset and must not be broadcast
+# to the server-wide channel. This is the single source of truth for both
+# directions: channel -> key params when subscribing, key -> channel when
+# broadcasting.
+_CHANNEL_KEY_PARAMS: dict[str, tuple[str, ...]] = {
+    "PRICES": ("connector_name", "trading_pair"),
+}
+
+
+def channel_for_key(key: CacheKey) -> str | None:
+    """WS channel a written SDS ``CacheKey`` belongs to, or ``None`` if none does.
+
+    ``None`` means "no channel carries this data" (a data type the dashboard does
+    not stream, e.g. portfolio history, or a parameterized variant of a
+    server-wide type) — never a silent drop of data a channel was waiting for:
+    a key that names a channel but is missing the params to address it is logged.
+    """
+    prefix = _SDT_TO_CHANNEL_PREFIX.get(key.data_type.name)
+    if not prefix:
+        return None
+
+    params = key.params_dict
+    param_names = _CHANNEL_KEY_PARAMS.get(key.data_type.name, ())
+    if set(params) != set(param_names):
+        logger.debug(
+            "No %s channel for key with params %s (expected %s)",
+            prefix,
+            sorted(params),
+            list(param_names),
+        )
+        return None
+
+    segments = [params[name] for name in param_names]
+    return ":".join([prefix, key.server, *segments])
+
+
 # Interval string -> seconds for buffer sizing
 _INTERVAL_SECONDS: dict[str, int] = {
     "1s": 1,
@@ -582,10 +624,12 @@ async def _subscribe_sds(self, channel: str) -> None:
         sds = get_server_data_service()
         data_type = ServerDataType[sdt_name]
 
-        # Build params for price channels
-        params = {}
-        if sdt_name == "PRICES" and len(parts) >= 4:
-            params = {"connector_name": parts[2], "trading_pair": parts[3]}
+        # Params the channel scopes its key by, read off the channel segments
+        # that follow the server (same table the broadcast direction uses).
+        param_names = _CHANNEL_KEY_PARAMS.get(sdt_name, ())
+        if len(parts) < 2 + len(param_names):
+            return
+        params = dict(zip(param_names, parts[2:]))
 
         try:
             cache_key = await sds.subscribe(
@@ -681,7 +725,7 @@ def _unsubscribe_portfolio_history(self, server_name: str) -> None:
                 "ws_manager",
             )
 
-    # -- SDS listener (legacy-compatible signature) --
+    # -- SDS listener --
 
     @staticmethod
     def _transform_executors(raw_data: Any) -> list[dict]:
@@ -713,24 +757,15 @@ def _overlay_stopping_state(server_name: str, data: dict) -> None:
             server_name, data.get("controllers", []), data.get("bots", [])
         )
 
-    def _on_data_update(
-        self, server_name: str, cache_key: str, data_type: Any, value: Any
-    ) -> None:
-        """Called by SDS when cache is updated. Maps to WS channels and broadcasts."""
-        dt_name = data_type.name if hasattr(data_type, "name") else str(data_type)
-        prefix = _SDT_TO_CHANNEL_PREFIX.get(dt_name)
-        if not prefix:
+    def _on_data_update(self, key: CacheKey, value: Any) -> None:
+        """Called by SDS on every cache write. Maps the key to a WS channel and
+        broadcasts. ``key`` is an SDS ``CacheKey``: server, data type and params."""
+        channel = channel_for_key(key)
+        if channel is None:
             return
 
-        # Build channel name
-        if dt_name == "PRICES":
-            parts = cache_key.split(":")
-            if len(parts) >= 3:
-                channel = f"prices:{server_name}:{parts[1]}:{parts[2]}"
-            else:
-                return
-        else:
-            channel = f"{prefix}:{server_name}"
+        dt_name = key.data_type.name
+        server_name = key.server
 
         has_subscribers = any(channel in conn.channels for conn in self._connections)
         if not has_subscribers:
diff --git a/tests/test_sds_listener_typed_keys.py b/tests/test_sds_listener_typed_keys.py
new file mode 100644
index 00000000..5e4f6f71
--- /dev/null
+++ b/tests/test_sds_listener_typed_keys.py
@@ -0,0 +1,202 @@
+"""Tests for ARCH-155: the SDS listener protocol speaks typed CacheKeys.
+
+``_notify_listeners`` used to flatten each written key into a DataManager-era
+string (``cex_prices:{connector}:{pair}``, ``cex_balances:{account}``,
+``bots_status``, ``executors``) that its single listener — ws_manager's
+``_on_data_update`` — split back apart to rebuild a *different* prefix. The key
+already carries server, data type and params; the listener now receives it
+whole, so a parameterized data type is addressable without string munging in
+two files kept in sync by convention.
+
+What a regression would break, and what these pin: the key survives the hop
+byte-for-byte (params included, e.g. a portfolio-history range), a key that no
+channel carries is dropped deliberately rather than misrouted onto a sibling
+channel, and no per-data-type string synthesis creeps back into SDS.
+"""
+
+import asyncio
+import inspect
+
+from condor.server_data_service import (
+    CacheKey,
+    ServerDataService,
+    ServerDataType,
+    get_server_data_service,
+)
+from condor.web.ws_manager import WebSocketManager, _Connection, channel_for_key
+
+
+class _FakeWS:
+    def __init__(self):
+        self.sent: list[dict] = []
+
+    async def send_json(self, payload: dict) -> None:
+        self.sent.append(payload)
+
+
+def _manager_with_subscriber(channel: str) -> tuple[WebSocketManager, _FakeWS]:
+    manager = WebSocketManager()
+    ws = _FakeWS()
+    conn = _Connection(ws, user_id=1)
+    conn.channels.add(channel)
+    manager._connections.append(conn)
+    return manager, ws
+
+
+async def _drain(manager: WebSocketManager) -> None:
+    await asyncio.gather(*list(manager._oneshot_tasks), return_exceptions=True)
+    await asyncio.sleep(0)
+
+
+def _capture(sds: ServerDataService) -> list[tuple]:
+    seen: list[tuple] = []
+    sds.add_listener(lambda key, value: seen.append((key, value)))
+    return seen
+
+
+def test_typed_key_round_trips_from_cache_write_to_listener():
+    """The listener gets the key object itself — nothing is stringified."""
+    sds = ServerDataService()
+    seen = _capture(sds)
+
+    sds.put(
+        "srv",
+        ServerDataType.PRICES,
+        1.23,
+        connector_name="binance",
+        trading_pair="BTC-USDT",
+    )
+
+    assert len(seen) == 1
+    key, value = seen[0]
+    assert isinstance(key, CacheKey)
+    assert key == CacheKey.make(
+        "srv",
+        ServerDataType.PRICES,
+        connector_name="binance",
+        trading_pair="BTC-USDT",
+    )
+    assert key.server == "srv"
+    assert key.data_type is ServerDataType.PRICES
+    assert value == 1.23
+    # And the channel is derived from the key's params, not re-parsed from a string.
+    assert channel_for_key(key) == "prices:srv:binance:BTC-USDT"
+
+
+def test_parameterized_history_key_survives_the_listener_hop_intact():
+    """A portfolio-history key keeps its range_key param end to end (ARCH-145)."""
+    sds = ServerDataService()
+    seen = _capture(sds)
+
+    sds.put("srv", ServerDataType.PORTFOLIO_HISTORY, [{"v": 1}], range_key="1d")
+    sds.put("srv", ServerDataType.PORTFOLIO_HISTORY, [{"v": 2}], range_key="3m")
+
+    assert [k.params_dict for k, _ in seen] == [
+        {"range_key": "1d"},
+        {"range_key": "3m"},
+    ]
+    assert [v for _, v in seen] == [[{"v": 1}], [{"v": 2}]]
+    # No WS channel streams history: it is served from the SDS cache over REST.
+    assert [channel_for_key(k) for k, _ in seen] == [None, None]
+
+
+def test_history_write_is_not_broadcast_onto_the_portfolio_channel():
+    """The parameterized key must not collapse onto its data type's neighbours."""
+    manager, ws = _manager_with_subscriber("portfolio:srv")
+
+    async def scenario():
+        manager._on_data_update(
+            CacheKey.make("srv", ServerDataType.PORTFOLIO_HISTORY, range_key="1d"),
+            [{"v": 1}],
+        )
+        await _drain(manager)
+
+    asyncio.run(scenario())
+
+    assert ws.sent == [], "portfolio history leaked onto the portfolio channel"
+    assert manager._oneshot_tasks == set()
+
+
+def test_account_scoped_portfolio_is_not_broadcast_to_the_server_channel():
+    """`portfolio:{server}` is the whole-server portfolio; an account-scoped
+    write (Telegram's per-account balances) is a different dataset."""
+    manager, ws = _manager_with_subscriber("portfolio:srv")
+
+    async def scenario():
+        manager._on_data_update(
+            CacheKey.make("srv", ServerDataType.PORTFOLIO, account_name="master"),
+            {"total": 999},
+        )
+        manager._on_data_update(
+            CacheKey.make("srv", ServerDataType.PORTFOLIO), {"total": 1}
+        )
+        await _drain(manager)
+
+    asyncio.run(scenario())
+
+    assert [m["data"] for m in ws.sent] == [{"total": 1}]
+
+
+def test_key_without_a_channel_is_dropped_deliberately_not_misrouted():
+    """Data types the dashboard does not stream resolve to no channel at all."""
+    for data_type in (
+        ServerDataType.EXECUTORS,
+        ServerDataType.POSITIONS,
+        ServerDataType.TICKER_POOL,
+    ):
+        assert channel_for_key(CacheKey.make("srv", data_type)) is None
+
+    # A price key missing the params that address its channel is not guessed at.
+    assert channel_for_key(CacheKey.make("srv", ServerDataType.PRICES)) is None
+    assert (
+        channel_for_key(
+            CacheKey.make("srv", ServerDataType.PRICES, connector_name="binance")
+        )
+        is None
+    )
+
+
+def test_listener_registration_survives_a_failing_listener():
+    """One listener raising must not stop the others (or the cache write)."""
+    sds = ServerDataService()
+    sds.add_listener(lambda key, value: (_ for _ in ()).throw(RuntimeError("boom")))
+    seen = _capture(sds)
+
+    sds.put("srv", ServerDataType.BOTS_STATUS, {"bots": []})
+
+    assert [k.data_type for k, _ in seen] == [ServerDataType.BOTS_STATUS]
+    assert sds.get("srv", ServerDataType.BOTS_STATUS) == {"bots": []}
+
+
+def test_sds_synthesizes_no_legacy_cache_key_strings():
+    """Guards the regression: the DataManager-era key strings are gone for good."""
+    import condor.server_data_service as sds_module
+
+    source = inspect.getsource(sds_module)
+    assert "cex_prices" not in source
+    assert "cex_balances" not in source
+
+    notify = inspect.getsource(sds_module.ServerDataService._notify_listeners)
+    assert 'f"' not in notify, "per-data-type string formatting is back"
+
+
+def test_ws_manager_listener_registers_and_unregisters_on_the_live_service():
+    """The one registration site wires up — and unwires — against the singleton.
+
+    ``_on_data_update`` is a bound method: every attribute access builds a new
+    object, so removal has to compare by equality or ``stop()`` leaks a dead
+    manager into the singleton's listener list.
+    """
+    manager = WebSocketManager()
+    sds = get_server_data_service()
+    before = len(sds._listeners)
+
+    manager._sds_listener_registered = True  # skip the candle cleanup task
+    sds.add_listener(manager._on_data_update)
+    try:
+        assert len(sds._listeners) == before + 1
+        sig = inspect.signature(manager._on_data_update)
+        assert list(sig.parameters) == ["key", "value"]
+    finally:
+        sds.remove_listener(manager._on_data_update)
+    assert len(sds._listeners) == before
diff --git a/tests/test_ws_manager_oneshot_tasks.py b/tests/test_ws_manager_oneshot_tasks.py
index 7418ca58..e27e527f 100644
--- a/tests/test_ws_manager_oneshot_tasks.py
+++ b/tests/test_ws_manager_oneshot_tasks.py
@@ -12,6 +12,7 @@
 import inspect
 import logging
 
+from condor.server_data_service import CacheKey, ServerDataType
 from condor.web.ws_manager import WebSocketManager, _Connection
 
 WS_LOGGER = "condor.web.ws_manager"
@@ -25,11 +26,9 @@ async def send_json(self, payload: dict) -> None:
         self.sent.append(payload)
 
 
-class _FakeDataType:
-    """Stands in for the SDS ServerDataType enum member."""
-
-    def __init__(self, name: str):
-        self.name = name
+def _key(data_type: str, server: str = "srv", **params) -> CacheKey:
+    """The typed key SDS hands its listeners on every cache write."""
+    return CacheKey.make(server, ServerDataType[data_type], **params)
 
 
 def _manager_with_subscriber(channel: str) -> tuple[WebSocketManager, _FakeWS]:
@@ -54,9 +53,7 @@ def test_sds_update_holds_a_strong_reference_until_the_broadcast_finishes():
     manager, ws = _manager_with_subscriber("portfolio:srv")
 
     async def scenario():
-        manager._on_data_update(
-            "srv", "portfolio", _FakeDataType("PORTFOLIO"), {"total": 1}
-        )
+        manager._on_data_update(_key("PORTFOLIO"), {"total": 1})
         assert len(manager._oneshot_tasks) == 1, "broadcast task was not tracked"
         name = next(iter(manager._oneshot_tasks)).get_name()
         await _drain(manager)
@@ -72,9 +69,7 @@ def test_reference_is_released_across_repeated_polls():
 
     async def scenario():
         for i in range(5):
-            manager._on_data_update(
-                "srv", "portfolio", _FakeDataType("PORTFOLIO"), {"total": i}
-            )
+            manager._on_data_update(_key("PORTFOLIO"), {"total": i})
             await _drain(manager)
 
     asyncio.run(scenario())
@@ -93,7 +88,7 @@ async def boom(channel, data):
     manager._broadcast_update = boom
 
     async def scenario():
-        manager._on_data_update("srv", "bots", _FakeDataType("BOTS_STATUS"), {})
+        manager._on_data_update(_key("BOTS_STATUS"), {})
         await _drain(manager)
 
     with caplog.at_level(logging.ERROR, logger=WS_LOGGER):
@@ -119,7 +114,7 @@ async def never_finishes(channel, data):
     manager._broadcast_update = never_finishes
 
     async def scenario():
-        manager._on_data_update("srv", "portfolio", _FakeDataType("PORTFOLIO"), {})
+        manager._on_data_update(_key("PORTFOLIO"), {})
         await started.wait()
         task = next(iter(manager._oneshot_tasks))
         task.cancel()

From 5199efb13fdcc6fb0f70aac7ff6498ed278bcb38 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Fri, 14 Aug 2026 15:42:33 +0300
Subject: [PATCH 072/116] (perf) PERF-138: replay reads the transcript's tail,
 not the whole file
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

replay_context ran read_transcript(limit=0) on the session-spawn path: every
line of an append-only, never-truncated transcript.jsonl was json-parsed and
pydantic-validated just to render a ~6KB tail, so first-token latency grew
with the conversation's whole history.

Read backwards instead. _iter_lines_reverse walks the file in 64KB blocks
from the end and _iter_turns_reverse parses lazily, so the budget walk stops
at the turn that overruns the bound. read_transcript's bounded tail shares
it, which also takes the /conversations route's limit=200 off the full parse;
limit=0 still walks the file.

The output is unchanged by construction — same sequence, same walk, same
tolerance for a malformed line — and a test pins that against the previous
full-parse algorithm across empty, torn, malformed, empty-rendering and
300-turn transcripts at five budgets. Complexity is pinned by counting
TurnEntry constructions: 10k turns, 1000-char tail, 10000 parses before, 5
after.
---
 condor/runtime/conversations.py     |  82 ++++++++++-
 tests/runtime/test_conversations.py | 209 ++++++++++++++++++++++++++++
 2 files changed, 286 insertions(+), 5 deletions(-)

diff --git a/condor/runtime/conversations.py b/condor/runtime/conversations.py
index a6621b7d..93d6a561 100644
--- a/condor/runtime/conversations.py
+++ b/condor/runtime/conversations.py
@@ -32,7 +32,9 @@
 import shutil
 import time
 import uuid
+from collections.abc import Iterator
 from datetime import datetime, timezone
+from itertools import chain, islice
 from pathlib import Path
 
 from pydantic import BaseModel, ConfigDict, Field
@@ -59,6 +61,11 @@
 REPLAY_HEADER = "Previously in this chat:"
 REPLAY_OMITTED = "(older turns omitted)"
 
+# Bytes pulled per backwards read of a transcript. One block already covers a
+# replay's whole char budget many times over; it only ever grows when a single
+# turn is bigger than this.
+_TAIL_BLOCK_BYTES = 64 * 1024
+
 TITLE_MAX_CHARS = 80
 SNIPPET_MAX_CHARS = 160
 
@@ -343,13 +350,71 @@ def list_conversations(user_id: int, *, limit: int = 100) -> list[ConversationMe
     return metas[:limit] if limit else metas
 
 
+def _iter_lines_reverse(path: Path, *, block: int | None = None) -> Iterator[bytes]:
+    """The file's non-blank lines, newest first, reading only what is consumed.
+
+    Opened in binary and split on ``b"\\n"``: no UTF-8 continuation byte is
+    ``0x0A``, so a block boundary can cut a character in half but never a line.
+    A record is always one line — ``append_turn`` writes ``json.dumps`` output,
+    which escapes newlines — so a line is a whole turn, and the last one is
+    yielded whether or not it ends in a newline (a torn append reads as a
+    malformed line, exactly as it does on the forward path).
+    """
+    size = block or _TAIL_BLOCK_BYTES
+    with path.open("rb") as fh:
+        fh.seek(0, os.SEEK_END)
+        pos = fh.tell()
+        carry = b""
+        while pos > 0:
+            step = min(size, pos)
+            pos -= step
+            fh.seek(pos)
+            lines = (fh.read(step) + carry).split(b"\n")
+            # The first piece may continue into the block before this one.
+            carry = lines.pop(0)
+            for line in reversed(lines):
+                line = line.strip()
+                if line:
+                    yield line
+        carry = carry.strip()
+        if carry:
+            yield carry
+
+
+def _iter_turns_reverse(path: Path) -> Iterator[TurnEntry]:
+    """Parsed turns, newest first, parsing only the lines the caller pulls.
+
+    Same tolerance as the forward read: a line that will not parse is skipped,
+    an unreadable file is empty rather than fatal.
+    """
+    try:
+        if not path.is_file():
+            return
+        for line in _iter_lines_reverse(path):
+            try:
+                yield TurnEntry(**json.loads(line.decode("utf-8")))
+            except Exception:  # noqa: BLE001 - one bad line is not the file
+                continue
+    except OSError:
+        log.debug("Unreadable transcript at %s", path, exc_info=True)
+
+
 def read_transcript(user_id: int, conv_id: str, *, limit: int = 200) -> list[TurnEntry]:
     """The tail of a transcript. ``limit=0`` means all of it.
 
     A line that fails to parse is skipped, never fatal — the same tolerance
     ``read_status()`` shows for a truncated status file.
+
+    A bounded tail is read backwards from the end, so a conversation with
+    thousands of turns costs its tail rather than its whole history; only
+    ``limit=0`` still walks the file.
     """
     path = _conv_dir(user_id, conv_id) / TRANSCRIPT_FILENAME
+    if limit:
+        tail = list(islice(_iter_turns_reverse(path), limit))
+        tail.reverse()
+        return tail
+
     entries: list[TurnEntry] = []
     try:
         if not path.is_file():
@@ -366,7 +431,7 @@ def read_transcript(user_id: int, conv_id: str, *, limit: int = 200) -> list[Tur
     except OSError:
         log.debug("Unreadable transcript at %s", path, exc_info=True)
         return []
-    return entries[-limit:] if limit else entries
+    return entries
 
 
 def append_turn(user_id: int, conv_id: str, entry: TurnEntry) -> None:
@@ -462,9 +527,14 @@ def replay_context(
 
     Walks backwards from the newest turn so the most recent ones always survive
     the bound, then reverses. The returned string never exceeds ``max_chars``.
+
+    The walk reads the transcript backwards and parses lazily, so it stops at
+    the turn that overruns the budget instead of parsing the whole file first:
+    this runs on the session-spawn path, and the transcript is append-only.
     """
-    turns = read_transcript(user_id, conv_id, limit=0)
-    if not turns:
+    turns = _iter_turns_reverse(_conv_dir(user_id, conv_id) / TRANSCRIPT_FILENAME)
+    newest_turn = next(turns, None)
+    if newest_turn is None:
         return ""
 
     # Budget the body so header and footer fit inside the caller's bound.
@@ -476,10 +546,13 @@ def replay_context(
     lines: list[str] = []
     used = 0
     omitted = False
-    for turn in reversed(turns):
+    newest = ""
+    for turn in chain([newest_turn], turns):
         rendered = _render_turn(turn)
         if not rendered:
             continue
+        if not newest:
+            newest = rendered
         if used + len(rendered) + 1 > budget:
             omitted = True
             break
@@ -489,7 +562,6 @@ def replay_context(
     if not lines:
         # Even the newest turn alone overruns the budget. Keeping a truncated
         # head of it beats returning nothing at all.
-        newest = next((r for r in (_render_turn(t) for t in reversed(turns)) if r), "")
         if not newest:
             return ""
         lines = [newest[:budget]]
diff --git a/tests/runtime/test_conversations.py b/tests/runtime/test_conversations.py
index a747902b..8dfbc830 100644
--- a/tests/runtime/test_conversations.py
+++ b/tests/runtime/test_conversations.py
@@ -15,16 +15,20 @@
 from condor.acp.client import PromptDone, TextChunk
 from condor.runtime import PromptRequest, SessionKey, SessionSpec
 from condor.runtime import client as runtime
+from condor.runtime import conversations
 from condor.runtime import sessions as session_module
 from condor.runtime.conversations import (
     REDACTED,
     REPLAY_HEADER,
+    REPLAY_MAX_CHARS,
     REPLAY_OMITTED,
     TOOL_INPUT_MAX_CHARS,
     TOOL_OUTPUT_MAX_CHARS,
     ConversationIdError,
     Recorder,
     TurnEntry,
+    _iter_lines_reverse,
+    _render_turn,
     _root,
     append_turn,
     delete_conversation,
@@ -962,3 +966,208 @@ async def scenario():
         return str(exc.value)
 
     assert "busy" in asyncio.run(scenario())
+
+
+# ── Bounded tail reads (PERF-138) ──
+
+
+def _replay_by_full_parse(user_id, conv_id, *, max_chars=None):
+    """The pre-PERF-138 replay: parse the whole file, then walk it backwards.
+
+    Kept verbatim as the oracle for the bounded reader — the point of the
+    change was cost, not output, so the two must agree line for line.
+    """
+    max_chars = REPLAY_MAX_CHARS if max_chars is None else max_chars
+    turns = read_transcript(user_id, conv_id, limit=0)
+    if not turns:
+        return ""
+    overhead = len(REPLAY_HEADER) + 1 + len(REPLAY_OMITTED) + 1
+    budget = max_chars - overhead
+    if budget <= 0:
+        return REPLAY_HEADER[:max_chars]
+
+    lines, used, omitted = [], 0, False
+    for turn in reversed(turns):
+        rendered = _render_turn(turn)
+        if not rendered:
+            continue
+        if used + len(rendered) + 1 > budget:
+            omitted = True
+            break
+        lines.append(rendered)
+        used += len(rendered) + 1
+
+    if not lines:
+        newest = next((r for r in (_render_turn(t) for t in reversed(turns)) if r), "")
+        if not newest:
+            return ""
+        lines = [newest[:budget]]
+        omitted = True
+
+    lines.reverse()
+    parts = [REPLAY_HEADER, *lines]
+    if omitted:
+        parts.append(REPLAY_OMITTED)
+    return "\n".join(parts)[:max_chars]
+
+
+def _write_raw_transcript(conv_root, conv_id, lines):
+    """Write transcript lines straight to disk, bypassing ``append_turn``."""
+    path = conv_root / str(USER) / conv_id / "transcript.jsonl"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text("".join(lines), encoding="utf-8")
+    return path
+
+
+def _turn_line(**fields):
+    return json.dumps(TurnEntry(**fields).model_dump(mode="json")) + "\n"
+
+
+def test_reverse_line_reader_matches_a_forward_read(conv_root):
+    """Backwards blocks yield exactly the forward lines, reversed.
+
+    Tiny blocks on purpose: every line here straddles a block boundary, which
+    is the only way the reader can lose or splice one.
+    """
+    meta = new_conversation(USER, WEB)
+    raw = ["one\n", "two\n", "\n", "three " + "x" * 500 + "\n", "four"]
+    path = _write_raw_transcript(conv_root, meta.id, raw)
+
+    forward = [line.strip() for line in path.read_bytes().split(b"\n") if line.strip()]
+    for block in (1, 7, 64, 4096):
+        assert (
+            list(_iter_lines_reverse(path, block=block)) == forward[::-1]
+        ), f"block={block} changed the line sequence"
+
+
+def test_replay_matches_the_full_parse_on_every_transcript_shape(conv_root):
+    """Same records, same order, same truncation boundary as the old path."""
+    shapes = {
+        "empty file": [],
+        "one turn": [_turn_line(role="user", text="hi")],
+        "short": [
+            _turn_line(role="user", text="what is my pnl?"),
+            _turn_line(role="assistant", text="Up $120."),
+        ],
+        "empty renders interleaved": [
+            _turn_line(role="assistant", text="", tool_calls=[]),
+            _turn_line(role="user", text="hello"),
+            _turn_line(role="system", text=""),
+            _turn_line(role="assistant", text="", tool_calls=[]),
+        ],
+        "malformed lines inside the tail": [
+            _turn_line(role="user", text="kept"),
+            "{not json at all\n",
+            _turn_line(role="assistant", text="also kept"),
+            '{"role": 12345}\n',
+        ],
+        "no trailing newline": [_turn_line(role="user", text="torn").rstrip("\n")],
+        "torn last line": [
+            _turn_line(role="user", text="whole"),
+            '{"role": "assistant", "text": "half a li',
+        ],
+        "long": [
+            _turn_line(role="user", text=f"message number {i} " + "x" * 100)
+            for i in range(300)
+        ],
+        "long with tool calls": [
+            _turn_line(
+                role="assistant",
+                text=f"turn {i}",
+                tool_calls=[{"id": f"t{i}", "title": "get_market_data"}],
+            )
+            for i in range(300)
+        ],
+        "one turn far over the bound": [_turn_line(role="user", text="y" * 5000)],
+    }
+
+    for name, raw in shapes.items():
+        meta = new_conversation(USER, WEB)
+        _write_raw_transcript(conv_root, meta.id, raw)
+        for max_chars in (10, 40, 200, 1000, REPLAY_MAX_CHARS):
+            assert replay_context(USER, meta.id, max_chars=max_chars) == (
+                _replay_by_full_parse(USER, meta.id, max_chars=max_chars)
+            ), f"{name} diverged from the full parse at max_chars={max_chars}"
+
+
+def _count_parsed_turns(monkeypatch):
+    """Count every ``TurnEntry`` the store builds while reading."""
+    real = conversations.TurnEntry
+    counter = {"n": 0}
+
+    def counting(**fields):
+        counter["n"] += 1
+        return real(**fields)
+
+    monkeypatch.setattr(conversations, "TurnEntry", counting)
+    return counter
+
+
+def test_replay_parses_a_bounded_tail_not_the_whole_transcript(conv_root, monkeypatch):
+    """The complexity pin: replay cost follows its char budget, not the file.
+
+    10k turns, ~200 chars each — the old path built 10k ``TurnEntry`` objects
+    to render a 1000-char tail. The bound here is the budget itself: no more
+    turns can be parsed than can fit in it, plus the one that overruns it.
+    """
+    meta = new_conversation(USER, WEB)
+    _write_raw_transcript(
+        conv_root,
+        meta.id,
+        [
+            _turn_line(role="user", text=f"message number {i} " + "x" * 200)
+            for i in range(10_000)
+        ],
+    )
+
+    counter = _count_parsed_turns(monkeypatch)
+    replay = replay_context(USER, meta.id, max_chars=1000)
+
+    assert "message number 9999" in replay
+    assert REPLAY_OMITTED in replay
+    assert counter["n"] <= 1000 // 200 + 2, (
+        "replay parsed more turns than its char budget can hold: "
+        f"{counter['n']} for a 1000-char tail of a 10k-turn transcript"
+    )
+
+
+def test_read_transcript_tail_parses_only_the_tail(conv_root, monkeypatch):
+    """The web route's ``limit=200`` over 10k turns parses 200, not 10k."""
+    meta = new_conversation(USER, WEB)
+    _write_raw_transcript(
+        conv_root,
+        meta.id,
+        [_turn_line(role="user", text=f"m{i}") for i in range(10_000)],
+    )
+
+    counter = _count_parsed_turns(monkeypatch)
+    tail = read_transcript(USER, meta.id, limit=200)
+
+    assert [t.text for t in tail] == [f"m{i}" for i in range(9800, 10_000)]
+    assert counter["n"] == 200, "a bounded read must not touch the older turns"
+
+
+def test_read_transcript_tail_skips_malformed_lines_like_the_full_read(conv_root):
+    """Tolerance is unchanged: a bad line costs its own slot, not the read."""
+    meta = new_conversation(USER, WEB)
+    _write_raw_transcript(
+        conv_root,
+        meta.id,
+        [
+            _turn_line(role="user", text="oldest"),
+            "not json\n",
+            _turn_line(role="assistant", text="middle"),
+            '{"role": "user", "text": {"bad": "type"}}\n',
+            _turn_line(role="user", text="newest"),
+        ],
+    )
+
+    assert [t.text for t in read_transcript(USER, meta.id, limit=2)] == [
+        "middle",
+        "newest",
+    ]
+    assert [t.text for t in read_transcript(USER, meta.id, limit=0)] == [
+        "oldest",
+        "middle",
+        "newest",
+    ]

From 010c926179f2a0ee47ff0adf7935392aec2a8500 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Fri, 14 Aug 2026 15:55:18 +0300
Subject: [PATCH 073/116] (refactor) SEC-147: the server-access check is a
 dependency, not 89 copies
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The 403 preamble `cm = get_config_manager(); if not
cm.has_server_access(user.id, name): raise HTTPException(403, "No access")`
was hand-copied into 89 endpoints across 15 route modules, which made access
control opt-in per endpoint. SEC-007, SEC-019 and SEC-045 were each a patch
for one endpoint that simply forgot to type it.

condor/web/auth.py now owns the single implementation, `check_server_access`,
plus three dependencies over it — one per parameter shape, because the sites
are not uniform and forcing one mechanism onto all of them would half-convert
some of them:

  require_server_access                  {name} path param        55 sites
  require_server_access_query            ?server= query param     19 sites
  require_server_access_by_server_name   {server_name} path param  2 sites
  check_server_access (called directly)  name in the body          9 sites

The body sites keep an explicit call: a path/query dependency cannot see a
request body. Their conditional shapes are preserved verbatim — consult,
delegate and the agent config pin only gate when a server was actually asked
for, sessions gates on the session owner's id, and the SEC-149 gate in
agents._start keeps its surrounding condition.

Levels are unchanged. Every one of the 89 calls used the two-arg form, i.e.
the TRADER default, so the dependency is behaviour-preserving; the stronger
checks layered on top of it stay layered — `_require_owner` on credential
add/delete (SEC-153) and on update/delete server, and the routine instance
ownership gate (SEC-150).

Four routes deliberately keep an inline check: /servers/{name}/status and
settings' update/delete/set-default answer 404 "Server not found" rather than
403, so a caller cannot tell a server they may not touch from one that does
not exist. They are on a reviewed allowlist in the new test.

tests/test_web_server_access_dependency.py makes the regression structural
rather than per-endpoint: it walks the real app and fails if any server-scoped
route lacks the dependency, if a guard's parameter does not match its route
(the half-conversion case, which fails closed with a 422), or if a body site
drops the helper. Verified by mutation: removing a dependency, mismatching a
parameter, and deleting a helper call each turn it red.

Tests that stubbed `get_config_manager` on a route module now stub it where
the guard lives; three that asserted the guard by calling an endpoint function
directly assert it on the dependency, which is what actually runs first.

Found but not fixed here: GET /routines/options/{source} reads any server's
controller configs with no check at all. Filed as SEC-159 and named in the
test's KNOWN_GAPS, since fixing it is a behaviour change, not a refactor.
---
 condor/web/auth.py                          |  55 +++-
 condor/web/routes/agents.py                 |  23 +-
 condor/web/routes/archived.py               |  14 +-
 condor/web/routes/backtesting.py            |  28 +-
 condor/web/routes/bots.py                   |  70 ++---
 condor/web/routes/code.py                   |   6 +-
 condor/web/routes/controller_performance.py |  20 +-
 condor/web/routes/dex.py                    |  29 +-
 condor/web/routes/executors.py              |  30 +-
 condor/web/routes/market.py                 |  52 +---
 condor/web/routes/portfolio.py              |  11 +-
 condor/web/routes/positions.py              |   8 +-
 condor/web/routes/routines.py               |  28 +-
 condor/web/routes/sessions.py               |   8 +-
 condor/web/routes/settings.py               |  79 ++----
 tests/test_agent_server_pin.py              |   5 +
 tests/test_agent_start_server_access.py     |   5 +
 tests/test_agents.py                        |   6 +-
 tests/test_code_run_tool.py                 |  11 +-
 tests/test_dex_liquidity_bins_route.py      |   1 +
 tests/test_dex_pool_discovery.py            |  74 ++++-
 tests/test_dex_pool_resolution.py           |  16 +-
 tests/test_executors_period_summary.py      |  20 +-
 tests/test_fetcher_identifier_validation.py |   3 +
 tests/test_fetcher_venues.py                |  12 +-
 tests/test_routines_access.py               |   1 +
 tests/test_session_model_switch.py          |   1 +
 tests/test_session_server_switch.py         |   3 +
 tests/test_web_credentials_owner_only.py    |   1 +
 tests/test_web_server_access_dependency.py  | 292 ++++++++++++++++++++
 30 files changed, 602 insertions(+), 310 deletions(-)
 create mode 100644 tests/test_web_server_access_dependency.py

diff --git a/condor/web/auth.py b/condor/web/auth.py
index 774ae85e..e2986ee0 100644
--- a/condor/web/auth.py
+++ b/condor/web/auth.py
@@ -8,7 +8,7 @@
 import time
 from typing import Optional
 
-from fastapi import Depends, HTTPException, WebSocket, status
+from fastapi import Depends, HTTPException, Query, WebSocket, status
 from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
 from jose import JWTError, jwt
 
@@ -154,6 +154,59 @@ async def get_current_user(
     )
 
 
+# ── Server-scoped access (SEC-147) ──
+
+
+def check_server_access(user_id: int, server_name: str) -> None:
+    """Raise ``403 No access`` unless ``user_id`` may use ``server_name``.
+
+    Single implementation of the guard that used to be hand-copied into every
+    server-scoped web endpoint. ``has_server_access`` defaults to
+    :attr:`ServerPermission.TRADER`, which is the level every web call already
+    required. Endpoints that need a *stronger* level (owner-only credential and
+    server mutations in ``routes/settings.py``) still layer their own check on
+    top of this one — this is the floor, never the ceiling.
+
+    Endpoints whose server name arrives in the request **body** call this
+    directly (a path/query dependency cannot see the body); endpoints that take
+    it as a path or query parameter use the ``require_server_access*``
+    dependencies below, which are thin wrappers over this function.
+    """
+    if not get_config_manager().has_server_access(user_id, server_name):
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="No access")
+
+
+async def require_server_access(
+    name: str, user: WebUser = Depends(get_current_user)
+) -> WebUser:
+    """Auth dependency for endpoints routed under ``/servers/{name}/...``.
+
+    Drop-in replacement for ``Depends(get_current_user)``: it returns the same
+    :class:`WebUser`, having first enforced access to the ``{name}`` path
+    parameter. If the route has no ``{name}`` path parameter FastAPI treats it
+    as a required *query* parameter and the request fails with 422 — the guard
+    fails closed, never open.
+    """
+    check_server_access(user.id, name)
+    return user
+
+
+async def require_server_access_by_server_name(
+    server_name: str, user: WebUser = Depends(get_current_user)
+) -> WebUser:
+    """Same as :func:`require_server_access` for a ``{server_name}`` path param."""
+    check_server_access(user.id, server_name)
+    return user
+
+
+async def require_server_access_query(
+    server: str = Query(...), user: WebUser = Depends(get_current_user)
+) -> WebUser:
+    """Same as :func:`require_server_access` for a ``?server=`` query param."""
+    check_server_access(user.id, server)
+    return user
+
+
 # ── One-time login tokens (generated from Telegram /web command) ──
 
 
diff --git a/condor/web/routes/agents.py b/condor/web/routes/agents.py
index 46b0ffb1..f7dbbbce 100644
--- a/condor/web/routes/agents.py
+++ b/condor/web/routes/agents.py
@@ -39,7 +39,7 @@
     list_session_snapshots,
     list_sessions,
 )
-from condor.web.auth import get_current_user
+from condor.web.auth import check_server_access, get_current_user
 from condor.web.models import ReportSummary, WebUser
 
 # ── Simple in-memory TTL cache for performance data ──
@@ -1168,10 +1168,8 @@ async def update_agent_config(
     # A pin decides which account the Agent's tools trade on, so it is gated
     # like every other server-scoped write. An empty string clears the pin and
     # needs no access at all.
-    if req.server_name and not get_config_manager().has_server_access(
-        user.id, req.server_name
-    ):
-        raise HTTPException(status_code=403, detail="No access")
+    if req.server_name:
+        check_server_access(user.id, req.server_name)
 
     # Picker sentinels ("openrouter:", "custom:") are drill-downs that open a
     # model list, not startable models: stored here they would fail at every
@@ -1228,10 +1226,8 @@ async def consult_agent(
     # routes do — otherwise any session could consult against a server it was
     # never granted (IDOR). Only enforce when a server is actually requested;
     # serverless consults need no server scope.
-    if req.server_name and not get_config_manager().has_server_access(
-        user.id, req.server_name
-    ):
-        raise HTTPException(status_code=403, detail="No access")
+    if req.server_name:
+        check_server_access(user.id, req.server_name)
 
     # Web callers always act as themselves; the ``user_id`` override is reserved
     # for trusted internal/MCP callers and must not let a session impersonate
@@ -1288,10 +1284,8 @@ async def delegate_agent(
 
     # Same server-scope gate as consult: a delegate binds the agent's MCP toolset
     # to ``server_name``'s live credentials, so refuse a server the caller can't access.
-    if req.server_name and not get_config_manager().has_server_access(
-        user.id, req.server_name
-    ):
-        raise HTTPException(status_code=403, detail="No access")
+    if req.server_name:
+        check_server_access(user.id, req.server_name)
 
     conversation_id = await _conversation_for_session(req.session_key)
 
@@ -1757,8 +1751,7 @@ async def _start(agent, strategy, req: StartStrategyRequest, user_id: int) -> di
     server_name = config_dict.get("server_name")
     asked_for_it = bool(req.config and req.config.get("server_name"))
     if server_name and (asked_for_it or cm.get_server(server_name)):
-        if not cm.has_server_access(user_id, server_name):
-            raise HTTPException(status_code=403, detail="No access")
+        check_server_access(user_id, server_name)
 
     if req.trading_context:
         config_dict["trading_context"] = req.trading_context
diff --git a/condor/web/routes/archived.py b/condor/web/routes/archived.py
index 5264a59f..d65539fa 100644
--- a/condor/web/routes/archived.py
+++ b/condor/web/routes/archived.py
@@ -8,7 +8,7 @@
 from fastapi import APIRouter, Depends, HTTPException, Query
 
 from condor.fetchers.executors import normalize_executor_side
-from condor.web.auth import get_current_user
+from condor.web.auth import require_server_access
 from condor.web.models import (
     ArchivedBotPerformance,
     ArchivedBotSummary,
@@ -309,10 +309,8 @@ async def _fetch_and_cache_performance(
 
 
 @router.get("/servers/{name}/archived")
-async def list_archived_bots(name: str, user: WebUser = Depends(get_current_user)):
+async def list_archived_bots(name: str, user: WebUser = Depends(require_server_access)):
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     client = await cm.get_client(name)
 
@@ -357,11 +355,9 @@ async def get_archived_performance(
     include_executors: bool = Query(
         False, description="Include full executor list in response"
     ),
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access),
 ):
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     client = await cm.get_client(name)
 
@@ -380,11 +376,9 @@ async def get_archived_executors(
     db_path: str = Query(..., description="Database path"),
     offset: int = Query(0, ge=0),
     limit: int = Query(50, ge=1, le=200),
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access),
 ):
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     cache_key = (name, db_path)
 
diff --git a/condor/web/routes/backtesting.py b/condor/web/routes/backtesting.py
index d43d82d4..ff35163f 100644
--- a/condor/web/routes/backtesting.py
+++ b/condor/web/routes/backtesting.py
@@ -7,7 +7,7 @@
 
 from condor.backtest_store import get_backtest_store
 from condor.backtesting import coerce_controller_config, normalize_backtest_task
-from condor.web.auth import get_current_user
+from condor.web.auth import require_server_access
 from condor.web.models import WebUser
 from config_manager import get_config_manager
 
@@ -28,11 +28,9 @@ class SubmitBacktestRequest(BaseModel):
 async def submit_backtest_task(
     name: str,
     body: SubmitBacktestRequest,
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access),
 ):
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     client = await cm.get_client(name)
 
@@ -56,11 +54,9 @@ async def submit_backtest_task(
 @router.get("/servers/{name}/backtesting/tasks")
 async def list_backtest_tasks(
     name: str,
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access),
 ):
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     store = get_backtest_store()
 
@@ -105,11 +101,9 @@ async def list_backtest_tasks(
 async def get_backtest_task(
     name: str,
     task_id: str,
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access),
 ):
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     store = get_backtest_store()
 
@@ -139,11 +133,9 @@ async def get_backtest_task(
 async def delete_backtest_task(
     name: str,
     task_id: str,
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access),
 ):
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     store = get_backtest_store()
     store.delete_result(task_id)
@@ -162,11 +154,8 @@ async def delete_backtest_task(
 @router.get("/servers/{name}/backtesting/saved")
 async def list_saved_results(
     name: str,
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access),
 ):
-    cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     store = get_backtest_store()
     return [normalize_backtest_task(entry) for entry in store.list_results(name)]
@@ -176,11 +165,8 @@ async def list_saved_results(
 async def delete_saved_result(
     name: str,
     task_id: str,
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access),
 ):
-    cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     store = get_backtest_store()
     deleted = store.delete_result(task_id)
diff --git a/condor/web/routes/bots.py b/condor/web/routes/bots.py
index 17b27b1c..996f64b5 100644
--- a/condor/web/routes/bots.py
+++ b/condor/web/routes/bots.py
@@ -9,7 +9,7 @@
 from fastapi import APIRouter, Depends, HTTPException
 
 from condor.fetchers.bots import build_bots_page, extract_bots_list
-from condor.web.auth import get_current_user
+from condor.web.auth import require_server_access
 from condor.web.models import (
     AvailableControllersResponse,
     BotDetailResponse,
@@ -232,10 +232,8 @@ def _collect_bot_runs(result: Any, runs: dict[str, str]) -> None:
 
 
 @router.get("/servers/{name}/bots", response_model=BotsPageResponse)
-async def list_bots(name: str, user: WebUser = Depends(get_current_user)):
+async def list_bots(name: str, user: WebUser = Depends(require_server_access)):
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     from condor.server_data_service import ServerDataType, get_server_data_service
 
@@ -394,10 +392,10 @@ async def _with_timeout(coro, label: str, default: Any) -> Any:
 
 
 @router.get("/servers/{name}/bots/{bot_id}")
-async def get_bot(name: str, bot_id: str, user: WebUser = Depends(get_current_user)):
+async def get_bot(
+    name: str, bot_id: str, user: WebUser = Depends(require_server_access)
+):
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     import asyncio
 
@@ -448,10 +446,10 @@ async def get_bot(name: str, bot_id: str, user: WebUser = Depends(get_current_us
     "/servers/{name}/controllers/configs",
     response_model=AvailableControllersResponse,
 )
-async def list_controller_configs(name: str, user: WebUser = Depends(get_current_user)):
+async def list_controller_configs(
+    name: str, user: WebUser = Depends(require_server_access)
+):
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     import asyncio
 
@@ -503,11 +501,9 @@ async def _get_configs():
     response_model=ControllerConfigDetail,
 )
 async def get_controller_config(
-    name: str, config_id: str, user: WebUser = Depends(get_current_user)
+    name: str, config_id: str, user: WebUser = Depends(require_server_access)
 ):
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     client = await cm.get_client(name)
     try:
@@ -534,7 +530,7 @@ async def update_controller_config(
     name: str,
     config_id: str,
     body: dict[str, Any],
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access),
 ):
     """Update a saved controller config's parameters.
 
@@ -543,8 +539,6 @@ async def update_controller_config(
       - { ... } (raw dict) — existing behavior preserved
     """
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     client = await cm.get_client(name)
 
@@ -605,12 +599,10 @@ async def get_controller_source(
     name: str,
     controller_type: str,
     controller_name: str,
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access),
 ):
     """Fetch the Python source of a controller."""
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     client = await cm.get_client(name)
     try:
@@ -653,12 +645,10 @@ async def update_controller_source(
     controller_type: str,
     controller_name: str,
     body: dict[str, Any],
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access),
 ):
     """Update the Python source of a controller."""
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     source = body.get("source")
     if not source or not isinstance(source, str):
@@ -688,12 +678,10 @@ async def get_controller_config_template(
     name: str,
     controller_type: str,
     controller_name: str,
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access),
 ):
     """Fetch the config template/schema for a controller."""
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     client = await cm.get_client(name)
     try:
@@ -722,12 +710,10 @@ async def get_controller_config_template(
 async def create_controller_config(
     name: str,
     body: dict[str, Any],
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access),
 ):
     """Create or update a controller config."""
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     config_id = body.get("id")
     if not config_id:
@@ -768,12 +754,10 @@ async def create_controller_config(
 async def delete_controller_config(
     name: str,
     config_id: str,
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access),
 ):
     """Delete a saved controller config."""
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     client = await cm.get_client(name)
     try:
@@ -792,12 +776,10 @@ async def delete_controller(
     name: str,
     controller_type: str,
     controller_name: str,
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access),
 ):
     """Delete a controller."""
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     client = await cm.get_client(name)
     try:
@@ -823,11 +805,9 @@ async def delete_controller(
 
 @router.post("/servers/{name}/bots/deploy")
 async def deploy_bot_endpoint(
-    name: str, body: DeployBotRequest, user: WebUser = Depends(get_current_user)
+    name: str, body: DeployBotRequest, user: WebUser = Depends(require_server_access)
 ):
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     client = await cm.get_client(name)
 
@@ -852,11 +832,9 @@ async def deploy_bot_endpoint(
 
 @router.post("/servers/{name}/bots/{bot_name}/stop")
 async def stop_bot_endpoint(
-    name: str, bot_name: str, user: WebUser = Depends(get_current_user)
+    name: str, bot_name: str, user: WebUser = Depends(require_server_access)
 ):
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     # Mark as stopping immediately so UI reflects it
     mark_bot_stopping(name, bot_name)
@@ -884,11 +862,9 @@ async def stop_controllers_endpoint(
     name: str,
     bot_name: str,
     body: ControllerActionRequest,
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access),
 ):
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     # Mark controllers as stopping immediately
     mark_controllers_stopping(name, bot_name, body.controller_names)
@@ -918,11 +894,9 @@ async def start_controllers_endpoint(
     name: str,
     bot_name: str,
     body: ControllerActionRequest,
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access),
 ):
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     client = await cm.get_client(name)
 
@@ -950,12 +924,10 @@ async def update_bot_controller_config_endpoint(
     bot_name: str,
     config_id: str,
     body: dict[str, Any],
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access),
 ):
     """Update a controller config inside a running bot in real-time."""
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     client = await cm.get_client(name)
 
diff --git a/condor/web/routes/code.py b/condor/web/routes/code.py
index 2ef24c65..cde8ded4 100644
--- a/condor/web/routes/code.py
+++ b/condor/web/routes/code.py
@@ -23,7 +23,7 @@
 from pydantic import BaseModel
 
 from condor.code_runner import DEFAULT_TIMEOUT, MAX_TIMEOUT, execute_code
-from condor.web.auth import get_current_user
+from condor.web.auth import check_server_access, get_current_user
 from condor.web.models import WebUser
 from config_manager import get_config_manager
 
@@ -81,9 +81,7 @@ async def run_code(
     if not body.code.strip():
         raise HTTPException(400, "code is required")
     if body.server_name:
-        cm = get_config_manager()
-        if not cm.has_server_access(user.id, body.server_name):
-            raise HTTPException(status_code=403, detail="No access")
+        check_server_access(user.id, body.server_name)
 
     return await execute_code(
         body.code,
diff --git a/condor/web/routes/controller_performance.py b/condor/web/routes/controller_performance.py
index eaee3ea9..7dd86a51 100644
--- a/condor/web/routes/controller_performance.py
+++ b/condor/web/routes/controller_performance.py
@@ -3,11 +3,11 @@
 import logging
 from typing import Optional
 
-from fastapi import APIRouter, Depends, HTTPException, Query
+from fastapi import APIRouter, Depends, Query
 
 from condor.fetchers.bot_performance import extract_snapshots as _extract_snapshots
 from condor.fetchers.bot_performance import fetch_all_bot_performance
-from condor.web.auth import get_current_user
+from condor.web.auth import require_server_access
 from condor.web.models import (
     BotRunInfo,
     BotRunsResponse,
@@ -101,14 +101,12 @@ async def get_bot_runs(
     deployment_status: Optional[str] = Query(None),
     limit: int = Query(100, ge=1, le=500),
     offset: int = Query(0, ge=0),
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access),
 ):
     """Get bot runs with optional filtering."""
     import asyncio
 
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     client = await cm.get_client(name)
 
@@ -154,12 +152,10 @@ async def _fetch_perf() -> dict[str, dict]:
 async def delete_bot_run(
     name: str,
     bot_run_id: int,
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access),
 ):
     """Delete an archived bot run by its numeric ID."""
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     client = await cm.get_client(name)
 
@@ -198,12 +194,10 @@ def _extract_runs_list(result) -> list[dict]:
 async def get_latest_controller_performance(
     name: str,
     bot_name: Optional[str] = Query(None),
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access),
 ):
     """Get the most recent performance snapshot for each bot/controller."""
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     client = await cm.get_client(name)
 
@@ -243,12 +237,10 @@ async def get_controller_performance_history(
     interval: str = Query("5m"),
     limit: Optional[int] = Query(None, ge=1, le=5000),
     cursor: Optional[str] = Query(None),
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access),
 ):
     """Get historical controller performance with pagination and interval sampling."""
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     client = await cm.get_client(name)
 
diff --git a/condor/web/routes/dex.py b/condor/web/routes/dex.py
index ccaadc04..afe96458 100644
--- a/condor/web/routes/dex.py
+++ b/condor/web/routes/dex.py
@@ -18,7 +18,7 @@
 from fastapi import APIRouter, Depends, HTTPException, Query
 
 from condor import dex_candles
-from condor.web.auth import get_current_user
+from condor.web.auth import require_server_access
 from condor.web.models import WebUser
 from config_manager import get_config_manager
 
@@ -93,7 +93,7 @@ async def list_pools(
     ),
     limit: int = Query(default=20, ge=1, le=100),
     page: int = Query(default=1, ge=1, description="1-based page of `limit` rows"),
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access),
 ):
     """Pools to browse, from one of the two upstreams.
 
@@ -110,8 +110,6 @@ async def list_pools(
     something neither upstream reports.
     """
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     from handlers.dex.pool_data import list_gateway_pools, list_gecko_pools_page
 
@@ -163,7 +161,7 @@ async def list_pools(
 async def list_dexes(
     name: str,
     network: str = Query(default="solana-mainnet-beta"),
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access),
 ):
     """The venues on a chain, for the pool browser's dex filter.
 
@@ -171,9 +169,6 @@ async def list_dexes(
     indexing is filterable without a deploy. Empty when the lookup fails — a filter
     with no options is one the browser simply does not show.
     """
-    cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     from handlers.dex.pool_data import list_gecko_dexes
 
@@ -183,7 +178,7 @@ async def list_dexes(
 @router.get("/servers/{name}/dex/chains")
 async def list_chains(
     name: str,
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access),
 ):
     """The chains the pool browser can offer, from Gateway rather than a constant.
 
@@ -197,8 +192,6 @@ async def list_chains(
     has at least the chain it defaults to.
     """
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     from handlers.dex.pool_data import NETWORK_TO_GECKO
 
@@ -241,7 +234,7 @@ async def list_pools_by_address(
     name: str,
     addresses: str = Query(description="Comma-separated pool addresses (max 30)"),
     network: str = Query(default="solana-mainnet-beta"),
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access),
 ):
     """Several pools by address at once, for the favourites view.
 
@@ -253,9 +246,6 @@ async def list_pools_by_address(
     Declared above ``/dex/pools/{pool_address}`` deliberately: a path segment would
     otherwise be read as an address.
     """
-    cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     from handlers.dex.pool_data import fetch_pools_by_addresses
 
@@ -270,16 +260,13 @@ async def get_pool(
     name: str,
     pool_address: str,
     network: str = Query(default="solana-mainnet-beta"),
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access),
 ):
     """One pool by address, so ``/dex/{network}/{address}`` renders from a URL alone.
 
     404 when the pool is genuinely unknown *or* the lookup failed: either way the
     workspace has nothing to draw, and the two are indistinguishable to the user.
     """
-    cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     if not _POOL_ADDRESS_RE.match(pool_address):
         raise HTTPException(status_code=400, detail="Invalid pool_address")
@@ -326,7 +313,7 @@ async def get_pool_bins(
         description="The pool's Gateway CLMM connector, or the GeckoTerminal "
         "dex_id it is derived from (meteora-dlmm → meteora).",
     ),
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access),
 ):
     """The pool's liquidity bins, for the depth column beside its chart.
 
@@ -341,8 +328,6 @@ async def get_pool_bins(
     handler injects a client and shapes the answer.
     """
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     if not _POOL_ADDRESS_RE.match(pool_address):
         raise HTTPException(status_code=400, detail="Invalid pool_address")
diff --git a/condor/web/routes/executors.py b/condor/web/routes/executors.py
index 4ab74935..cf5feb5c 100644
--- a/condor/web/routes/executors.py
+++ b/condor/web/routes/executors.py
@@ -11,7 +11,7 @@
 from condor.fetchers.executors import EXECUTORS_POLL_MAX, MAX_EXECUTORS_FETCH
 from condor.fetchers.executors import extract_executors_list as _extract_executors_list
 from condor.fetchers.executors import fetch_all_executors, summarize_executors_by_quote
-from condor.web.auth import get_current_user
+from condor.web.auth import require_server_access
 from condor.web.models import (
     CreateExecutorRequest,
     ExecutorInfo,
@@ -55,11 +55,9 @@ async def list_executors(
         le=MAX_EXECUTORS_FETCH,
         description="Max executors to return (0 = default SDS cache)",
     ),
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access),
 ):
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     from condor.server_data_service import ServerDataType, get_server_data_service
 
@@ -130,7 +128,7 @@ async def list_executors_page(
     trading_pair: str = Query(default=""),
     status: str = Query(default=""),
     controller_id: str = Query(default=""),
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access),
 ):
     """Fetch a single page of executors with a next_cursor for progressive loading.
 
@@ -142,8 +140,6 @@ async def list_executors_page(
     from the API instead, so the stream continues past the poll's page budget.
     """
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     has_filters = bool(executor_type or trading_pair or status or controller_id)
 
@@ -263,7 +259,7 @@ async def _usd_summary(
 async def executors_summary(
     name: str,
     period: str = Query(default="1D", description="Window: 1D, 1W or 1M"),
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access),
 ):
     """PnL, volume and executor count over a period, across the whole history.
 
@@ -278,8 +274,6 @@ async def executors_summary(
     at its one request per tick.
     """
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     period = period.upper()
     window = _PERIOD_SECONDS.get(period)
@@ -313,11 +307,9 @@ async def executors_summary(
 async def create_executor_endpoint(
     name: str,
     body: CreateExecutorRequest,
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access),
 ):
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     client = await cm.get_client(name)
 
@@ -341,11 +333,9 @@ async def stop_executor_endpoint(
     name: str,
     executor_id: str,
     keep_position: bool = Query(default=False),
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access),
 ):
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     client = await cm.get_client(name)
 
@@ -361,11 +351,9 @@ async def stop_executor_endpoint(
 @router.get("/servers/{name}/executors/positions")
 async def get_positions_held(
     name: str,
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access),
 ):
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     client = await cm.get_client(name)
     try:
@@ -396,11 +384,9 @@ async def clear_position_held(
     connector: str,
     pair: str,
     controller_id: str = Query(default=""),
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access),
 ):
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     client = await cm.get_client(name)
     try:
diff --git a/condor/web/routes/market.py b/condor/web/routes/market.py
index 44c8ef56..479499ee 100644
--- a/condor/web/routes/market.py
+++ b/condor/web/routes/market.py
@@ -42,7 +42,7 @@ def _candle_cache_put(key: tuple, value: list, now: float) -> None:
 
 
 from condor.fetchers.market_data import fetch_historical_candles
-from condor.web.auth import get_current_user
+from condor.web.auth import get_current_user, require_server_access
 from condor.web.models import (
     CandleData,
     MarketPriceResponse,
@@ -83,10 +83,7 @@ async def _fetch_dex_candles(
 
 
 @router.get("/servers/{name}/market/connectors")
-async def get_connectors(name: str, user: WebUser = Depends(get_current_user)):
-    cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
+async def get_connectors(name: str, user: WebUser = Depends(require_server_access)):
 
     from condor.server_data_service import ServerDataType, get_server_data_service
 
@@ -101,11 +98,10 @@ async def get_connectors(name: str, user: WebUser = Depends(get_current_user)):
 
 
 @router.get("/servers/{name}/market/connected-exchanges")
-async def get_connected_exchanges(name: str, user: WebUser = Depends(get_current_user)):
+async def get_connected_exchanges(
+    name: str, user: WebUser = Depends(require_server_access)
+):
     """Get connectors that have credentials configured (accounts connected)."""
-    cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     from condor.server_data_service import ServerDataType, get_server_data_service
 
@@ -120,7 +116,7 @@ async def get_connected_exchanges(name: str, user: WebUser = Depends(get_current
 
 
 @router.get("/servers/{name}/market/venues")
-async def get_venues(name: str, user: WebUser = Depends(get_current_user)):
+async def get_venues(name: str, user: WebUser = Depends(require_server_access)):
     """Venues the trade panel can offer, each with its independent traits.
 
     ``{"venues": [{"name", "hummingbot_market_data", "clmm_lp"}, ...]}``. The panel
@@ -132,9 +128,6 @@ async def get_venues(name: str, user: WebUser = Depends(get_current_user)):
     so that failure is never cached; a gateway-only failure degrades inside the
     fetcher and still reports the credentialed venues.
     """
-    cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     from condor.server_data_service import ServerDataType, get_server_data_service
 
@@ -166,7 +159,7 @@ async def get_dex_pool(
         ..., description="Gateway network, e.g. solana-mainnet-beta"
     ),
     trading_pair: str = Query(...),
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access),
 ):
     """The pool a DEX pair trades in, and whether an LP position can be opened in it.
 
@@ -179,9 +172,6 @@ async def get_dex_pool(
     ask for a pool address by hand, which is a state to render rather than a failure
     to handle.
     """
-    cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     from handlers.dex.pool_data import lp_provider_for_dex, resolve_pool_info
 
@@ -220,11 +210,8 @@ async def get_price(
     name: str,
     connector: str = Query(...),
     trading_pair: str = Query(...),
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access),
 ):
-    cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     from condor.server_data_service import ServerDataType, get_server_data_service
 
@@ -263,12 +250,9 @@ async def get_price(
 async def get_rates(
     name: str,
     body: dict,
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access),
 ):
     """Cross-rates resolved from Condor's cached ticker pool (replaces the rate oracle)."""
-    cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     trading_pairs = body.get("trading_pairs") or []
     if not trading_pairs:
@@ -289,11 +273,8 @@ async def get_rates(
 async def get_trading_rules(
     name: str,
     connector: str = Query(...),
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access),
 ):
-    cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     from condor.fetchers._identifiers import IdentifierError, validate_identifier
     from condor.server_data_service import ServerDataType, get_server_data_service
@@ -339,12 +320,9 @@ async def get_trading_rules(
 async def get_tickers(
     name: str,
     connector: str = Query(...),
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access),
 ):
     """24h tickers for a connector, sorted by USD volume (highest first)."""
-    cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     from condor.market_rates import get_connector_tickers
 
@@ -378,11 +356,9 @@ async def get_order_book(
     connector: str = Query(...),
     trading_pair: str = Query(...),
     depth: int = Query(default=20, ge=1, le=100),
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access),
 ):
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     client = await cm.get_client(name)
     try:
@@ -503,11 +479,9 @@ async def get_candles(
         "connector (e.g. solana-mainnet-beta) has no CandlesFactory feed, so "
         "candles come from GeckoTerminal by pool instead.",
     ),
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access),
 ):
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     if pool_address and not _POOL_ADDRESS_RE.match(pool_address):
         raise HTTPException(status_code=400, detail="Invalid pool_address")
diff --git a/condor/web/routes/portfolio.py b/condor/web/routes/portfolio.py
index 90e69a30..19b5829e 100644
--- a/condor/web/routes/portfolio.py
+++ b/condor/web/routes/portfolio.py
@@ -7,7 +7,7 @@
 from fastapi import APIRouter, Depends, HTTPException, Query
 
 from condor.fetchers.portfolio import PORTFOLIO_HISTORY_RANGES
-from condor.web.auth import get_current_user
+from condor.web.auth import require_server_access
 from condor.web.models import (
     BalanceItem,
     ConnectorBalance,
@@ -27,11 +27,9 @@
 async def get_portfolio(
     name: str,
     refresh: bool = Query(False),
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access),
 ):
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access to this server")
 
     from condor.server_data_service import ServerDataType, get_server_data_service
 
@@ -174,11 +172,8 @@ async def get_portfolio_history(
     name: str,
     range: str = Query("1D", pattern="^(1D|1W|1M|3M)$"),
     breakdown: bool = Query(False),
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access),
 ):
-    cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access to this server")
 
     from condor.server_data_service import ServerDataType, get_server_data_service
 
diff --git a/condor/web/routes/positions.py b/condor/web/routes/positions.py
index c3845044..d7baee46 100644
--- a/condor/web/routes/positions.py
+++ b/condor/web/routes/positions.py
@@ -3,9 +3,9 @@
 import asyncio
 import logging
 
-from fastapi import APIRouter, Depends, HTTPException
+from fastapi import APIRouter, Depends
 
-from condor.web.auth import get_current_user
+from condor.web.auth import require_server_access
 from condor.web.models import WebUser
 from config_manager import get_config_manager
 
@@ -46,11 +46,9 @@ def _normalize_position(pos: dict, source: str, source_name: str) -> dict:
 @router.get("/servers/{name}/positions")
 async def get_consolidated_positions(
     name: str,
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access),
 ):
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, name):
-        raise HTTPException(status_code=403, detail="No access")
 
     from condor.server_data_service import ServerDataType, get_server_data_service
 
diff --git a/condor/web/routes/routines.py b/condor/web/routes/routines.py
index fdc64f1b..bec3c560 100644
--- a/condor/web/routes/routines.py
+++ b/condor/web/routes/routines.py
@@ -14,7 +14,11 @@
 from condor.reports import list_reports
 from condor.routine_store import get_routine_store
 from condor.runtime import client
-from condor.web.auth import get_current_user
+from condor.web.auth import (
+    check_server_access,
+    get_current_user,
+    require_server_access_by_server_name,
+)
 from condor.web.models import WebUser
 from config_manager import get_config_manager
 
@@ -141,12 +145,9 @@ async def run_routine(
     server_name: str,
     routine_name: str,
     body: RunRequest,
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access_by_server_name),
 ):
     """Execute a one-shot routine. Returns instance_id for polling."""
-    cm = get_config_manager()
-    if not cm.has_server_access(user.id, server_name):
-        raise HTTPException(status_code=403, detail="No access")
     store = get_routine_store()
     try:
         instance_id = await store.execute(
@@ -165,12 +166,9 @@ async def schedule_routine(
     server_name: str,
     routine_name: str,
     body: ScheduleRequest,
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access_by_server_name),
 ):
     """Schedule a routine at an interval. Returns instance_id."""
-    cm = get_config_manager()
-    if not cm.has_server_access(user.id, server_name):
-        raise HTTPException(status_code=403, detail="No access")
     store = get_routine_store()
     try:
         instance_id = await store.schedule(
@@ -191,9 +189,7 @@ async def run_routine_v2(
     user: WebUser = Depends(get_current_user),
 ):
     """Execute a routine (supports names with slashes like agent/routine)."""
-    cm = get_config_manager()
-    if not cm.has_server_access(user.id, body.server_name):
-        raise HTTPException(status_code=403, detail="No access")
+    check_server_access(user.id, body.server_name)
     store = get_routine_store()
     try:
         instance_id = await store.execute(
@@ -221,9 +217,7 @@ async def start_continuous_v2(
     an agent starts from chat lives in the main process's store — visible in the
     dashboard and stoppable from it — instead of dying with the MCP subprocess.
     """
-    cm = get_config_manager()
-    if not cm.has_server_access(user.id, body.server_name):
-        raise HTTPException(status_code=403, detail="No access")
+    check_server_access(user.id, body.server_name)
     store = get_routine_store()
     try:
         instance_id = await store.start_continuous(
@@ -246,9 +240,7 @@ async def schedule_routine_v2(
     user: WebUser = Depends(get_current_user),
 ):
     """Schedule a routine (supports names with slashes like agent/routine)."""
-    cm = get_config_manager()
-    if not cm.has_server_access(user.id, body.server_name):
-        raise HTTPException(status_code=403, detail="No access")
+    check_server_access(user.id, body.server_name)
     store = get_routine_store()
     try:
         instance_id = await store.schedule(
diff --git a/condor/web/routes/sessions.py b/condor/web/routes/sessions.py
index 102dffb9..90fa81e6 100644
--- a/condor/web/routes/sessions.py
+++ b/condor/web/routes/sessions.py
@@ -22,7 +22,7 @@
 from condor.runtime import conversations
 from condor.runtime.binding import UnknownAgent, remember_model_choice
 from condor.runtime.sse import SSE_HEADERS, event_stream
-from condor.web.auth import get_current_user
+from condor.web.auth import check_server_access, get_current_user
 from condor.web.models import WebUser
 from config_manager import get_config_manager
 
@@ -253,10 +253,8 @@ async def _respawn(key: SessionKey, info: SessionInfo, body: SessionAction) -> d
     # gate it exactly like consult/delegate do — otherwise a switch would be a
     # way to reach a server the caller was never granted (IDOR). Checked before
     # the teardown, so a refused switch leaves the session running as it was.
-    if body.server_name and not get_config_manager().has_server_access(
-        info.user_id or 0, body.server_name
-    ):
-        raise HTTPException(status_code=403, detail="No access")
+    if body.server_name:
+        check_server_access(info.user_id or 0, body.server_name)
 
     # Unspecified fields keep their current value, so "new" is just a switch
     # to the same identity.
diff --git a/condor/web/routes/settings.py b/condor/web/routes/settings.py
index 35454bd5..270169a7 100644
--- a/condor/web/routes/settings.py
+++ b/condor/web/routes/settings.py
@@ -5,7 +5,7 @@
 
 from fastapi import APIRouter, Depends, HTTPException, Query
 
-from condor.web.auth import get_current_user
+from condor.web.auth import get_current_user, require_server_access_query
 from condor.web.models import (
     AddCredentialRequest,
     AddServerRequest,
@@ -151,11 +151,9 @@ async def set_default_server(name: str, user: WebUser = Depends(get_current_user
 @router.get("/gateway/status")
 async def gateway_status(
     server: str = Query(...),
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access_query),
 ):
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, server):
-        raise HTTPException(status_code=403, detail="No access")
     client = await _get_client(cm, server)
     try:
         info = await client.gateway.get_status()
@@ -176,11 +174,9 @@ async def gateway_status(
 async def gateway_pull(
     req: GatewayPullRequest,
     server: str = Query(...),
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access_query),
 ):
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, server):
-        raise HTTPException(status_code=403, detail="No access")
     client = await _get_client(cm, server)
     try:
         # Parse "image:tag" format (e.g. "hummingbot/gateway:latest")
@@ -197,11 +193,9 @@ async def gateway_pull(
 @router.get("/gateway/pull-status")
 async def gateway_pull_status(
     server: str = Query(...),
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access_query),
 ):
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, server):
-        raise HTTPException(status_code=403, detail="No access")
     client = await _get_client(cm, server)
     try:
         result = await client.docker.get_pull_status()
@@ -215,11 +209,9 @@ async def gateway_pull_status(
 async def gateway_start(
     req: GatewayStartRequest,
     server: str = Query(...),
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access_query),
 ):
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, server):
-        raise HTTPException(status_code=403, detail="No access")
     client = await _get_client(cm, server)
     try:
         result = await client.gateway.start(
@@ -237,11 +229,9 @@ async def gateway_start(
 @router.post("/gateway/stop")
 async def gateway_stop(
     server: str = Query(...),
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access_query),
 ):
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, server):
-        raise HTTPException(status_code=403, detail="No access")
     client = await _get_client(cm, server)
     try:
         result = await client.gateway.stop()
@@ -254,11 +244,9 @@ async def gateway_stop(
 @router.post("/gateway/restart")
 async def gateway_restart(
     server: str = Query(...),
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access_query),
 ):
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, server):
-        raise HTTPException(status_code=403, detail="No access")
     client = await _get_client(cm, server)
     try:
         result = await client.gateway.restart()
@@ -271,11 +259,9 @@ async def gateway_restart(
 @router.get("/gateway/logs")
 async def gateway_logs(
     server: str = Query(...),
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access_query),
 ):
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, server):
-        raise HTTPException(status_code=403, detail="No access")
     client = await _get_client(cm, server)
     try:
         logs = await client.gateway.get_logs()
@@ -291,11 +277,9 @@ async def gateway_logs(
 @router.get("/gateway/networks")
 async def gateway_networks(
     server: str = Query(...),
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access_query),
 ):
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, server):
-        raise HTTPException(status_code=403, detail="No access")
     client = await _get_client(cm, server)
     try:
         result = await client.gateway.list_networks()
@@ -312,11 +296,9 @@ async def gateway_networks(
 async def gateway_network_config(
     network_id: str,
     server: str = Query(...),
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access_query),
 ):
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, server):
-        raise HTTPException(status_code=403, detail="No access")
     client = await _get_client(cm, server)
     try:
         config = await client.gateway.get_network_config(network_id)
@@ -333,11 +315,9 @@ async def gateway_network_update(
     network_id: str,
     req: GatewayNetworkUpdateRequest,
     server: str = Query(...),
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access_query),
 ):
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, server):
-        raise HTTPException(status_code=403, detail="No access")
     client = await _get_client(cm, server)
     try:
         result = await client.gateway.update_network_config(network_id, req.config)
@@ -355,11 +335,9 @@ async def gateway_network_update(
 @router.get("/gateway/wallets")
 async def gateway_wallets(
     server: str = Query(...),
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access_query),
 ):
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, server):
-        raise HTTPException(status_code=403, detail="No access")
     client = await _get_client(cm, server)
     try:
         wallets = await client.accounts.list_gateway_wallets()
@@ -388,11 +366,9 @@ async def _gateway_default_address(client, chain: str) -> str | None:
 async def gateway_wallet_add(
     req: GatewayWalletAddRequest,
     server: str = Query(...),
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access_query),
 ):
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, server):
-        raise HTTPException(status_code=403, detail="No access")
     client = await _get_client(cm, server)
     # Gateway's add-wallet always promotes the new key to the chain default, so when the user
     # opted out we capture the existing default first and restore it after the import.
@@ -439,11 +415,9 @@ async def gateway_wallet_add(
 async def gateway_wallet_set_default(
     req: GatewayWalletDefaultRequest,
     server: str = Query(...),
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access_query),
 ):
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, server):
-        raise HTTPException(status_code=403, detail="No access")
     client = await _get_client(cm, server)
     try:
         result = await client.accounts.set_default_gateway_wallet(
@@ -467,11 +441,9 @@ async def gateway_wallet_remove(
     chain: str,
     address: str,
     server: str = Query(...),
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access_query),
 ):
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, server):
-        raise HTTPException(status_code=403, detail="No access")
     client = await _get_client(cm, server)
     try:
         result = await client.accounts.remove_gateway_wallet(
@@ -554,11 +526,9 @@ async def update_voice_settings(
 @router.get("/credentials")
 async def list_credentials(
     server: str = Query(...),
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access_query),
 ):
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, server):
-        raise HTTPException(status_code=403, detail="No access")
     client = await _get_client(cm, server)
     try:
         creds_raw = await client.accounts.list_account_credentials("master_account")
@@ -589,11 +559,8 @@ async def list_credentials(
 async def list_connectors(
     server: str = Query(...),
     type: str = Query(None),
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access_query),
 ):
-    cm = get_config_manager()
-    if not cm.has_server_access(user.id, server):
-        raise HTTPException(status_code=403, detail="No access")
 
     from condor.server_data_service import ServerDataType, get_server_data_service
 
@@ -629,11 +596,9 @@ async def list_connectors(
 async def connector_config_map(
     name: str,
     server: str = Query(...),
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access_query),
 ):
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, server):
-        raise HTTPException(status_code=403, detail="No access")
     client = await _get_client(cm, server)
     try:
         config_map = await client.connectors.get_config_map(name)
@@ -649,11 +614,9 @@ async def connector_config_map(
 async def add_credential(
     req: AddCredentialRequest,
     server: str = Query(...),
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access_query),
 ):
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, server):
-        raise HTTPException(status_code=403, detail="No access")
     # Credentials are server configuration, not trading: a shared trader must not
     # overwrite the owner's exchange keys. Same line update_server/delete_server draw.
     _require_owner(cm, user.id, server)
@@ -680,11 +643,9 @@ async def add_credential(
 async def delete_credential(
     connector: str,
     server: str = Query(...),
-    user: WebUser = Depends(get_current_user),
+    user: WebUser = Depends(require_server_access_query),
 ):
     cm = get_config_manager()
-    if not cm.has_server_access(user.id, server):
-        raise HTTPException(status_code=403, detail="No access")
     # Deleting a key kills the owner's running bots' connectivity — owner only.
     _require_owner(cm, user.id, server)
     client = await _get_client(cm, server)
diff --git a/tests/test_agent_server_pin.py b/tests/test_agent_server_pin.py
index b3d30d7c..8dcfbc09 100644
--- a/tests/test_agent_server_pin.py
+++ b/tests/test_agent_server_pin.py
@@ -34,6 +34,11 @@ def env(tmp_path, monkeypatch):
     monkeypatch.setattr(
         "config_manager.get_config_manager", lambda: FakeConfigManager()
     )
+    # The server-access guard lives in condor.web.auth (SEC-147), which binds
+    # get_config_manager at import time — patch it there too.
+    monkeypatch.setattr(
+        "condor.web.auth.get_config_manager", lambda: FakeConfigManager()
+    )
     AgentStore().create(name="Brigado", description="BRL market making")
     return tmp_path
 
diff --git a/tests/test_agent_start_server_access.py b/tests/test_agent_start_server_access.py
index 5c80bedd..d6ab8426 100644
--- a/tests/test_agent_start_server_access.py
+++ b/tests/test_agent_start_server_access.py
@@ -61,6 +61,11 @@ def env(tmp_path, monkeypatch):
     monkeypatch.setattr(
         "config_manager.get_config_manager", lambda: FakeConfigManager()
     )
+    # The server-access guard lives in condor.web.auth (SEC-147), which binds
+    # get_config_manager at import time — patch it there too.
+    monkeypatch.setattr(
+        "condor.web.auth.get_config_manager", lambda: FakeConfigManager()
+    )
     monkeypatch.setattr(engine_module, "TickEngine", FakeEngine)
     FakeEngine.spawned = []
     AgentStore().create(name="Brigado", description="BRL market making")
diff --git a/tests/test_agents.py b/tests/test_agents.py
index 9467b18a..82205f6f 100644
--- a/tests/test_agents.py
+++ b/tests/test_agents.py
@@ -649,8 +649,7 @@ async def _fail_run_consult(**kw):  # pragma: no cover - must not be reached
 
     monkeypatch.setattr(consult_module, "run_consult", _fail_run_consult)
     monkeypatch.setattr(
-        config_manager,
-        "get_config_manager",
+        "condor.web.auth.get_config_manager",
         lambda: SimpleNamespace(has_server_access=lambda uid, name: False),
     )
 
@@ -679,8 +678,7 @@ async def _capture_run_consult(**kw):
 
     monkeypatch.setattr(consult_module, "run_consult", _capture_run_consult)
     monkeypatch.setattr(
-        config_manager,
-        "get_config_manager",
+        "condor.web.auth.get_config_manager",
         lambda: SimpleNamespace(has_server_access=lambda uid, name: True),
     )
 
diff --git a/tests/test_code_run_tool.py b/tests/test_code_run_tool.py
index 91bbbfa1..f899fc62 100644
--- a/tests/test_code_run_tool.py
+++ b/tests/test_code_run_tool.py
@@ -258,6 +258,10 @@ def _config(monkeypatch, **kw):
     monkeypatch.setattr(
         code_routes, "get_config_manager", lambda: _FakeConfigManager(**kw)
     )
+    # The server-access guard moved to condor.web.auth (SEC-147).
+    monkeypatch.setattr(
+        "condor.web.auth.get_config_manager", lambda: _FakeConfigManager(**kw)
+    )
 
 
 def test_the_route_runs_the_snippet_as_the_authenticated_caller(monkeypatch):
@@ -418,8 +422,13 @@ class _AuthConfigManager:
         def get_user_role(self, user_id):
             return UserRole.ADMIN if user_id == seat_user_id else UserRole.PENDING
 
-    monkeypatch.setattr(web_auth, "get_config_manager", lambda: _AuthConfigManager())
+        def has_server_access(self, user_id, server_name, *a, **kw):
+            return True
+
+    # _config also stubs condor.web.auth, so install the auth-side manager last:
+    # in production both answers come from the one real ConfigManager.
     _config(monkeypatch, allowed=True, admins={seat_user_id})
+    monkeypatch.setattr(web_auth, "get_config_manager", lambda: _AuthConfigManager())
 
     async def _execute(code, **kw):
         return {
diff --git a/tests/test_dex_liquidity_bins_route.py b/tests/test_dex_liquidity_bins_route.py
index 4935db6c..f978c1d9 100644
--- a/tests/test_dex_liquidity_bins_route.py
+++ b/tests/test_dex_liquidity_bins_route.py
@@ -104,6 +104,7 @@ def route_client(monkeypatch):
     def build(allowed=True, client=None, client_error=None):
         cm = FakeConfigManager(allowed, client, client_error)
         monkeypatch.setattr(dex_routes, "get_config_manager", lambda: cm)
+        monkeypatch.setattr("condor.web.auth.get_config_manager", lambda: cm)
         app = FastAPI()
         app.include_router(dex_routes.router)
         app.dependency_overrides[get_current_user] = lambda: USER
diff --git a/tests/test_dex_pool_discovery.py b/tests/test_dex_pool_discovery.py
index 7e610ddf..8c74f9c5 100644
--- a/tests/test_dex_pool_discovery.py
+++ b/tests/test_dex_pool_discovery.py
@@ -29,7 +29,7 @@ def run(coro):
 
 
 @pytest.fixture(autouse=True)
-def _clear_caches():
+def _clear_caches(monkeypatch):
     for cache in (
         pool_data._gecko_page_cache,
         pool_data._gecko_dexes_cache,
@@ -38,6 +38,11 @@ def _clear_caches():
         pool_data._multi_pool_cache,
     ):
         cache.clear()
+    # No test in this module may reach the real GeckoTerminal — and a Gateway
+    # listing now looks pools up there too, to fill the figures Orca's connector
+    # leaves null. The empty stand-in is overridden by the ``fake_gecko`` fixture
+    # wherever a test actually wants rows back.
+    monkeypatch.setattr(pool_data, "_gecko_client", lambda: FakeGecko())
     yield
 
 
@@ -468,6 +473,72 @@ def test_gateway_lists_are_cached_per_connector_and_search():
     assert len(clmm.calls) == 2
 
 
+# ── gateway rows filled from GeckoTerminal ──
+
+
+def test_gateway_gaps_are_filled_from_gecko(fake_gecko):
+    """Orca reports TVL and nothing else; the browser's other columns come from gecko."""
+    client = fake_gecko(pd.DataFrame([gecko_row(dex_id="orca")]))
+    clmm = FakeClmm(
+        {"pools": [gateway_row(connector="orca", volume_24h=None, apr=None)]}
+    )
+    pool = run(pool_data.list_gateway_pools(FakeClient(clmm), "orca"))[0]
+    assert pool["volume_24h"] == 4_200_000.0
+    assert pool["price_change_24h"] == -3.5
+    # The connector's own TVL stands; gecko's only fills a gap.
+    assert pool["reserve_usd"] == 4_500_000.0
+    assert ("multi", "solana", (POOL,)) in client.calls
+
+
+def test_missing_gateway_yield_is_estimated_from_volume_and_fee_tier(fake_gecko):
+    fake_gecko(pd.DataFrame([gecko_row(dex_id="orca")]))
+    clmm = FakeClmm(
+        {"pools": [gateway_row(connector="orca", volume_24h=None, apr=None)]}
+    )
+    pool = run(pool_data.list_gateway_pools(FakeClient(clmm), "orca"))[0]
+    # 4.2M of volume at 0.2% over 4.5M of TVL.
+    fees = 4_200_000.0 * 0.2 / 100
+    assert pool["fees_24h"] == pytest.approx(fees)
+    assert pool["apr"] == pytest.approx(fees / 4_500_000.0 * 100)
+    assert pool["apy"] > pool["apr"]
+    assert pool["apr_estimated"] is True
+
+
+def test_a_reported_yield_is_never_overwritten(fake_gecko):
+    fake_gecko(pd.DataFrame([gecko_row()]))
+    clmm = FakeClmm({"pools": [gateway_row(volume_24h=None)]})
+    pool = run(pool_data.list_gateway_pools(FakeClient(clmm), "meteora"))[0]
+    assert pool["apr"] == 42.5
+    assert "apr_estimated" not in pool
+
+
+def test_a_reported_volume_is_never_overwritten(fake_gecko):
+    fake_gecko(pd.DataFrame([gecko_row()]))
+    clmm = FakeClmm({"pools": [gateway_row()]})
+    pool = run(pool_data.list_gateway_pools(FakeClient(clmm), "meteora"))[0]
+    assert pool["volume_24h"] == 1_200_000.0
+
+
+def test_a_failed_lookup_leaves_the_rows_alone(fake_gecko):
+    fake_gecko(error=RuntimeError("gecko down"))
+    clmm = FakeClmm({"pools": [gateway_row(volume_24h=None, apr=None)]})
+    pool = run(pool_data.list_gateway_pools(FakeClient(clmm), "orca"))[0]
+    assert pool["volume_24h"] is None
+    assert pool["reserve_usd"] == 4_500_000.0
+
+
+def test_the_filled_page_is_what_gets_cached(fake_gecko):
+    """The extra request is spent once per page, not once per viewer of it."""
+    client = fake_gecko(pd.DataFrame([gecko_row(dex_id="orca")]))
+    clmm = FakeClmm({"pools": [gateway_row(connector="orca", volume_24h=None)]})
+    gateway_client = FakeClient(clmm)
+    run(pool_data.list_gateway_pools(gateway_client, "orca"))
+    second = run(pool_data.list_gateway_pools(gateway_client, "orca"))
+    assert len(clmm.calls) == 1
+    assert len([c for c in client.calls if c[0] == "multi"]) == 1
+    assert second[0]["volume_24h"] == 4_200_000.0
+
+
 # ── fetch_pool_by_address ──
 
 
@@ -525,6 +596,7 @@ def route_client(monkeypatch):
     def build(allowed=True, client=None, client_error=None):
         cm = FakeConfigManager(allowed, client, client_error)
         monkeypatch.setattr(dex_routes, "get_config_manager", lambda: cm)
+        monkeypatch.setattr("condor.web.auth.get_config_manager", lambda: cm)
         app = FastAPI()
         app.include_router(dex_routes.router)
         app.dependency_overrides[get_current_user] = lambda: USER
diff --git a/tests/test_dex_pool_resolution.py b/tests/test_dex_pool_resolution.py
index 75dd23ea..908a674c 100644
--- a/tests/test_dex_pool_resolution.py
+++ b/tests/test_dex_pool_resolution.py
@@ -465,11 +465,21 @@ async def _resolve(_net, _pair):
 
 
 def test_route_rejects_a_caller_without_access(monkeypatch):
+    """Refused by the ``require_server_access`` dependency (SEC-147), which
+    runs before the endpoint body — so nothing is resolved. That the route
+    carries it is pinned by ``tests/test_web_server_access_dependency.py``."""
     from fastapi import HTTPException
 
-    async def _resolve(_net, _pair):
-        raise AssertionError("access is checked before anything is resolved")
+    from condor.web.auth import require_server_access
+    from condor.web.models import WebUser
 
+    class _Cm:
+        def has_server_access(self, user_id, name):
+            return False
+
+    monkeypatch.setattr(
+        "condor.web.auth.get_config_manager", lambda: _Cm(), raising=True
+    )
     with pytest.raises(HTTPException) as e:
-        _call_route(monkeypatch, _resolve, access=False)
+        asyncio.run(require_server_access("srv", user=WebUser(id=1, role="user")))
     assert e.value.status_code == 403
diff --git a/tests/test_executors_period_summary.py b/tests/test_executors_period_summary.py
index 1223f54b..7883ae47 100644
--- a/tests/test_executors_period_summary.py
+++ b/tests/test_executors_period_summary.py
@@ -227,11 +227,20 @@ def test_an_unknown_period_is_a_bad_request(summary_env):
     assert exc.value.status_code == 400
 
 
-def test_access_is_checked_before_any_work(summary_env, monkeypatch):
-    """No server access, no walk."""
-    client = summary_env([_executor(0)], {})
+def test_access_is_checked_before_any_work(monkeypatch):
+    """No server access, no walk.
+
+    Since SEC-147 the guard is the ``require_server_access`` dependency, which
+    FastAPI resolves before the endpoint coroutine is ever awaited — so "before
+    any work" is structural, not a matter of statement order in the body. That
+    the route carries the dependency is pinned by
+    ``tests/test_web_server_access_dependency.py``.
+    """
+    from condor.web.auth import require_server_access
+    from condor.web.models import WebUser
+
     monkeypatch.setattr(
-        "condor.web.routes.executors.get_config_manager",
+        "condor.web.auth.get_config_manager",
         lambda: type(
             "_Denied",
             (),
@@ -240,10 +249,9 @@ def test_access_is_checked_before_any_work(summary_env, monkeypatch):
     )
 
     with pytest.raises(HTTPException) as exc:
-        _summary()
+        asyncio.run(require_server_access("srv", user=WebUser(id=1, role="user")))
 
     assert exc.value.status_code == 403
-    assert client.calls == []
 
 
 # ── the pure aggregation ──
diff --git a/tests/test_fetcher_identifier_validation.py b/tests/test_fetcher_identifier_validation.py
index 433f2f60..af7f03ae 100644
--- a/tests/test_fetcher_identifier_validation.py
+++ b/tests/test_fetcher_identifier_validation.py
@@ -185,6 +185,9 @@ def _client(monkeypatch) -> TestClient:
     monkeypatch.setattr(
         market_routes, "get_config_manager", lambda: FakeConfigManager()
     )
+    monkeypatch.setattr(
+        "condor.web.auth.get_config_manager", lambda: FakeConfigManager()
+    )
     app = FastAPI()
     app.include_router(market_routes.router)
     app.dependency_overrides[get_current_user] = lambda: USER
diff --git a/tests/test_fetcher_venues.py b/tests/test_fetcher_venues.py
index 517e63e2..2759cf78 100644
--- a/tests/test_fetcher_venues.py
+++ b/tests/test_fetcher_venues.py
@@ -378,18 +378,24 @@ def test_route_normalizes_a_none_answer(monkeypatch):
 
 
 def test_route_rejects_a_caller_without_access(monkeypatch):
+    """The guard is the ``require_server_access`` dependency (SEC-147).
+
+    It runs before the endpoint body, so the refusal is asserted on the
+    dependency itself; that the route actually carries it is pinned
+    structurally by ``tests/test_web_server_access_dependency.py``.
+    """
     from fastapi import HTTPException
 
+    from condor.web.auth import require_server_access
     from condor.web.models import WebUser
-    from condor.web.routes.market import get_venues
 
     class _Cm:
         def has_server_access(self, user_id, name):
             return False
 
     monkeypatch.setattr(
-        "condor.web.routes.market.get_config_manager", lambda: _Cm(), raising=True
+        "condor.web.auth.get_config_manager", lambda: _Cm(), raising=True
     )
     with pytest.raises(HTTPException) as e:
-        asyncio.run(get_venues("srv", user=WebUser(id=1, role="user")))
+        asyncio.run(require_server_access("srv", user=WebUser(id=1, role="user")))
     assert e.value.status_code == 403
diff --git a/tests/test_routines_access.py b/tests/test_routines_access.py
index a9b3b0f5..9ff6d065 100644
--- a/tests/test_routines_access.py
+++ b/tests/test_routines_access.py
@@ -84,6 +84,7 @@ def client_and_store(monkeypatch):
     cm = FakeConfigManager(allowed={(USER.id, OWNED_SERVER)})
     monkeypatch.setattr(routines_module, "get_routine_store", lambda: store)
     monkeypatch.setattr(routines_module, "get_config_manager", lambda: cm)
+    monkeypatch.setattr("condor.web.auth.get_config_manager", lambda: cm)
 
     app = FastAPI()
     app.include_router(routines_module.router)
diff --git a/tests/test_session_model_switch.py b/tests/test_session_model_switch.py
index c691de94..a4362bbd 100644
--- a/tests/test_session_model_switch.py
+++ b/tests/test_session_model_switch.py
@@ -106,6 +106,7 @@ def env(tmp_path, monkeypatch):
         "config_manager.get_config_manager", lambda: FakeConfigManager()
     )
     monkeypatch.setattr(session_routes, "get_config_manager", FakeConfigManager)
+    monkeypatch.setattr("condor.web.auth.get_config_manager", FakeConfigManager)
     monkeypatch.setattr("handlers.agents._shared.DEFAULT_AGENT", FALLBACK)
     monkeypatch.setattr("condor.web.routes.chat_ws.DEFAULT_AGENT", FALLBACK)
 
diff --git a/tests/test_session_server_switch.py b/tests/test_session_server_switch.py
index d50083be..29b463c2 100644
--- a/tests/test_session_server_switch.py
+++ b/tests/test_session_server_switch.py
@@ -86,6 +86,9 @@ def env(tmp_path, monkeypatch):
     monkeypatch.setattr(session_module, "ACPClient", _Client)
     monkeypatch.setattr(session_module, "build_initial_context", lambda *a, **k: "")
     monkeypatch.setattr(routes, "get_config_manager", lambda: FakeConfigManager())
+    monkeypatch.setattr(
+        "condor.web.auth.get_config_manager", lambda: FakeConfigManager()
+    )
     monkeypatch.setattr(
         "handlers.agents._shared.build_mcp_servers_for_session", lambda *a, **k: []
     )
diff --git a/tests/test_web_credentials_owner_only.py b/tests/test_web_credentials_owner_only.py
index ecd0c36a..3890c706 100644
--- a/tests/test_web_credentials_owner_only.py
+++ b/tests/test_web_credentials_owner_only.py
@@ -87,6 +87,7 @@ def env(monkeypatch):
     cm = FakeConfigManager(client)
     sds = FakeSDS()
     monkeypatch.setattr(settings_routes, "get_config_manager", lambda: cm)
+    monkeypatch.setattr("condor.web.auth.get_config_manager", lambda: cm)
     monkeypatch.setattr(
         "condor.server_data_service.get_server_data_service", lambda: sds
     )
diff --git a/tests/test_web_server_access_dependency.py b/tests/test_web_server_access_dependency.py
new file mode 100644
index 00000000..cd9c2e7a
--- /dev/null
+++ b/tests/test_web_server_access_dependency.py
@@ -0,0 +1,292 @@
+"""SEC-147: the server-access guard is a dependency, and no route may skip it.
+
+The 403 preamble used to be hand-copied into ~88 endpoints, which made access
+control opt-in: SEC-007, SEC-019 and SEC-045 were each a patch for one endpoint
+that simply forgot to type it. Centralising it only helps if a *new* endpoint
+cannot forget it either, so the regression here is structural rather than
+per-endpoint: it walks the real FastAPI app and asserts that every server-scoped
+route carries one of the ``require_server_access*`` dependencies, with a small
+explicit allowlist for the routes that deliberately answer differently.
+
+Three shapes exist, and they are not interchangeable:
+
+* ``/servers/{name}/...``   → ``require_server_access``
+* ``/servers/{server_name}/...`` → ``require_server_access_by_server_name``
+* ``?server=...``          → ``require_server_access_query``
+
+and a fourth that no path/query dependency can cover — the server name arriving
+in the request **body** — which uses the shared ``check_server_access`` helper
+the dependencies are built on. Those sites are pinned by source inspection
+below, because there is no signature for FastAPI to reflect on.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import re
+
+import pytest
+from fastapi import HTTPException
+from fastapi.routing import APIRoute
+from starlette.testclient import TestClient
+
+from condor.web.app import create_app
+from condor.web.auth import (
+    check_server_access,
+    get_current_user,
+    require_server_access,
+    require_server_access_by_server_name,
+    require_server_access_query,
+)
+from condor.web.models import WebUser
+
+GUARDS = {
+    require_server_access,
+    require_server_access_by_server_name,
+    require_server_access_query,
+}
+
+USER = WebUser(id=7, username="u", first_name="U", role="user")
+OWNED = "mine"
+FOREIGN = "not-mine"
+
+
+# ── The reviewed exceptions ──
+
+# Server-scoped routes that deliberately do NOT use the dependency. Each entry
+# was reviewed one by one; anything not listed here must carry the guard.
+ALLOWLIST: dict[tuple[str, str], str] = {
+    # These four answer 404 "Server not found" instead of 403 "No access" on
+    # purpose: a caller must not be able to tell an existing server they cannot
+    # touch from one that does not exist (no enumeration). The dependency's 403
+    # would leak exactly that, so they keep an inline check.
+    ("GET", "/api/v1/servers/{name}/status"): "404-shaped, non-enumerable",
+    ("PUT", "/api/v1/settings/servers/{name}"): "404-shaped, non-enumerable",
+    ("DELETE", "/api/v1/settings/servers/{name}"): "404-shaped, non-enumerable",
+    ("POST", "/api/v1/settings/servers/{name}/default"): "404-shaped, non-enumerable",
+}
+
+# Routes that read a server but have never had an access check. NOT a licence:
+# each is a live gap, listed so the sweep above stays green while they are
+# fixed under their own item rather than silently smuggled into SEC-147.
+KNOWN_GAPS: dict[tuple[str, str], str] = {
+    ("GET", "/api/v1/routines/options/{source}"): (
+        "reads controller configs off any ?server= with no access check"
+    ),
+}
+
+# The body-param sites: "<module>.<function>" → the attribute holding the name.
+# A path/query dependency cannot see a request body, so these call the shared
+# helper instead. Listed explicitly so deleting one is a test failure.
+BODY_SITES = [
+    ("condor.web.routes.routines", "run_routine_v2"),
+    ("condor.web.routes.routines", "start_continuous_v2"),
+    ("condor.web.routes.routines", "schedule_routine_v2"),
+    ("condor.web.routes.code", "run_code"),
+    ("condor.web.routes.sessions", "_respawn"),
+    ("condor.web.routes.agents", "update_agent_config"),
+    ("condor.web.routes.agents", "consult_agent"),
+    ("condor.web.routes.agents", "delegate_agent"),
+    ("condor.web.routes.agents", "_start"),
+]
+
+
+@pytest.fixture(scope="module")
+def app():
+    return create_app()
+
+
+def _flatten(dependant, acc=None):
+    acc = set() if acc is None else acc
+    for sub in dependant.dependencies:
+        acc.add(sub.call)
+        _flatten(sub, acc)
+    return acc
+
+
+def _server_scoped_routes(app):
+    """Yield ``(route, methods, why)`` for every route that names a server."""
+    for route in app.routes:
+        if not isinstance(route, APIRoute):
+            continue
+        methods = sorted(m for m in route.methods if m != "HEAD")
+        if re.search(r"/servers/\{name\}(/|$)", route.path):
+            yield route, methods, "path {name}"
+        elif "{server_name}" in route.path:
+            yield route, methods, "path {server_name}"
+        elif any(p.name == "server" for p in route.dependant.query_params):
+            yield route, methods, "query ?server="
+
+
+# ── The structural sweep ──
+
+
+def test_every_server_scoped_route_carries_the_guard(app):
+    """A new server-scoped endpoint cannot forget the access check."""
+    missing = []
+    for route, methods, why in _server_scoped_routes(app):
+        if _flatten(route.dependant) & GUARDS:
+            continue
+        for method in methods:
+            key = (method, route.path)
+            if key in ALLOWLIST or key in KNOWN_GAPS:
+                continue
+            missing.append(f"{method} {route.path} ({why}) -> {route.name}")
+    assert not missing, (
+        "server-scoped routes with no require_server_access* dependency:\n  "
+        + "\n  ".join(missing)
+        + "\nAdd the dependency, or justify the route in ALLOWLIST."
+    )
+
+
+def test_each_shape_uses_the_dependency_that_matches_it(app):
+    """A guard whose parameter does not match the route fails closed, loudly.
+
+    ``require_server_access`` declares ``name``; on a route with no ``{name}``
+    path parameter FastAPI would demote it to a required *query* parameter and
+    every request would 422. That is safe but broken, so pin that each guard
+    reads the parameter it was meant to read.
+    """
+    wrong = []
+    for route in app.routes:
+        if not isinstance(route, APIRoute):
+            continue
+        for sub in route.dependant.dependencies:
+            if sub.call not in GUARDS:
+                continue
+            path_params = {p.name for p in sub.path_params}
+            query_params = {p.name for p in sub.query_params}
+            if sub.call is require_server_access and "name" not in path_params:
+                wrong.append(f"{route.path}: require_server_access has no {{name}}")
+            if (
+                sub.call is require_server_access_by_server_name
+                and "server_name" not in path_params
+            ):
+                wrong.append(f"{route.path}: no {{server_name}} path param")
+            if sub.call is require_server_access_query and "server" not in query_params:
+                wrong.append(f"{route.path}: no ?server= query param")
+    assert not wrong, wrong
+
+
+def test_the_sweep_actually_finds_the_migrated_routes(app):
+    """Guard against the sweep silently matching nothing and passing."""
+    guarded = [
+        r
+        for r in app.routes
+        if isinstance(r, APIRoute) and _flatten(r.dependant) & GUARDS
+    ]
+    assert len(guarded) >= 70, len(guarded)
+
+
+def test_allowlisted_routes_still_check_access_inline(app):
+    """The 404-shaped exceptions keep their own check — they are not unguarded."""
+    by_key = {}
+    for route in app.routes:
+        if not isinstance(route, APIRoute):
+            continue
+        for method in route.methods:
+            by_key[(method, route.path)] = route
+    for key in ALLOWLIST:
+        route = by_key.get(key)
+        assert route is not None, f"allowlisted route no longer exists: {key}"
+        source = inspect.getsource(route.endpoint)
+        assert "has_server_access" in source, key
+        assert "Server not found" in source, key
+
+
+def test_body_param_sites_call_the_shared_helper():
+    """The body shape has no signature to reflect on, so pin it by source."""
+    import importlib
+
+    for module_name, func_name in BODY_SITES:
+        module = importlib.import_module(module_name)
+        source = inspect.getsource(getattr(module, func_name))
+        assert "check_server_access(" in source, f"{module_name}.{func_name}"
+
+
+# ── The guards actually refuse ──
+
+
+class _Cm:
+    """Grants ``OWNED`` to ``USER`` and nothing else."""
+
+    def has_server_access(self, user_id, server_name, *a, **kw):
+        return user_id == USER.id and server_name == OWNED
+
+
+@pytest.fixture
+def deny(monkeypatch):
+    monkeypatch.setattr("condor.web.auth.get_config_manager", lambda: _Cm())
+
+
+def test_path_guard_refuses_a_foreign_server(deny):
+    with pytest.raises(HTTPException) as exc:
+        asyncio.run(require_server_access(FOREIGN, user=USER))
+    assert exc.value.status_code == 403
+    assert exc.value.detail == "No access"
+
+
+def test_path_guard_returns_the_user_on_an_owned_server(deny):
+    assert asyncio.run(require_server_access(OWNED, user=USER)) is USER
+
+
+def test_server_name_alias_guard_refuses_a_foreign_server(deny):
+    with pytest.raises(HTTPException) as exc:
+        asyncio.run(require_server_access_by_server_name(FOREIGN, user=USER))
+    assert exc.value.status_code == 403
+    assert asyncio.run(require_server_access_by_server_name(OWNED, user=USER)) is USER
+
+
+def test_query_guard_refuses_a_foreign_server(deny):
+    with pytest.raises(HTTPException) as exc:
+        asyncio.run(require_server_access_query(FOREIGN, user=USER))
+    assert exc.value.status_code == 403
+    assert asyncio.run(require_server_access_query(OWNED, user=USER)) is USER
+
+
+def test_the_shared_helper_refuses_a_foreign_server(deny):
+    with pytest.raises(HTTPException) as exc:
+        check_server_access(USER.id, FOREIGN)
+    assert exc.value.status_code == 403
+    assert exc.value.detail == "No access"
+    assert check_server_access(USER.id, OWNED) is None
+
+
+# ── End to end, through the real app, one route per shape ──
+
+
+@pytest.fixture
+def client(app, deny):
+    app.dependency_overrides[get_current_user] = lambda: USER
+    yield TestClient(app)
+    app.dependency_overrides.clear()
+
+
+@pytest.mark.parametrize(
+    "method,url",
+    [
+        # {name} path param
+        ("GET", f"/api/v1/servers/{FOREIGN}/bots"),
+        ("GET", f"/api/v1/servers/{FOREIGN}/market/connectors"),
+        ("GET", f"/api/v1/servers/{FOREIGN}/portfolio"),
+        # aliased ?server= query param (settings.py)
+        ("GET", f"/api/v1/settings/gateway/status?server={FOREIGN}"),
+        ("GET", f"/api/v1/settings/credentials?server={FOREIGN}"),
+        # {server_name} path param
+        ("POST", f"/api/v1/routines/servers/{FOREIGN}/some_routine/run"),
+    ],
+)
+def test_a_foreign_server_is_refused_over_http(client, method, url):
+    resp = client.request(method, url, json={"config": {}})
+    assert resp.status_code == 403, resp.text
+    assert resp.json()["detail"] == "No access"
+
+
+def test_a_foreign_server_in_the_body_is_refused_over_http(client):
+    resp = client.post(
+        "/api/v1/routines/run",
+        json={"routine_name": "agent/some_routine", "server_name": FOREIGN},
+    )
+    assert resp.status_code == 403, resp.text
+    assert resp.json()["detail"] == "No access"

From a335584037d4fd03781aaaf53358afd13428a81d Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Fri, 14 Aug 2026 16:04:16 +0300
Subject: [PATCH 074/116] (fix) scope routine hooks to their owner
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Routine hooks were one global config per routine name: any approved user
could PUT one and then receive the full interactive report — portfolio
value, PnL, positions — of every run of that routine by anyone, including
runs against servers they have no access to. A silent, persistent
cross-user exfiltration channel, and GET leaked everyone's chat ids too.

Hooks now belong to whoever saved them. Storage is keyed by routine name
then owner id; the two REST endpoints read and write only the caller's
own config; dispatch takes the run's owner (user_id in the instance meta,
the chat id on the Telegram path) and fires only that owner's hooks.
Gating the endpoints alone would have left the hole open — a hook written
before the gate would keep firing for everyone — so the owner check lives
in dispatch, where the send actually happens.

Recipients are bounded by what the owner controls: a plain user reaches
only their own Telegram chat, admins may target groups and channels as
they do today. Checked at save time (403) and again at dispatch, so a
hooks file from an older build cannot deliver anywhere either.

Hooks written before ownership existed are kept verbatim under an explicit
unowned key: they stop firing for everyone, fire only for an admin's runs,
stay visible to an admin in the dashboard, and are adopted under that
admin's id the next time they are saved.
---
 condor/routine_hooks.py               | 168 ++++++++++++++--
 condor/routine_store.py               |   2 +
 condor/web/routes/routines.py         |  15 +-
 handlers/routines/__init__.py         |   3 +
 tests/test_routine_hooks_ownership.py | 264 ++++++++++++++++++++++++++
 5 files changed, 427 insertions(+), 25 deletions(-)
 create mode 100644 tests/test_routine_hooks_ownership.py

diff --git a/condor/routine_hooks.py b/condor/routine_hooks.py
index 2ce551a6..4bd33a7c 100644
--- a/condor/routine_hooks.py
+++ b/condor/routine_hooks.py
@@ -1,15 +1,38 @@
-"""Persistent per-routine post-execution hooks.
+"""Persistent per-routine, per-owner post-execution hooks.
 
 After a routine finishes, its report can be delivered to extra destinations:
-    - Telegram — the raw interactive .html report as a document to arbitrary
-      chat ids / groups.
+    - Telegram — the raw interactive .html report as a document.
 
-Config is a persistent preset per routine name, stored in
-``data/routine_hooks.json``, keyed by the routine name as known to each engine
-(global base name, or ``slug/name`` for agent routines). It applies to every
-execution of that routine (manual, scheduled, or after restart).
+Config is a persistent preset stored in ``data/routine_hooks.json``, keyed by
+the routine name as known to each engine (global base name, or ``slug/name``
+for agent routines) and then by the id of the user who configured it. It
+applies to every execution of that routine *by that owner* (manual, scheduled,
+or after restart).
 
 ``trigger`` controls when to fire: "success" (default), "always", or "failure".
+
+Ownership (SEC-152). Hooks used to be global and unowned: one config per
+routine name, writable by any approved user, fired on every run by anyone. That
+made them a silent exfiltration channel — attach a hook to a routine the admin
+schedules against a server you have no access to and its full report (portfolio
+value, PnL, positions) lands in your Telegram on every run. So now:
+
+    - a hook belongs to the user who saved it, and only that user reads or
+      overwrites it;
+    - a run fires only the hooks owned by the user who started the run
+      (``user_id`` in the RoutineStore instance meta);
+    - recipients are bounded by what the owner controls — their own Telegram
+      chat — both when saving and again at dispatch, so a hooks file written by
+      an older version (or by hand) cannot deliver anywhere either.
+
+Admins are the exception at both ends: they already reach every server and
+every instance, and they are the ones who route reports into shared groups, so
+they may target any chat id.
+
+Legacy entries written before ownership existed are kept verbatim under the
+``_UNOWNED`` key: they are nobody's, so they no longer fire for everyone —
+only an admin's runs trigger them, and an admin saving that routine's hooks
+adopts them under their own id.
 """
 
 from __future__ import annotations
@@ -29,22 +52,80 @@
 # Valid trigger conditions.
 _TRIGGERS = ("success", "always", "failure")
 
+# Owner key for hooks saved before ownership existed. They are nobody's: kept
+# on disk, readable and adoptable by an admin, fired only for an admin's runs.
+_UNOWNED = ""
+
+
+class ForbiddenRecipient(Exception):
+    """Raised when a hook targets a chat its owner is not allowed to reach."""
+
+
+# ── Ownership ──
+
+
+def _is_admin(user_id: int | None) -> bool:
+    if not user_id:
+        return False
+    try:
+        from config_manager import get_config_manager
+
+        return bool(get_config_manager().is_admin(int(user_id)))
+    except Exception:  # noqa: BLE001
+        # Fail closed: an unresolvable role is not an admin.
+        logger.warning("Could not resolve role for user %s", user_id, exc_info=True)
+        return False
+
+
+def _owner_key(user_id: int | None) -> str:
+    return str(user_id) if user_id else _UNOWNED
+
+
+def _allowed_recipient(chat_id: str, user_id: int | None) -> bool:
+    """Whether ``user_id`` may have this routine's reports delivered to ``chat_id``.
+
+    A plain user only reaches their own Telegram chat — the one Condor already
+    talks to them in — so a hook can never carry a report somewhere its owner
+    does not control. Admins may target any chat: they route reports into
+    shared groups and channels, which is what the pre-SEC-152 hooks did.
+    """
+    if not user_id:
+        return False
+    return chat_id == str(user_id) or _is_admin(user_id)
+
 
 # ── Persistence ──
 
 
-def _read_all() -> dict[str, dict]:
+def _normalize(entry: Any) -> dict[str, dict]:
+    """Coerce one stored routine entry into ``{owner_key: config}``.
+
+    Pre-SEC-152 files hold a bare config per routine name. Those entries are
+    preserved as-is under :data:`_UNOWNED` rather than dropped or reassigned to
+    a made-up owner — losing an admin's delivery config silently would be as
+    bad a surprise as leaving it firing for everyone.
+    """
+    if not isinstance(entry, dict):
+        return {}
+    if "telegram" in entry or "trigger" in entry or "email" in entry:
+        return {_UNOWNED: entry}
+    return {str(k): v for k, v in entry.items() if isinstance(v, dict)}
+
+
+def _read_all() -> dict[str, dict[str, dict]]:
     if not _HOOKS_FILE.exists():
         return {}
     try:
         data = json.loads(_HOOKS_FILE.read_text())
-        return data if isinstance(data, dict) else {}
+        if not isinstance(data, dict):
+            return {}
+        return {name: _normalize(entry) for name, entry in data.items()}
     except Exception:  # noqa: BLE001
         logger.warning("Failed to read %s; treating as empty", _HOOKS_FILE)
         return {}
 
 
-def _write_all(data: dict[str, dict]) -> None:
+def _write_all(data: dict[str, dict[str, dict]]) -> None:
     atomic_write_json(_HOOKS_FILE, data, indent=2)
 
 
@@ -55,30 +136,61 @@ def _default_config() -> dict:
     }
 
 
-def load_hooks(routine_name: str) -> dict | None:
-    """Return the hook config for a routine, or None if none set."""
-    return _read_all().get(routine_name)
+def load_hooks(routine_name: str, user_id: int | None) -> dict | None:
+    """Return ``user_id``'s hook config for a routine, or None if none set.
 
+    An admin with no config of their own inherits the legacy unowned entry, so
+    the pre-SEC-152 hooks stay visible in the dashboard and are adopted the
+    next time they are saved.
+    """
+    owners = _read_all().get(routine_name) or {}
+    own = owners.get(_owner_key(user_id))
+    if own is not None:
+        return own
+    if _is_admin(user_id):
+        return owners.get(_UNOWNED)
+    return None
+
+
+def save_hooks(routine_name: str, cfg: dict, user_id: int | None) -> dict:
+    """Validate and persist ``user_id``'s hook config. Returns the stored config.
+
+    Raises :class:`ForbiddenRecipient` if a chat id is not one the owner may
+    deliver to.
+    """
+    if not user_id:
+        raise ForbiddenRecipient("Hooks need an owner")
 
-def save_hooks(routine_name: str, cfg: dict) -> dict:
-    """Validate and persist the hook config for a routine. Returns the stored config."""
     clean = _default_config()
 
     tg = cfg.get("telegram") or {}
     chat_ids = [str(c).strip() for c in (tg.get("chat_ids") or []) if str(c).strip()]
     # Light validation: chat ids are integers (may be negative for groups).
     chat_ids = [c for c in chat_ids if c.lstrip("-").isdigit()]
+    forbidden = [c for c in chat_ids if not _allowed_recipient(c, user_id)]
+    if forbidden:
+        raise ForbiddenRecipient(
+            "You can only send routine reports to your own chat "
+            f"({user_id}); not allowed: {', '.join(forbidden)}"
+        )
     clean["telegram"] = {"enabled": bool(tg.get("enabled")), "chat_ids": chat_ids}
 
     trigger = cfg.get("trigger")
     clean["trigger"] = trigger if trigger in _TRIGGERS else "success"
 
     data = _read_all()
+    owners = data.setdefault(routine_name, {})
+    # An admin writing this routine's hooks adopts whatever the pre-ownership
+    # file left behind, so the legacy entry stops shadowing their own config.
+    if _is_admin(user_id):
+        owners.pop(_UNOWNED, None)
     # If nothing is enabled/configured, drop the entry to keep the file tidy.
     if not clean["telegram"]["enabled"] and not chat_ids:
-        data.pop(routine_name, None)
+        owners.pop(_owner_key(user_id), None)
     else:
-        data[routine_name] = clean
+        owners[_owner_key(user_id)] = clean
+    if not owners:
+        data.pop(routine_name, None)
     _write_all(data)
     return clean
 
@@ -131,13 +243,19 @@ async def dispatch(
     *,
     failed: bool,
     bot: Any | None,
+    owner_id: int | None,
 ) -> None:
-    """Send the configured Telegram notification for a routine.
+    """Send the Telegram notification ``owner_id`` configured for a routine.
+
+    ``owner_id`` is who started this run — ``user_id`` in the RoutineStore
+    instance meta, the chat id on the Telegram path. Only that user's hooks
+    fire, so a run never delivers its report to someone else's destinations
+    (SEC-152). A run with no owner fires nothing.
 
     Never raises — failures are logged so a broken notification can't break the
     routine run itself.
     """
-    cfg = load_hooks(routine_name)
+    cfg = load_hooks(routine_name, owner_id)
     if not cfg:
         return
 
@@ -146,7 +264,15 @@ async def dispatch(
         return
 
     tg_cfg = cfg.get("telegram") or {}
-    if not (tg_cfg.get("enabled") and tg_cfg.get("chat_ids") and bot is not None):
+    # Re-check recipients here, not only at save time: a hooks file written by
+    # a pre-SEC-152 build (or edited by hand) must not be able to deliver
+    # anywhere its owner could not have configured today.
+    chat_ids = [
+        c
+        for c in (tg_cfg.get("chat_ids") or [])
+        if _allowed_recipient(str(c), owner_id)
+    ]
+    if not (tg_cfg.get("enabled") and chat_ids and bot is not None):
         return
 
     # Send the raw interactive report HTML (live Plotly charts), or a minimal
@@ -174,7 +300,7 @@ async def dispatch(
         slug += ".html"
 
     doc_bytes = html.encode("utf-8")
-    for chat_id in tg_cfg["chat_ids"]:
+    for chat_id in chat_ids:
         try:
             import io
 
diff --git a/condor/routine_store.py b/condor/routine_store.py
index fbeaf561..97051cc5 100644
--- a/condor/routine_store.py
+++ b/condor/routine_store.py
@@ -331,6 +331,8 @@ async def _fire_hooks(
                 report_id,
                 failed=failed,
                 bot=(self._bot or _http_bot),
+                # Only the hooks of whoever started this run fire (SEC-152).
+                owner_id=meta.get("user_id"),
             )
         except Exception as e:
             logger.error(
diff --git a/condor/web/routes/routines.py b/condor/web/routes/routines.py
index bec3c560..766b99d7 100644
--- a/condor/web/routes/routines.py
+++ b/condor/web/routes/routines.py
@@ -266,8 +266,12 @@ async def stop_instance(instance_id: str, user: WebUser = Depends(get_current_us
 
 @router.get("/{routine_name:path}/hooks")
 async def get_hooks(routine_name: str, user: WebUser = Depends(get_current_user)):
-    """Get the post-execution hook config for a routine."""
-    cfg = routine_hooks.load_hooks(routine_name)
+    """Get the caller's post-execution hook config for a routine.
+
+    Hooks are per-owner (SEC-152), so this never exposes another user's
+    delivery destinations: a caller who configured none gets the empty default.
+    """
+    cfg = routine_hooks.load_hooks(routine_name, user.id)
     return cfg if cfg is not None else routine_hooks._default_config()
 
 
@@ -277,8 +281,11 @@ async def put_hooks(
     body: HooksRequest,
     user: WebUser = Depends(get_current_user),
 ):
-    """Save the post-execution hook config for a routine."""
-    return routine_hooks.save_hooks(routine_name, body.model_dump())
+    """Save the caller's post-execution hook config for a routine."""
+    try:
+        return routine_hooks.save_hooks(routine_name, body.model_dump(), user.id)
+    except routine_hooks.ForbiddenRecipient as e:
+        raise HTTPException(status_code=403, detail=str(e))
 
 
 @router.get("/options/{source}")
diff --git a/handlers/routines/__init__.py b/handlers/routines/__init__.py
index 5a02b1e8..09d0c44c 100644
--- a/handlers/routines/__init__.py
+++ b/handlers/routines/__init__.py
@@ -314,6 +314,9 @@ async def _execute_routine(
             report_id,
             failed=failed,
             bot=context.bot,
+            # The chat that started the run owns its hooks — the same identity
+            # user_data is keyed by, and the one the store records (SEC-152).
+            owner_id=chat_id,
         )
     except Exception as e:
         logger.error(
diff --git a/tests/test_routine_hooks_ownership.py b/tests/test_routine_hooks_ownership.py
new file mode 100644
index 00000000..6665ca09
--- /dev/null
+++ b/tests/test_routine_hooks_ownership.py
@@ -0,0 +1,264 @@
+"""Tests for SEC-152: routine hooks are owned, and only their owner's runs fire them.
+
+Hooks used to be one global config per routine name: any approved user could
+PUT one, read anyone else's, and — because dispatch keyed only on the routine
+name — receive the full interactive report (portfolio value, PnL, positions)
+of every run of that routine by anyone, forever. These tests pin the three
+halves of the fix: the REST endpoints are per-owner, dispatch fires only the
+run owner's hooks, and no hook can deliver to a chat its owner does not
+control (checked again at dispatch, so a file written by an older build is
+defused too).
+"""
+
+import asyncio
+import json
+
+import pytest
+from fastapi import FastAPI
+from starlette.testclient import TestClient
+
+import condor.routine_hooks as hooks
+import condor.web.routes.routines as routines_module
+from condor.web.auth import get_current_user
+from condor.web.models import WebUser
+
+OWNER = WebUser(id=111, username="owner", first_name="O", role="user")
+STRANGER = WebUser(id=222, username="stranger", first_name="S", role="user")
+ADMIN = WebUser(id=999, username="admin", first_name="A", role="admin")
+
+ROUTINE = "brigado/bot_report"
+GROUP_CHAT = "-1003602724903"
+
+
+class FakeConfigManager:
+    def is_admin(self, user_id):
+        return user_id == ADMIN.id
+
+
+@pytest.fixture(autouse=True)
+def hooks_file(tmp_path, monkeypatch):
+    """Point the hook store at a throwaway file and stub the role lookup."""
+    import config_manager
+
+    path = tmp_path / "routine_hooks.json"
+    monkeypatch.setattr(hooks, "_HOOKS_FILE", path)
+    monkeypatch.setattr(config_manager, "get_config_manager", FakeConfigManager)
+    return path
+
+
+def write_raw(path, data):
+    path.write_text(json.dumps(data))
+
+
+def read_raw(path):
+    return json.loads(path.read_text())
+
+
+@pytest.fixture
+def make_client():
+    def _make(user: WebUser):
+        app = FastAPI()
+        app.include_router(routines_module.router)
+        app.dependency_overrides[get_current_user] = lambda: user
+        return TestClient(app)
+
+    return _make
+
+
+def hook_body(chat_ids, trigger="success"):
+    return {"telegram": {"enabled": True, "chat_ids": chat_ids}, "trigger": trigger}
+
+
+class FakeBot:
+    def __init__(self):
+        self.sent = []
+
+    async def send_document(self, chat_id, document):
+        self.sent.append(chat_id)
+
+
+class FakeResult:
+    text = "portfolio: $1,234,567"
+
+
+def fire(routine_name, owner_id, bot, failed=False):
+    """Run one routine's post-execution hooks as ``owner_id``."""
+    asyncio.run(
+        hooks.dispatch(
+            routine_name, FakeResult(), None, failed=failed, bot=bot, owner_id=owner_id
+        )
+    )
+
+
+# ── REST: reading someone else's hooks ──
+
+
+def test_stranger_cannot_read_another_users_hooks(make_client, hooks_file):
+    hooks.save_hooks(ROUTINE, hook_body([str(OWNER.id)]), OWNER.id)
+
+    resp = make_client(STRANGER).get(f"/routines/{ROUTINE}/hooks")
+
+    assert resp.status_code == 200
+    # The stranger sees their own (empty) config, never the owner's chat ids.
+    assert resp.json() == hooks._default_config()
+    assert str(OWNER.id) not in json.dumps(resp.json())
+
+
+def test_owner_reads_back_their_own_hooks(make_client):
+    hooks.save_hooks(ROUTINE, hook_body([str(OWNER.id)]), OWNER.id)
+
+    resp = make_client(OWNER).get(f"/routines/{ROUTINE}/hooks")
+
+    assert resp.json()["telegram"]["chat_ids"] == [str(OWNER.id)]
+
+
+# ── REST: writing over someone else's hooks ──
+
+
+def test_stranger_put_does_not_overwrite_the_owners_hooks(make_client, hooks_file):
+    hooks.save_hooks(ROUTINE, hook_body([str(OWNER.id)]), OWNER.id)
+
+    resp = make_client(STRANGER).put(
+        f"/routines/{ROUTINE}/hooks", json=hook_body([str(STRANGER.id)])
+    )
+
+    assert resp.status_code == 200
+    assert hooks.load_hooks(ROUTINE, OWNER.id)["telegram"]["chat_ids"] == [
+        str(OWNER.id)
+    ]
+    assert hooks.load_hooks(ROUTINE, STRANGER.id)["telegram"]["chat_ids"] == [
+        str(STRANGER.id)
+    ]
+
+
+def test_put_rejects_a_chat_the_caller_does_not_control(make_client, hooks_file):
+    resp = make_client(STRANGER).put(
+        f"/routines/{ROUTINE}/hooks", json=hook_body([str(OWNER.id), GROUP_CHAT])
+    )
+
+    assert resp.status_code == 403
+    assert not hooks_file.exists() or read_raw(hooks_file) == {}
+
+
+def test_admin_may_target_a_group(make_client, hooks_file):
+    resp = make_client(ADMIN).put(
+        f"/routines/{ROUTINE}/hooks", json=hook_body([GROUP_CHAT])
+    )
+
+    assert resp.status_code == 200
+    assert hooks.load_hooks(ROUTINE, ADMIN.id)["telegram"]["chat_ids"] == [GROUP_CHAT]
+
+
+# ── Dispatch: only the run owner's hooks fire ──
+
+
+def test_dispatch_fires_for_the_owners_own_run():
+    hooks.save_hooks(ROUTINE, hook_body([str(OWNER.id)]), OWNER.id)
+    bot = FakeBot()
+
+    fire(ROUTINE, OWNER.id, bot)
+
+    assert bot.sent == [OWNER.id]
+
+
+def test_a_strangers_hook_never_sees_another_users_run():
+    """The exfiltration channel itself: hook the routine, wait for someone else."""
+    hooks.save_hooks(ROUTINE, hook_body([str(STRANGER.id)]), STRANGER.id)
+    bot = FakeBot()
+
+    fire(ROUTINE, OWNER.id, bot)
+    fire(ROUTINE, ADMIN.id, bot)
+
+    assert bot.sent == []
+
+
+def test_dispatch_sends_nothing_for_an_unowned_run():
+    hooks.save_hooks(ROUTINE, hook_body([str(OWNER.id)]), OWNER.id)
+    bot = FakeBot()
+
+    fire(ROUTINE, None, bot)
+    fire(ROUTINE, 0, bot)
+
+    assert bot.sent == []
+
+
+def test_dispatch_drops_a_chat_the_owner_does_not_control(hooks_file):
+    """A hooks file from a pre-SEC-152 build must not deliver anywhere new."""
+    write_raw(
+        hooks_file,
+        {ROUTINE: {str(OWNER.id): hook_body([str(OWNER.id), GROUP_CHAT])}},
+    )
+    bot = FakeBot()
+
+    fire(ROUTINE, OWNER.id, bot)
+
+    assert bot.sent == [OWNER.id]
+
+
+# ── Migration: hooks written before ownership existed ──
+
+
+def test_legacy_flat_entry_is_preserved_on_disk(hooks_file):
+    write_raw(hooks_file, {ROUTINE: hook_body([GROUP_CHAT])})
+
+    hooks.save_hooks("other_routine", hook_body([str(OWNER.id)]), OWNER.id)
+
+    stored = read_raw(hooks_file)
+    assert stored[ROUTINE][""]["telegram"]["chat_ids"] == [GROUP_CHAT]
+
+
+def test_legacy_entry_no_longer_fires_for_everyone(hooks_file):
+    write_raw(hooks_file, {ROUTINE: hook_body([GROUP_CHAT])})
+    bot = FakeBot()
+
+    fire(ROUTINE, STRANGER.id, bot)
+    assert bot.sent == []
+
+    # The admin's runs keep delivering exactly as before the change.
+    fire(ROUTINE, ADMIN.id, bot)
+    assert bot.sent == [int(GROUP_CHAT)]
+
+
+def test_legacy_entry_is_hidden_from_non_admins(hooks_file, make_client):
+    write_raw(hooks_file, {ROUTINE: hook_body([GROUP_CHAT])})
+
+    assert make_client(STRANGER).get(f"/routines/{ROUTINE}/hooks").json() == (
+        hooks._default_config()
+    )
+    assert make_client(ADMIN).get(f"/routines/{ROUTINE}/hooks").json()["telegram"][
+        "chat_ids"
+    ] == [GROUP_CHAT]
+
+
+def test_admin_save_adopts_the_legacy_entry(hooks_file):
+    write_raw(hooks_file, {ROUTINE: hook_body([GROUP_CHAT])})
+
+    hooks.save_hooks(ROUTINE, hook_body([GROUP_CHAT, str(ADMIN.id)]), ADMIN.id)
+
+    stored = read_raw(hooks_file)
+    assert "" not in stored[ROUTINE]
+    assert stored[ROUTINE][str(ADMIN.id)]["telegram"]["chat_ids"] == [
+        GROUP_CHAT,
+        str(ADMIN.id),
+    ]
+
+
+# ── The store hands dispatch the run's owner ──
+
+
+def test_fire_hooks_passes_the_instance_owner(monkeypatch):
+    from condor.routine_store import RoutineStore
+
+    store = RoutineStore()
+    store._instances["i1"] = {"routine_name": ROUTINE, "user_id": OWNER.id}
+
+    seen = {}
+
+    async def fake_dispatch(name, result, report_id, *, failed, bot, owner_id):
+        seen["name"] = name
+        seen["owner_id"] = owner_id
+
+    monkeypatch.setattr(hooks, "dispatch", fake_dispatch)
+    asyncio.run(store._fire_hooks("i1", FakeResult(), None, False))
+
+    assert seen == {"name": ROUTINE, "owner_id": OWNER.id}

From 66fbb84ad0062d54e685d7836590c8dfffe84766 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Fri, 14 Aug 2026 16:09:26 +0300
Subject: [PATCH 075/116] (fix) SEC-159: gate routine field options on server
 access
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

GET /routines/options/{source} built a client for whatever ?server= it was
given and returned that server's controller config ids, with no access check —
the same cross-server IDOR as SEC-007/019/045, on the one ?server= route
SEC-147 left alone because fixing it is a behaviour change, not a refactor.

It now takes require_server_access_query, the dependency SEC-147 introduced for
this exact shape. server loses its "local" default (the dependency declares it
required); the dashboard's only caller already gates the request on a selected
server and always sends it.

KNOWN_GAPS in the structural sweep is empty as a result, so the route is now
enforced by that test rather than excused by it.
---
 condor/web/routes/routines.py              | 13 +++--
 tests/test_routines_access.py              | 57 ++++++++++++++++++++++
 tests/test_web_server_access_dependency.py |  9 ++--
 3 files changed, 71 insertions(+), 8 deletions(-)

diff --git a/condor/web/routes/routines.py b/condor/web/routes/routines.py
index 766b99d7..b033f60e 100644
--- a/condor/web/routes/routines.py
+++ b/condor/web/routes/routines.py
@@ -18,6 +18,7 @@
     check_server_access,
     get_current_user,
     require_server_access_by_server_name,
+    require_server_access_query,
 )
 from condor.web.models import WebUser
 from config_manager import get_config_manager
@@ -291,10 +292,16 @@ async def put_hooks(
 @router.get("/options/{source}")
 async def get_field_options(
     source: str,
-    server: str = Query("local", alias="server"),
-    user: WebUser = Depends(get_current_user),
+    server: str = Query(...),
+    user: WebUser = Depends(require_server_access_query),
 ):
-    """Return dynamic options for routine config fields (e.g. controller_configs)."""
+    """Return dynamic options for routine config fields (e.g. controller_configs).
+
+    Server-scoped: ``controller_configs`` reads the named server's controller
+    configs, so the caller must have access to it (SEC-159). ``server`` used to
+    default to ``"local"``; the guard makes it required, which is what the
+    dashboard has always sent anyway.
+    """
     if source == "controller_configs":
         try:
             cm = get_config_manager()
diff --git a/tests/test_routines_access.py b/tests/test_routines_access.py
index 9ff6d065..0cfbe76c 100644
--- a/tests/test_routines_access.py
+++ b/tests/test_routines_access.py
@@ -70,13 +70,29 @@ async def start_continuous(
         return "inst-cont"
 
 
+class FakeControllers:
+    async def list_controller_configs(self):
+        return [{"id": "pmm_b"}, {"id": "pmm_a"}]
+
+
+class FakeClient:
+    controllers = FakeControllers()
+
+
 class FakeConfigManager:
     def __init__(self, allowed):
         self._allowed = allowed  # set of (user_id, server_name)
+        self.clients_built = []
 
     def has_server_access(self, user_id, server_name, *args, **kwargs):
         return (user_id, server_name) in self._allowed
 
+    async def get_client(self, server_name):
+        # A denied request must never reach this: building the client is what
+        # reads the other user's server (SEC-159).
+        self.clients_built.append(server_name)
+        return FakeClient()
+
 
 @pytest.fixture
 def client_and_store(monkeypatch):
@@ -92,6 +108,19 @@ def client_and_store(monkeypatch):
     return TestClient(app), store
 
 
+@pytest.fixture
+def client_and_cm(monkeypatch):
+    """Same wiring, exposing the config manager for the field-options route."""
+    cm = FakeConfigManager(allowed={(USER.id, OWNED_SERVER)})
+    monkeypatch.setattr(routines_module, "get_config_manager", lambda: cm)
+    monkeypatch.setattr("condor.web.auth.get_config_manager", lambda: cm)
+
+    app = FastAPI()
+    app.include_router(routines_module.router)
+    app.dependency_overrides[get_current_user] = lambda: USER
+    return TestClient(app), cm
+
+
 # ── Denied: no access to the target server ──
 
 
@@ -293,3 +322,31 @@ def test_a_dashboard_run_has_no_conversation_behind_it(client_and_store, monkeyp
         json={"routine_name": "some_routine", "server_name": OWNED_SERVER},
     )
     assert store.conversations == [""]
+
+
+# ── SEC-159: the field-options route is server-scoped too ──
+
+
+def test_field_options_denied_on_foreign_server(client_and_cm):
+    """``?server=`` on /options/{source} used to enumerate any server's configs."""
+    client, cm = client_and_cm
+    resp = client.get(f"/routines/options/controller_configs?server={FOREIGN_SERVER}")
+    assert resp.status_code == 403
+    assert resp.json()["detail"] == "No access"
+    assert cm.clients_built == []
+
+
+def test_field_options_allowed_on_owned_server(client_and_cm):
+    client, cm = client_and_cm
+    resp = client.get(f"/routines/options/controller_configs?server={OWNED_SERVER}")
+    assert resp.status_code == 200
+    assert resp.json() == {"options": ["pmm_a", "pmm_b"]}
+    assert cm.clients_built == [OWNED_SERVER]
+
+
+def test_field_options_requires_an_explicit_server(client_and_cm):
+    """The guard makes ``server`` required; it no longer falls back to "local"."""
+    client, cm = client_and_cm
+    resp = client.get("/routines/options/controller_configs")
+    assert resp.status_code == 422
+    assert cm.clients_built == []
diff --git a/tests/test_web_server_access_dependency.py b/tests/test_web_server_access_dependency.py
index cd9c2e7a..2e68f076 100644
--- a/tests/test_web_server_access_dependency.py
+++ b/tests/test_web_server_access_dependency.py
@@ -70,11 +70,9 @@
 # Routes that read a server but have never had an access check. NOT a licence:
 # each is a live gap, listed so the sweep above stays green while they are
 # fixed under their own item rather than silently smuggled into SEC-147.
-KNOWN_GAPS: dict[tuple[str, str], str] = {
-    ("GET", "/api/v1/routines/options/{source}"): (
-        "reads controller configs off any ?server= with no access check"
-    ),
-}
+# Empty since SEC-159 closed the last one (GET /routines/options/{source}) —
+# keep it that way: a new entry here is a hole shipped on purpose.
+KNOWN_GAPS: dict[tuple[str, str], str] = {}
 
 # The body-param sites: "<module>.<function>" → the attribute holding the name.
 # A path/query dependency cannot see a request body, so these call the shared
@@ -273,6 +271,7 @@ def client(app, deny):
         # aliased ?server= query param (settings.py)
         ("GET", f"/api/v1/settings/gateway/status?server={FOREIGN}"),
         ("GET", f"/api/v1/settings/credentials?server={FOREIGN}"),
+        ("GET", f"/api/v1/routines/options/controller_configs?server={FOREIGN}"),
         # {server_name} path param
         ("POST", f"/api/v1/routines/servers/{FOREIGN}/some_routine/run"),
     ],

From 28888bee91139ffb4f52e6e74c808729a70ce9ae Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Fri, 14 Aug 2026 16:17:21 +0300
Subject: [PATCH 076/116] (refactor) archived_pnl: extract the shared per-trade
 loop from both PnL modes

_calculate_pnl_average_cost and _calculate_pnl_open_close were structural
twins: identical accumulator setup, timestamp sort, field extraction,
fee/volume accumulation, cumulative-point append and result dict, with only
the ~40-line accounting core differing. Any fix to the shared frame had to be
applied twice, and the two copies had already drifted.

The frame now lives once in _walk_trades(). Each mode is an accounting object
that owns its own state, counters and log summary, and returns a _TradeOutcome
per trade. The deltas are split deliberately: running_delta always lands on the
running total, while pair_delta is credited to pnl_by_pair only when it is not
None - which is what lets average cost keep charging the fee on an unmatched
SELL to total_pnl without inventing a pnl_by_pair entry, exactly as before.

No arithmetic changed. The genuine divergences between the modes are preserved
and now documented rather than implied: average cost clamps a sell to the
inventory on hand while open/close realizes the full trade amount; an unmatched
SELL is charged its fee while an unmatched CLOSE is a complete no-op; open/close
deletes a fully closed position while average cost zeroes the record in place.

Characterization tests were written first, against the unmodified code, over 21
fixtures covering both modes plus zero quantities, missing fields, unparseable
and epoch timestamps, oversells, partial fills and reopens. They pin the exact
floats and the full cumulative series and pass unchanged after the refactor. A
throwaway differential fuzz over 40k random trade lists also found no
divergence from the previous implementation.
---
 condor/archived_pnl.py                      | 320 ++++++------
 tests/test_archived_pnl_characterization.py | 522 ++++++++++++++++++++
 2 files changed, 696 insertions(+), 146 deletions(-)
 create mode 100644 tests/test_archived_pnl_characterization.py

diff --git a/condor/archived_pnl.py b/condor/archived_pnl.py
index 4bc96867..8eb82b6a 100644
--- a/condor/archived_pnl.py
+++ b/condor/archived_pnl.py
@@ -13,7 +13,7 @@
 import logging
 from collections import defaultdict
 from datetime import datetime
-from typing import Any
+from typing import Any, NamedTuple
 
 logger = logging.getLogger(__name__)
 
@@ -89,74 +89,78 @@ def calculate_pnl_from_trades(trades: list[dict[str, Any]]) -> dict[str, Any]:
         return _calculate_pnl_open_close(trades)
 
 
-def _calculate_pnl_average_cost(trades: list[dict[str, Any]]) -> dict[str, Any]:
-    """
-    Calculate PnL using average cost basis for spot/market making trades.
+class _ParsedTrade(NamedTuple):
+    """One trade row after the field extraction every mode shares."""
+
+    pair: str
+    amount: float
+    price: float
+    trade_type: str
+    position: str
+    fee: float
+    timestamp: Any
+
+
+class _TradeOutcome(NamedTuple):
+    """What an accounting mode decided about one trade.
 
-    This handles NIL position trades where:
-    - BUY adds to inventory at that price
-    - SELL realizes PnL based on weighted average cost of inventory
+    ``running_delta`` is added to the running total unconditionally.
+    ``pair_delta`` is credited to ``pnl_by_pair`` only when it is not ``None``,
+    so a mode that touches the running total *without* attributing the amount
+    to a pair (average cost does exactly that for the fee on an unmatched SELL)
+    does not create a spurious ``pnl_by_pair`` entry.
     """
-    # Track inventory per trading pair using average cost
-    # inventory = {amount: float, total_cost: float}
-    inventory: dict[str, dict[str, float]] = {}
 
-    pnl_by_pair: dict[str, float] = defaultdict(float)
-    cumulative_pnl: list[dict[str, Any]] = []
-    running_pnl = 0.0
-    total_fees = 0.0
-    total_volume = 0.0
+    running_delta: float = 0.0
+    pair_delta: float | None = None
 
-    # Debug counters
-    buy_count = 0
-    sell_count = 0
-    realized_trades = 0
 
-    # Sort trades by timestamp
-    sorted_trades = sorted(trades, key=lambda t: t.get("timestamp", 0))
+_NO_CHANGE = _TradeOutcome()
 
-    for trade in sorted_trades:
-        pair = trade.get("trading_pair", "Unknown")
-        amount = float(trade.get("amount", 0))
-        price = float(trade.get("price", 0))
-        trade_type = trade.get("trade_type", "").upper()
-        fee = float(trade.get("trade_fee_in_quote", 0))
-        timestamp = trade.get("timestamp", 0)
 
-        total_fees += fee
-        total_volume += amount * price
+class _AverageCostAccounting:
+    """Average cost basis inventory tracking, for spot / market making (NIL).
 
-        # Parse timestamp for cumulative chart
-        ts = parse_timestamp(timestamp)
+    BUY adds to inventory at its price; SELL realizes against the weighted
+    average cost of the inventory on hand, clamped to that inventory. A SELL
+    with no inventory (a short) is not modelled: only its fee is charged, and
+    only to the running total.
+    """
 
+    def __init__(self) -> None:
+        # inventory = {amount: float, total_cost: float}
+        self.inventory: dict[str, dict[str, float]] = {}
+        self.buy_count = 0
+        self.sell_count = 0
+        self.realized_trades = 0
+
+    def __call__(self, trade: _ParsedTrade) -> _TradeOutcome:
         # Initialize inventory for this pair if needed
-        if pair not in inventory:
-            inventory[pair] = {"amount": 0.0, "total_cost": 0.0}
+        if trade.pair not in self.inventory:
+            self.inventory[trade.pair] = {"amount": 0.0, "total_cost": 0.0}
 
-        inv = inventory[pair]
+        inv = self.inventory[trade.pair]
 
-        if trade_type == "BUY":
-            buy_count += 1
+        if trade.trade_type == "BUY":
+            self.buy_count += 1
             # Add to inventory at this price
-            inv["amount"] += amount
-            inv["total_cost"] += amount * price
+            inv["amount"] += trade.amount
+            inv["total_cost"] += trade.amount * trade.price
+            return _NO_CHANGE
 
-        elif trade_type == "SELL":
-            sell_count += 1
+        if trade.trade_type == "SELL":
+            self.sell_count += 1
             # Realize PnL if we have inventory
             if inv["amount"] > 0:
-                realized_trades += 1
+                self.realized_trades += 1
                 # Calculate average cost of inventory
                 avg_cost = inv["total_cost"] / inv["amount"] if inv["amount"] > 0 else 0
 
                 # Determine how much we can actually sell from inventory
-                sell_amount = min(amount, inv["amount"])
+                sell_amount = min(trade.amount, inv["amount"])
 
                 # PnL = (sell_price - avg_cost) * amount - fee
-                pnl = (price - avg_cost) * sell_amount - fee
-
-                pnl_by_pair[pair] += pnl
-                running_pnl += pnl
+                pnl = (trade.price - avg_cost) * sell_amount - trade.fee
 
                 # Reduce inventory
                 if sell_amount >= inv["amount"]:
@@ -168,143 +172,157 @@ def _calculate_pnl_average_cost(trades: list[dict[str, Any]]) -> dict[str, Any]:
                     ratio = sell_amount / inv["amount"]
                     inv["amount"] -= sell_amount
                     inv["total_cost"] -= inv["total_cost"] * ratio
-            else:
-                # Short selling (no inventory) - track as negative PnL for now
-                # This means we're selling something we don't have (going short)
-                # For simplicity, just count fees
-                running_pnl -= fee
 
-        # Record cumulative PnL point for charting
-        if ts:
-            cumulative_pnl.append(
-                {
-                    "timestamp": ts,
-                    "pnl": running_pnl,
-                    "pair": pair,
-                }
-            )
+                return _TradeOutcome(running_delta=pnl, pair_delta=pnl)
 
-    logger.info(
-        f"PnL calculation (avg cost): {len(trades)} trades, {buy_count} BUY, {sell_count} SELL, "
-        f"{realized_trades} realized, total_pnl=${running_pnl:.4f}"
-    )
+            # Short selling (no inventory) - track as negative PnL for now
+            # This means we're selling something we don't have (going short)
+            # For simplicity, just count fees. Note the fee hits the running
+            # total but is deliberately NOT attributed to pnl_by_pair.
+            return _TradeOutcome(running_delta=-trade.fee)
 
-    return {
-        "total_pnl": running_pnl,
-        "total_fees": total_fees,
-        "pnl_by_pair": dict(pnl_by_pair),
-        "cumulative_pnl": cumulative_pnl,
-        "total_volume": total_volume,
-    }
+        return _NO_CHANGE
 
+    def summary(self, trade_count: int, running_pnl: float) -> str:
+        return (
+            f"PnL calculation (avg cost): {trade_count} trades, {self.buy_count} BUY, "
+            f"{self.sell_count} SELL, {self.realized_trades} realized, "
+            f"total_pnl=${running_pnl:.4f}"
+        )
 
-def _calculate_pnl_open_close(trades: list[dict[str, Any]]) -> dict[str, Any]:
-    """
-    Calculate PnL using OPEN/CLOSE position tracking for perpetual futures.
 
-    For perpetual futures:
-    - OPEN trades establish positions (long or short)
-    - CLOSE trades realize PnL
-    """
-    # Track positions per trading pair
-    # position = {amount: float, total_cost: float, direction: int (1=long, -1=short)}
-    positions: dict[str, dict[str, Any]] = {}
+class _OpenClosePositionAccounting:
+    """OPEN/CLOSE position tracking, for perpetual futures.
 
-    pnl_by_pair: dict[str, float] = defaultdict(float)
-    cumulative_pnl: list[dict[str, Any]] = []
-    running_pnl = 0.0
-    total_fees = 0.0
-    total_volume = 0.0
-
-    # Debug counters
-    open_count = 0
-    close_count = 0
-    close_with_position = 0
-
-    # Sort trades by timestamp
-    sorted_trades = sorted(trades, key=lambda t: t.get("timestamp", 0))
+    OPEN trades establish or add to a position (long on BUY, short on SELL);
+    CLOSE trades realize PnL against the average entry price. Unlike average
+    cost, a CLOSE realizes its full amount even when that exceeds the position,
+    and a CLOSE with no position is a complete no-op - not even its fee is
+    charged to the running total.
+    """
 
-    for trade in sorted_trades:
-        pair = trade.get("trading_pair", "Unknown")
-        amount = float(trade.get("amount", 0))
-        price = float(trade.get("price", 0))
-        trade_type = trade.get("trade_type", "").upper()  # BUY or SELL
-        position_action = trade.get("position", "").upper()  # OPEN or CLOSE
-        fee = float(trade.get("trade_fee_in_quote", 0))
-        timestamp = trade.get("timestamp", 0)
+    def __init__(self) -> None:
+        # position = {amount: float, total_cost: float, direction: int (1=long, -1=short)}
+        self.positions: dict[str, dict[str, Any]] = {}
+        self.open_count = 0
+        self.close_count = 0
+        self.close_with_position = 0
 
-        total_fees += fee
-        total_volume += amount * price
+    def __call__(self, trade: _ParsedTrade) -> _TradeOutcome:
+        if trade.position == "OPEN":
+            self.open_count += 1
+            # Opening a new position or adding to existing
+            if trade.pair not in self.positions:
+                self.positions[trade.pair] = {
+                    "amount": 0,
+                    "total_cost": 0,
+                    "direction": 0,
+                }
 
-        # Parse timestamp for cumulative chart
-        ts = parse_timestamp(timestamp)
+            pos = self.positions[trade.pair]
+            pos["amount"] += trade.amount
+            pos["total_cost"] += trade.price * trade.amount
+            # 1 = long (BUY), -1 = short (SELL). Recorded for inspection only;
+            # the close side reads trade_type, not this field.
+            pos["direction"] = 1 if trade.trade_type == "BUY" else -1
+            return _NO_CHANGE
 
-        if position_action == "OPEN":
-            open_count += 1
-            # Opening a new position or adding to existing
-            if pair not in positions:
-                positions[pair] = {"amount": 0, "total_cost": 0, "direction": 0}
-
-            pos = positions[pair]
-
-            if trade_type == "BUY":
-                # Opening/adding to long position
-                pos["amount"] += amount
-                pos["total_cost"] += price * amount
-                pos["direction"] = 1
-            else:  # SELL
-                # Opening/adding to short position
-                pos["amount"] += amount
-                pos["total_cost"] += price * amount
-                pos["direction"] = -1
-
-        elif position_action == "CLOSE":
-            close_count += 1
+        if trade.position == "CLOSE":
+            self.close_count += 1
             # Closing a position - realize PnL
-            pos = positions.get(pair)
+            pos = self.positions.get(trade.pair)
 
             if pos and pos["amount"] > 0:
-                close_with_position += 1
+                self.close_with_position += 1
                 # Calculate average entry price
                 avg_entry = pos["total_cost"] / pos["amount"]
 
-                if trade_type == "SELL":
+                if trade.trade_type == "SELL":
                     # Closing long: PnL = (exit - entry) * amount
-                    pnl = (price - avg_entry) * amount
+                    pnl = (trade.price - avg_entry) * trade.amount
                 else:  # BUY
                     # Closing short: PnL = (entry - exit) * amount
-                    pnl = (avg_entry - price) * amount
+                    pnl = (avg_entry - trade.price) * trade.amount
 
                 # Subtract fee from PnL
-                pnl -= fee
-
-                pnl_by_pair[pair] += pnl
-                running_pnl += pnl
+                pnl -= trade.fee
 
                 # Update position
-                if amount >= pos["amount"]:
+                if trade.amount >= pos["amount"]:
                     # Fully closed
-                    del positions[pair]
+                    del self.positions[trade.pair]
                 else:
                     # Partially closed
-                    close_ratio = amount / pos["amount"]
-                    pos["amount"] -= amount
+                    close_ratio = trade.amount / pos["amount"]
+                    pos["amount"] -= trade.amount
                     pos["total_cost"] -= pos["total_cost"] * close_ratio
 
+                return _TradeOutcome(running_delta=pnl, pair_delta=pnl)
+
+            # CLOSE with nothing open: no PnL and, unlike average cost mode,
+            # no fee charged to the running total either.
+            return _NO_CHANGE
+
+        return _NO_CHANGE
+
+    def summary(self, trade_count: int, running_pnl: float) -> str:
+        return (
+            f"PnL calculation (open/close): {trade_count} trades, {self.open_count} OPEN, "
+            f"{self.close_count} CLOSE, {self.close_with_position} CLOSE with matching "
+            f"position, total_pnl=${running_pnl:.4f}"
+        )
+
+
+def _walk_trades(trades: list[dict[str, Any]], accounting) -> dict[str, Any]:
+    """Run the per-trade frame both PnL modes share.
+
+    Sorts by timestamp, extracts the fields, accumulates fees and volume,
+    delegates the accounting decision to ``accounting``, and assembles the
+    cumulative series and the result dict. The accounting object owns all
+    mode-specific state and arithmetic; this function owns none of it.
+    """
+    pnl_by_pair: dict[str, float] = defaultdict(float)
+    cumulative_pnl: list[dict[str, Any]] = []
+    running_pnl = 0.0
+    total_fees = 0.0
+    total_volume = 0.0
+
+    # Sort trades by timestamp
+    sorted_trades = sorted(trades, key=lambda t: t.get("timestamp", 0))
+
+    for trade in sorted_trades:
+        parsed = _ParsedTrade(
+            pair=trade.get("trading_pair", "Unknown"),
+            amount=float(trade.get("amount", 0)),
+            price=float(trade.get("price", 0)),
+            trade_type=trade.get("trade_type", "").upper(),  # BUY or SELL
+            position=trade.get("position", "").upper(),  # OPEN, CLOSE or NIL
+            fee=float(trade.get("trade_fee_in_quote", 0)),
+            timestamp=trade.get("timestamp", 0),
+        )
+
+        total_fees += parsed.fee
+        total_volume += parsed.amount * parsed.price
+
+        # Parse timestamp for cumulative chart
+        ts = parse_timestamp(parsed.timestamp)
+
+        outcome = accounting(parsed)
+        if outcome.pair_delta is not None:
+            pnl_by_pair[parsed.pair] += outcome.pair_delta
+        running_pnl += outcome.running_delta
+
         # Record cumulative PnL point for charting
         if ts:
             cumulative_pnl.append(
                 {
                     "timestamp": ts,
                     "pnl": running_pnl,
-                    "pair": pair,
+                    "pair": parsed.pair,
                 }
             )
 
-    logger.info(
-        f"PnL calculation (open/close): {len(trades)} trades, {open_count} OPEN, {close_count} CLOSE, "
-        f"{close_with_position} CLOSE with matching position, total_pnl=${running_pnl:.4f}"
-    )
+    logger.info(accounting.summary(len(trades), running_pnl))
 
     return {
         "total_pnl": running_pnl,
@@ -313,3 +331,13 @@ def _calculate_pnl_open_close(trades: list[dict[str, Any]]) -> dict[str, Any]:
         "cumulative_pnl": cumulative_pnl,
         "total_volume": total_volume,
     }
+
+
+def _calculate_pnl_average_cost(trades: list[dict[str, Any]]) -> dict[str, Any]:
+    """Calculate PnL using average cost basis for spot/market making trades."""
+    return _walk_trades(trades, _AverageCostAccounting())
+
+
+def _calculate_pnl_open_close(trades: list[dict[str, Any]]) -> dict[str, Any]:
+    """Calculate PnL using OPEN/CLOSE position tracking for perpetual futures."""
+    return _walk_trades(trades, _OpenClosePositionAccounting())
diff --git a/tests/test_archived_pnl_characterization.py b/tests/test_archived_pnl_characterization.py
new file mode 100644
index 00000000..2e08a492
--- /dev/null
+++ b/tests/test_archived_pnl_characterization.py
@@ -0,0 +1,522 @@
+"""Characterization tests for condor.archived_pnl.calculate_pnl_from_trades.
+
+These pin the EXACT current numeric output of both PnL modes (average-cost /
+NIL and OPEN/CLOSE position tracking) over a representative fixture set,
+including the edge cases where the two modes deliberately disagree:
+
+* an unmatched SELL in average-cost mode charges its fee to ``total_pnl`` but
+  NOT to ``pnl_by_pair`` (so ``total_pnl != sum(pnl_by_pair.values())``),
+* an unmatched CLOSE in OPEN/CLOSE mode charges nothing at all,
+* average-cost clamps a sell to the inventory on hand, OPEN/CLOSE realizes the
+  full trade amount even when it exceeds the open position.
+
+The goldens below were captured from the implementation and must not be edited
+to make a refactor pass: they are the contract.
+"""
+
+import pytest
+
+from condor.archived_pnl import (
+    _calculate_pnl_average_cost,
+    _calculate_pnl_open_close,
+    calculate_pnl_from_trades,
+    parse_timestamp,
+)
+
+
+def _trade(ts, pair, side, position, price, amount, fee):
+    return {
+        "timestamp": ts,
+        "trading_pair": pair,
+        "trade_type": side,
+        "position": position,
+        "price": price,
+        "amount": amount,
+        "trade_fee_in_quote": fee,
+    }
+
+
+SCENARIOS: dict[str, list[dict]] = {
+    "empty": [],
+    # ---- average-cost / NIL mode -------------------------------------
+    "nil_buy_sell_full": [
+        _trade("2026-01-01T00:00:00", "SOL-USDC", "BUY", "NIL", 100.0, 10.0, 0.5),
+        _trade("2026-01-01T00:01:00", "SOL-USDC", "SELL", "NIL", 110.0, 10.0, 0.55),
+    ],
+    "nil_partial_and_oversell": [
+        _trade("2026-01-01T00:00:00", "SOL-USDC", "BUY", "NIL", 100.0, 10.0, 0.1),
+        _trade("2026-01-01T00:01:00", "SOL-USDC", "BUY", "NIL", 110.0, 10.0, 0.1),
+        _trade("2026-01-01T00:02:00", "SOL-USDC", "SELL", "NIL", 120.0, 5.0, 0.2),
+        _trade("2026-01-01T00:03:00", "SOL-USDC", "SELL", "NIL", 90.0, 20.0, 0.3),
+        _trade("2026-01-01T00:04:00", "SOL-USDC", "SELL", "NIL", 100.0, 1.0, 0.05),
+    ],
+    "nil_unmatched_sell_first": [
+        _trade("2026-01-01T00:00:00", "SOL-USDC", "SELL", "NIL", 100.0, 5.0, 0.25),
+        _trade("2026-01-01T00:01:00", "SOL-USDC", "BUY", "NIL", 100.0, 5.0, 0.1),
+    ],
+    "nil_multi_pair_unsorted": [
+        _trade("2026-01-01T00:03:00", "ETH-USDC", "SELL", "NIL", 2100.0, 1.0, 0.9),
+        _trade("2026-01-01T00:00:00", "SOL-USDC", "BUY", "NIL", 100.0, 10.0, 0.4),
+        _trade("2026-01-01T00:02:00", "ETH-USDC", "BUY", "NIL", 2000.0, 2.0, 1.2),
+        _trade("2026-01-01T00:01:00", "SOL-USDC", "SELL", "NIL", 105.0, 4.0, 0.2),
+    ],
+    "nil_zero_amount_and_price": [
+        _trade("2026-01-01T00:00:00", "SOL-USDC", "BUY", "NIL", 0.0, 0.0, 0.01),
+        _trade("2026-01-01T00:01:00", "SOL-USDC", "SELL", "NIL", 0.0, 0.0, 0.02),
+    ],
+    "nil_missing_fields": [
+        {"position": "NIL", "trade_type": "BUY"},
+        {"position": "NIL", "trade_type": "SELL"},
+        {"position": "NIL", "trade_type": "SELL"},
+    ],
+    "nil_none_timestamp": [
+        {
+            "timestamp": None,
+            "trading_pair": "SOL-USDC",
+            "trade_type": "BUY",
+            "position": "NIL",
+            "price": 100.0,
+            "amount": 1.0,
+            "trade_fee_in_quote": 0.1,
+        },
+    ],
+    "nil_unparseable_timestamps": [
+        _trade("2026-01-01T00:00:00", "SOL-USDC", "BUY", "NIL", 100.0, 4.0, 0.1),
+        _trade("", "SOL-USDC", "SELL", "NIL", 110.0, 2.0, 0.1),
+        _trade("garbage", "SOL-USDC", "SELL", "NIL", 120.0, 2.0, 0.1),
+    ],
+    "nil_unknown_trade_type": [
+        _trade("2026-01-01T00:00:00", "SOL-USDC", "", "NIL", 100.0, 3.0, 0.1),
+        _trade("2026-01-01T00:01:00", "SOL-USDC", "UNKNOWN", "NIL", 100.0, 3.0, 0.1),
+        _trade("2026-01-01T00:02:00", "SOL-USDC", "buy", "NIL", 100.0, 2.0, 0.1),
+        _trade("2026-01-01T00:03:00", "SOL-USDC", "sell", "NIL", 120.0, 2.0, 0.1),
+    ],
+    "nil_epoch_timestamps": [
+        _trade(1735689600, "SOL-USDC", "BUY", "NIL", 100.0, 1.0, 0.1),
+        _trade(1735689660000, "SOL-USDC", "SELL", "NIL", 130.0, 1.0, 0.1),
+    ],
+    # ---- OPEN/CLOSE mode ---------------------------------------------
+    "oc_long_full": [
+        _trade("2026-01-01T00:00:00", "SOL-USDT", "BUY", "OPEN", 100.0, 10.0, 0.5),
+        _trade("2026-01-01T00:01:00", "SOL-USDT", "SELL", "CLOSE", 110.0, 10.0, 0.55),
+    ],
+    "oc_short_full": [
+        _trade("2026-01-01T00:00:00", "SOL-USDT", "SELL", "OPEN", 100.0, 10.0, 0.5),
+        _trade("2026-01-01T00:01:00", "SOL-USDT", "BUY", "CLOSE", 90.0, 10.0, 0.45),
+    ],
+    "oc_partial_then_over_close": [
+        _trade("2026-01-01T00:00:00", "SOL-USDT", "BUY", "OPEN", 100.0, 10.0, 0.5),
+        _trade("2026-01-01T00:01:00", "SOL-USDT", "SELL", "CLOSE", 110.0, 4.0, 0.2),
+        _trade("2026-01-01T00:02:00", "SOL-USDT", "SELL", "CLOSE", 120.0, 20.0, 0.9),
+        _trade("2026-01-01T00:03:00", "SOL-USDT", "SELL", "CLOSE", 130.0, 1.0, 0.05),
+    ],
+    "oc_close_no_position": [
+        _trade("2026-01-01T00:00:00", "SOL-USDT", "SELL", "CLOSE", 100.0, 5.0, 0.25),
+        _trade("2026-01-01T00:01:00", "SOL-USDT", "BUY", "OPEN", 100.0, 5.0, 0.1),
+    ],
+    "oc_reopen_after_full_close": [
+        _trade("2026-01-01T00:00:00", "SOL-USDT", "BUY", "OPEN", 100.0, 5.0, 0.1),
+        _trade("2026-01-01T00:01:00", "SOL-USDT", "SELL", "CLOSE", 105.0, 5.0, 0.1),
+        _trade("2026-01-01T00:02:00", "SOL-USDT", "SELL", "OPEN", 110.0, 5.0, 0.1),
+        _trade("2026-01-01T00:03:00", "SOL-USDT", "BUY", "CLOSE", 100.0, 5.0, 0.1),
+    ],
+    "oc_zero_amount_open": [
+        _trade("2026-01-01T00:00:00", "SOL-USDT", "BUY", "OPEN", 100.0, 0.0, 0.1),
+        _trade("2026-01-01T00:01:00", "SOL-USDT", "SELL", "CLOSE", 110.0, 3.0, 0.2),
+    ],
+    "oc_mixed_with_nil_rows": [
+        _trade("2026-01-01T00:00:00", "SOL-USDT", "BUY", "NIL", 100.0, 2.0, 0.1),
+        _trade("2026-01-01T00:01:00", "SOL-USDT", "BUY", "OPEN", 100.0, 10.0, 0.5),
+        _trade("2026-01-01T00:02:00", "SOL-USDT", "SELL", "CLOSE", 110.0, 10.0, 0.55),
+    ],
+    "oc_missing_position_field": [
+        {
+            "timestamp": "2026-01-01T00:00:00",
+            "trading_pair": "SOL-USDT",
+            "trade_type": "BUY",
+            "price": 100.0,
+            "amount": 2.0,
+            "trade_fee_in_quote": 0.1,
+        },
+        {
+            "timestamp": "2026-01-01T00:01:00",
+            "trading_pair": "SOL-USDT",
+            "trade_type": "SELL",
+            "price": 110.0,
+            "amount": 2.0,
+            "trade_fee_in_quote": 0.11,
+        },
+    ],
+    "oc_multi_pair_unsorted": [
+        _trade("2026-01-01T00:03:00", "ETH-USDT", "BUY", "CLOSE", 1900.0, 1.0, 0.8),
+        _trade("2026-01-01T00:00:00", "SOL-USDT", "BUY", "OPEN", 100.0, 10.0, 0.4),
+        _trade("2026-01-01T00:02:00", "ETH-USDT", "SELL", "OPEN", 2000.0, 1.0, 0.7),
+        _trade("2026-01-01T00:01:00", "SOL-USDT", "SELL", "CLOSE", 105.0, 4.0, 0.2),
+    ],
+}
+
+# Which mode each scenario must dispatch to (None = empty short-circuit).
+MODES: dict[str, str] = {
+    "empty": "none",
+    "nil_buy_sell_full": "avg",
+    "nil_partial_and_oversell": "avg",
+    "nil_unmatched_sell_first": "avg",
+    "nil_multi_pair_unsorted": "avg",
+    "nil_zero_amount_and_price": "avg",
+    "nil_missing_fields": "avg",
+    "nil_none_timestamp": "avg",
+    "nil_unparseable_timestamps": "avg",
+    "nil_unknown_trade_type": "avg",
+    "nil_epoch_timestamps": "avg",
+    "oc_long_full": "oc",
+    "oc_short_full": "oc",
+    "oc_partial_then_over_close": "oc",
+    "oc_close_no_position": "oc",
+    "oc_reopen_after_full_close": "oc",
+    "oc_zero_amount_open": "oc",
+    "oc_mixed_with_nil_rows": "oc",
+    "oc_missing_position_field": "oc",
+    "oc_multi_pair_unsorted": "oc",
+}
+
+GOLDEN: dict[str, dict] = {
+    "empty": {
+        "total_pnl": 0,
+        "total_fees": 0,
+        "total_volume": 0,
+        "pnl_by_pair": {},
+        "cumulative": [],
+    },
+    "nil_buy_sell_full": {
+        "total_pnl": 99.45,
+        "total_fees": 1.05,
+        "total_volume": 2100.0,
+        "pnl_by_pair": {
+            "SOL-USDC": 99.45,
+        },
+        "cumulative": [
+            (0.0, "SOL-USDC"),
+            (99.45, "SOL-USDC"),
+        ],
+    },
+    "nil_partial_and_oversell": {
+        "total_pnl": -150.55,
+        "total_fees": 0.75,
+        "total_volume": 4600.0,
+        "pnl_by_pair": {
+            "SOL-USDC": -150.5,
+        },
+        "cumulative": [
+            (0.0, "SOL-USDC"),
+            (0.0, "SOL-USDC"),
+            (74.8, "SOL-USDC"),
+            (-150.5, "SOL-USDC"),
+            (-150.55, "SOL-USDC"),
+        ],
+    },
+    "nil_unmatched_sell_first": {
+        "total_pnl": -0.25,
+        "total_fees": 0.35,
+        "total_volume": 1000.0,
+        "pnl_by_pair": {},
+        "cumulative": [
+            (-0.25, "SOL-USDC"),
+            (-0.25, "SOL-USDC"),
+        ],
+    },
+    "nil_multi_pair_unsorted": {
+        "total_pnl": 118.89999999999999,
+        "total_fees": 2.7,
+        "total_volume": 7520.0,
+        "pnl_by_pair": {
+            "SOL-USDC": 19.8,
+            "ETH-USDC": 99.1,
+        },
+        "cumulative": [
+            (0.0, "SOL-USDC"),
+            (19.8, "SOL-USDC"),
+            (19.8, "ETH-USDC"),
+            (118.89999999999999, "ETH-USDC"),
+        ],
+    },
+    "nil_zero_amount_and_price": {
+        "total_pnl": -0.02,
+        "total_fees": 0.03,
+        "total_volume": 0.0,
+        "pnl_by_pair": {},
+        "cumulative": [
+            (0.0, "SOL-USDC"),
+            (-0.02, "SOL-USDC"),
+        ],
+    },
+    "nil_missing_fields": {
+        "total_pnl": 0.0,
+        "total_fees": 0.0,
+        "total_volume": 0.0,
+        "pnl_by_pair": {},
+        "cumulative": [
+            (0.0, "Unknown"),
+            (0.0, "Unknown"),
+            (0.0, "Unknown"),
+        ],
+    },
+    "nil_none_timestamp": {
+        "total_pnl": 0.0,
+        "total_fees": 0.1,
+        "total_volume": 100.0,
+        "pnl_by_pair": {},
+        "cumulative": [],
+    },
+    "nil_unparseable_timestamps": {
+        "total_pnl": 39.8,
+        "total_fees": 0.30000000000000004,
+        "total_volume": 860.0,
+        "pnl_by_pair": {
+            "SOL-USDC": 39.9,
+        },
+        "cumulative": [
+            (-0.1, "SOL-USDC"),
+        ],
+    },
+    "nil_unknown_trade_type": {
+        "total_pnl": 39.9,
+        "total_fees": 0.4,
+        "total_volume": 1040.0,
+        "pnl_by_pair": {
+            "SOL-USDC": 39.9,
+        },
+        "cumulative": [
+            (0.0, "SOL-USDC"),
+            (0.0, "SOL-USDC"),
+            (0.0, "SOL-USDC"),
+            (39.9, "SOL-USDC"),
+        ],
+    },
+    "nil_epoch_timestamps": {
+        "total_pnl": 29.9,
+        "total_fees": 0.2,
+        "total_volume": 230.0,
+        "pnl_by_pair": {
+            "SOL-USDC": 29.9,
+        },
+        "cumulative": [
+            (0.0, "SOL-USDC"),
+            (29.9, "SOL-USDC"),
+        ],
+    },
+    "oc_long_full": {
+        "total_pnl": 99.45,
+        "total_fees": 1.05,
+        "total_volume": 2100.0,
+        "pnl_by_pair": {
+            "SOL-USDT": 99.45,
+        },
+        "cumulative": [
+            (0.0, "SOL-USDT"),
+            (99.45, "SOL-USDT"),
+        ],
+    },
+    "oc_short_full": {
+        "total_pnl": 99.55,
+        "total_fees": 0.95,
+        "total_volume": 1900.0,
+        "pnl_by_pair": {
+            "SOL-USDT": 99.55,
+        },
+        "cumulative": [
+            (0.0, "SOL-USDT"),
+            (99.55, "SOL-USDT"),
+        ],
+    },
+    "oc_partial_then_over_close": {
+        "total_pnl": 438.90000000000003,
+        "total_fees": 1.6500000000000001,
+        "total_volume": 3970.0,
+        "pnl_by_pair": {
+            "SOL-USDT": 438.90000000000003,
+        },
+        "cumulative": [
+            (0.0, "SOL-USDT"),
+            (39.8, "SOL-USDT"),
+            (438.90000000000003, "SOL-USDT"),
+            (438.90000000000003, "SOL-USDT"),
+        ],
+    },
+    "oc_close_no_position": {
+        "total_pnl": 0.0,
+        "total_fees": 0.35,
+        "total_volume": 1000.0,
+        "pnl_by_pair": {},
+        "cumulative": [
+            (0.0, "SOL-USDT"),
+            (0.0, "SOL-USDT"),
+        ],
+    },
+    "oc_reopen_after_full_close": {
+        "total_pnl": 74.8,
+        "total_fees": 0.4,
+        "total_volume": 2075.0,
+        "pnl_by_pair": {
+            "SOL-USDT": 74.8,
+        },
+        "cumulative": [
+            (0.0, "SOL-USDT"),
+            (24.9, "SOL-USDT"),
+            (24.9, "SOL-USDT"),
+            (74.8, "SOL-USDT"),
+        ],
+    },
+    "oc_zero_amount_open": {
+        "total_pnl": 0.0,
+        "total_fees": 0.30000000000000004,
+        "total_volume": 330.0,
+        "pnl_by_pair": {},
+        "cumulative": [
+            (0.0, "SOL-USDT"),
+            (0.0, "SOL-USDT"),
+        ],
+    },
+    "oc_mixed_with_nil_rows": {
+        "total_pnl": 99.45,
+        "total_fees": 1.15,
+        "total_volume": 2300.0,
+        "pnl_by_pair": {
+            "SOL-USDT": 99.45,
+        },
+        "cumulative": [
+            (0.0, "SOL-USDT"),
+            (0.0, "SOL-USDT"),
+            (99.45, "SOL-USDT"),
+        ],
+    },
+    "oc_missing_position_field": {
+        "total_pnl": 0.0,
+        "total_fees": 0.21000000000000002,
+        "total_volume": 420.0,
+        "pnl_by_pair": {},
+        "cumulative": [
+            (0.0, "SOL-USDT"),
+            (0.0, "SOL-USDT"),
+        ],
+    },
+    "oc_multi_pair_unsorted": {
+        "total_pnl": 119.0,
+        "total_fees": 2.1,
+        "total_volume": 5320.0,
+        "pnl_by_pair": {
+            "SOL-USDT": 19.8,
+            "ETH-USDT": 99.2,
+        },
+        "cumulative": [
+            (0.0, "SOL-USDT"),
+            (19.8, "SOL-USDT"),
+            (19.8, "ETH-USDT"),
+            (119.0, "ETH-USDT"),
+        ],
+    },
+}
+
+
+def _expected_timestamps(trades):
+    """Timestamps the cumulative series must carry, derived independently."""
+    stamps = [
+        parse_timestamp(t.get("timestamp", 0))
+        for t in sorted(trades, key=lambda t: t.get("timestamp", 0))
+    ]
+    return [ts for ts in stamps if ts]
+
+
+@pytest.mark.parametrize("name", sorted(SCENARIOS))
+def test_totals_match_golden(name):
+    """The money numbers are byte-identical to the captured contract."""
+    result = calculate_pnl_from_trades(SCENARIOS[name])
+    expected = GOLDEN[name]
+
+    assert result["total_pnl"] == expected["total_pnl"]
+    assert result["total_fees"] == expected["total_fees"]
+    assert result["total_volume"] == expected["total_volume"]
+    assert result["pnl_by_pair"] == expected["pnl_by_pair"]
+    # exact key set too - a spurious zero entry must not creep in
+    assert list(result["pnl_by_pair"]) == list(expected["pnl_by_pair"])
+
+
+@pytest.mark.parametrize("name", sorted(SCENARIOS))
+def test_cumulative_series_matches_golden(name):
+    """The chart series keeps its exact length, order, values and pairs."""
+    result = calculate_pnl_from_trades(SCENARIOS[name])
+    expected = GOLDEN[name]["cumulative"]
+
+    assert [(p["pnl"], p["pair"]) for p in result["cumulative_pnl"]] == expected
+    assert [p["timestamp"] for p in result["cumulative_pnl"]] == _expected_timestamps(
+        SCENARIOS[name]
+    )
+    assert all(set(p) == {"timestamp", "pnl", "pair"} for p in result["cumulative_pnl"])
+
+
+@pytest.mark.parametrize("name", sorted(SCENARIOS))
+def test_result_shape_and_mode_dispatch(name):
+    """Every scenario returns the same five keys via the expected mode."""
+    trades = SCENARIOS[name]
+    result = calculate_pnl_from_trades(trades)
+    assert set(result) == {
+        "total_pnl",
+        "total_fees",
+        "pnl_by_pair",
+        "cumulative_pnl",
+        "total_volume",
+    }
+
+    mode = MODES[name]
+    if mode == "avg":
+        assert result == _calculate_pnl_average_cost(trades)
+    elif mode == "oc":
+        assert result == _calculate_pnl_open_close(trades)
+
+
+def test_unmatched_sell_charges_fee_to_total_but_not_to_pair():
+    """Average-cost mode: an unmatched SELL leaks its fee into total_pnl only.
+
+    This asymmetry is load-bearing behaviour, not an accident of the loop, and
+    the OPEN/CLOSE mode deliberately does NOT do it (see the test below).
+    """
+    result = calculate_pnl_from_trades(SCENARIOS["nil_unmatched_sell_first"])
+    assert result["total_pnl"] == -0.25
+    assert result["pnl_by_pair"] == {}
+    assert result["total_pnl"] != sum(result["pnl_by_pair"].values())
+
+
+def test_unmatched_close_charges_nothing():
+    """OPEN/CLOSE mode: a CLOSE with no position leaves running PnL untouched."""
+    result = calculate_pnl_from_trades(SCENARIOS["oc_close_no_position"])
+    assert result["total_pnl"] == 0.0
+    assert result["pnl_by_pair"] == {}
+
+
+def test_average_cost_clamps_sell_to_inventory():
+    """Average-cost realizes at most the inventory on hand..."""
+    trades = [
+        _trade("2026-01-01T00:00:00", "S-U", "BUY", "NIL", 100.0, 10.0, 0.0),
+        _trade("2026-01-01T00:01:00", "S-U", "SELL", "NIL", 110.0, 25.0, 0.0),
+    ]
+    # 10 units realized, not 25
+    assert calculate_pnl_from_trades(trades)["total_pnl"] == 100.0
+
+
+def test_open_close_realizes_full_amount_even_beyond_position():
+    """...while OPEN/CLOSE realizes the whole trade amount. Deliberate divergence."""
+    trades = [
+        _trade("2026-01-01T00:00:00", "S-U", "BUY", "OPEN", 100.0, 10.0, 0.0),
+        _trade("2026-01-01T00:01:00", "S-U", "SELL", "CLOSE", 110.0, 25.0, 0.0),
+    ]
+    # 25 units realized against a 10-unit position
+    assert calculate_pnl_from_trades(trades)["total_pnl"] == 250.0
+
+
+def test_empty_trades_short_circuits_with_integer_zeros():
+    assert calculate_pnl_from_trades([]) == {
+        "total_pnl": 0,
+        "total_fees": 0,
+        "pnl_by_pair": {},
+        "cumulative_pnl": [],
+        "total_volume": 0,
+    }

From 9f031aa6e00535af9070e6791757c8ebcac50d7c Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Fri, 14 Aug 2026 16:29:39 +0300
Subject: [PATCH 077/116] (perf) PERF-136: bound journal.md and write it once
 per tick
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A loop session's journal.md grew one Ticks line and one Snapshots line per
tick forever, and every tick rewrote the whole file three times (record_tick,
record_snapshot, write_summary) — five on a blocked or violating tick. Per-tick
IO therefore grew linearly with session age, inside the trading hot path.

Two independent fixes:

* JournalManager.batch() coalesces the writes of one tick into a single file
  write, applied to an in-memory document that readers inside the block see.
  It flushes in a finally, so a tick that raises still journals what it had
  recorded. The engine wraps both its per-tick write paths in it: 3 writes → 1
  on a normal tick, 2 → 1 on a risk-blocked one. The write itself now goes
  through condor.fsutil.atomic_write_text, so a crash mid-write can no longer
  truncate the agent's memory.

* Ticks and Snapshots are capped at 1000 lines each. The journal is an audit
  trail, so the overflow is moved — not deleted — to journal_archive.md beside
  it, and the section keeps a marker line naming the file and the count. The
  marker also carries the archived peak PnL, because get_drawdown_pct measures
  the fall from the session high-water mark and a forgotten peak would quietly
  make the risk gate less protective. Tick numbering is now read back from the
  tick line rather than derived from the line count, so it survives the trim
  across a restart (both _count_ticks and the module-level count_journal_ticks
  the dashboard uses).

Executors is left alone: it has no production writer, and its trim would have
to preserve status=open lines or under-count exposure in the risk gate.
---
 condor/agents/engine.py         |  76 ++++----
 condor/agents/journal.py        | 256 ++++++++++++++++++++++---
 tests/test_journal_retention.py | 328 ++++++++++++++++++++++++++++++++
 3 files changed, 598 insertions(+), 62 deletions(-)
 create mode 100644 tests/test_journal_retention.py

diff --git a/condor/agents/engine.py b/condor/agents/engine.py
index f5d443b5..a9c0d605 100644
--- a/condor/agents/engine.py
+++ b/condor/agents/engine.py
@@ -503,12 +503,13 @@ async def _tick(self) -> None:
             return
 
         if risk_state.is_blocked and not self.is_experiment:
-            self.journal.append_action(
-                self.journal.tick_count + 1,
-                "tick_blocked",
-                risk_state.block_reason,
-            )
-            self.journal.record_tick("blocked: " + risk_state.block_reason)
+            with self.journal.batch():
+                self.journal.append_action(
+                    self.journal.tick_count + 1,
+                    "tick_blocked",
+                    risk_state.block_reason,
+                )
+                self.journal.record_tick("blocked: " + risk_state.block_reason)
             await self._notify(
                 f"Agent {self.agent_id} blocked: {risk_state.block_reason}"
             )
@@ -653,24 +654,40 @@ async def _tick(self) -> None:
                 len(response_text),
             )
         else:
-            # Sessions: full journal tracking
-            tick_num = self.journal.record_tick(
-                response_summary=response_text[:500],
-            )
+            # Sessions: full journal tracking. Every journal.md update of this
+            # tick goes into one batch, so the file is rewritten once instead of
+            # three-to-five times (PERF-136).
+            with self.journal.batch():
+                tick_num = self.journal.record_tick(
+                    response_summary=response_text[:500],
+                )
 
-            self._journal_ownership_violations(tick_num)
-            self._journal_mode_mismatch(tick_num)
-
-            skill_pnl = self._last_skill_data.get("total_pnl", 0.0)
-            skill_volume = self._last_skill_data.get("total_volume", 0.0)
-            skill_executors = len(self._last_skill_data.get("executors", []))
-            skill_exposure = self._last_skill_data.get("total_exposure", 0.0)
-            self.journal.record_snapshot(
-                total_pnl=skill_pnl,
-                total_volume=skill_volume,
-                open_count=skill_executors,
-                position_size=skill_exposure,
-            )
+                self._journal_ownership_violations(tick_num)
+                self._journal_mode_mismatch(tick_num)
+
+                skill_pnl = self._last_skill_data.get("total_pnl", 0.0)
+                skill_volume = self._last_skill_data.get("total_volume", 0.0)
+                skill_executors = len(self._last_skill_data.get("executors", []))
+                skill_exposure = self._last_skill_data.get("total_exposure", 0.0)
+                self.journal.record_snapshot(
+                    total_pnl=skill_pnl,
+                    total_volume=skill_volume,
+                    open_count=skill_executors,
+                    position_size=skill_exposure,
+                )
+
+                action_brief = (
+                    response_text[:100].replace("\n", " ")
+                    if response_text
+                    else "No response"
+                )
+                self.journal.write_summary(
+                    tick=tick_num,
+                    status="Running",
+                    pnl=skill_pnl,
+                    open_count=skill_executors,
+                    last_action=action_brief,
+                )
 
             self.journal.save_full_snapshot(
                 tick=tick_num,
@@ -683,19 +700,6 @@ async def _tick(self) -> None:
                 duration=tick_duration,
             )
 
-            action_brief = (
-                response_text[:100].replace("\n", " ")
-                if response_text
-                else "No response"
-            )
-            self.journal.write_summary(
-                tick=tick_num,
-                status="Running",
-                pnl=skill_pnl,
-                open_count=skill_executors,
-                last_action=action_brief,
-            )
-
             # Live session report (FEAT-036). Deterministic render over data we
             # already hold — no tokens. The guard is load-bearing: a charting or
             # report-index failure must never take down a trading tick.
diff --git a/condor/agents/journal.py b/condor/agents/journal.py
index cff6a4b6..d7a943ad 100644
--- a/condor/agents/journal.py
+++ b/condor/agents/journal.py
@@ -22,10 +22,14 @@
 import json
 import logging
 import re
+from collections.abc import Iterator
+from contextlib import contextmanager
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
 
+from condor.fsutil import atomic_write_text
+
 log = logging.getLogger(__name__)
 
 _DATA_ROOT = Path(__file__).parent.parent.parent / "agents"
@@ -80,6 +84,30 @@ def resolve_agent_dirs(agent_id: str) -> tuple[Path | None, Path | None]:
 
 MAX_SNAPSHOTS = 100
 
+# Retention for the per-tick append-only sections of journal.md (PERF-136).
+# Ticks and Snapshots gain one line per tick, so on a long-running session they
+# grow without bound and every tick pays to rewrite them. Past the cap the
+# oldest lines are *moved* -- not deleted -- to ``journal_archive.md`` next to
+# journal.md, and the section keeps a marker line saying what went where.
+# 1000 lines is ~17h of history at a 60s tick and ~4 days at a 5m tick. No
+# reader of these two sections needs more: nothing reads a Ticks line's content
+# at all (only the tick number, from the last one), and Snapshots feeds the
+# drawdown peak -- carried across the trim in the marker -- plus a fallback
+# equity curve. Everything else lives in Summary and Decisions, both already
+# bounded and untouched here.
+MAX_TICK_LINES = 1000
+MAX_SNAPSHOT_LINES = 1000
+
+# Sidecar holding everything trimmed out of journal.md. Append-only, never read
+# in the trading hot path: it exists so the audit trail survives the trim and a
+# human (or the agent, via the journal_read MCP tool) can still go back.
+ARCHIVE_NAME = "journal_archive.md"
+
+# Marker left in place of the archived lines. Deliberately starts with "- " so
+# it reads as part of the list, and with a word that no entry parser accepts, so
+# _parse_snapshots / _count_ticks skip it instead of parsing it as data.
+ARCHIVE_MARKER_PREFIX = "- archived "
+
 JOURNAL_TEMPLATE = """\
 # Journal - {agent_id}
 
@@ -189,12 +217,36 @@ def next_experiment_number(agent_dir: Path) -> int:
 TICK_LINE_PREFIX = "- tick#"
 
 
+def highest_tick_number(text: str) -> int:
+    """Highest tick number recorded in ``text`` (0 if it holds no tick line).
+
+    The tick *number* is read back from the line rather than derived from the
+    line count, so numbering survives the retention trim (PERF-136): a journal
+    whose first 1000 ticks were archived still resumes at 1001. Lines are
+    appended in order, so the last one normally wins, but the max is taken
+    anyway -- the MCP journal_write tool can edit the file out of band.
+    """
+    highest = 0
+    seen = 0
+    for line in text.splitlines():
+        if not line.startswith(TICK_LINE_PREFIX):
+            continue
+        seen += 1
+        head = line[len(TICK_LINE_PREFIX) :].split("|", 1)[0].strip()
+        try:
+            highest = max(highest, int(head))
+        except ValueError:
+            continue
+    # A tick line with an unparseable number is not a reason to restart from
+    # zero and overwrite history: fall back to counting what is there.
+    return highest or seen
+
+
 def count_journal_ticks(journal_path: Path) -> int:
-    """Count tick entries in a session's journal.md (lines record_tick writes)."""
+    """Number of ticks a session has run, from its journal.md."""
     if not journal_path.exists():
         return 0
-    text = journal_path.read_text(errors="replace")
-    return sum(1 for line in text.splitlines() if line.startswith(TICK_LINE_PREFIX))
+    return highest_tick_number(journal_path.read_text(errors="replace"))
 
 
 EXPERIMENT_TEMPLATE = """\
@@ -339,6 +391,14 @@ def __init__(
         self._cache_text: str = ""
         self._parsed_cache: dict[str, list[dict]] = {}
 
+        # Write batching (PERF-136): inside ``with journal.batch():`` the
+        # updated document is held here and hits the disk once, on exit.
+        self._batch_depth = 0
+        self._pending_text: str | None = None
+        # Last section this process appended to journal_archive.md, so the
+        # sidecar gets one header per run of same-section lines, not per line.
+        self._archive_last_section: str | None = None
+
         if not self._path.exists():
             self._path.write_text(JOURNAL_TEMPLATE.format(agent_id=agent_id))
 
@@ -487,6 +547,9 @@ def _append_learning_to_journal(self, text_content: str) -> None:
 
     def read_full(self) -> str:
         """Return the entire journal contents (cached until the file changes)."""
+        if self._pending_text is not None:
+            # Mid-batch: the authoritative document is the one in memory.
+            return self._pending_text
         try:
             stat = self._path.stat()
         except OSError:
@@ -498,9 +561,38 @@ def read_full(self) -> str:
             self._parsed_cache.clear()
         return self._cache_text
 
+    @contextmanager
+    def batch(self) -> Iterator[JournalManager]:
+        """Coalesce every journal write in the block into a single file write.
+
+        A tick writes the journal three to five times (record_tick,
+        record_snapshot, write_summary, plus append_action on violations) and
+        each one used to rewrite the whole file. Inside this block the updates
+        are applied to an in-memory document -- readers inside the block see
+        them -- and the result is written once on exit, including on error, so
+        a tick that raises still journals what it had recorded.
+        """
+        self._batch_depth += 1
+        try:
+            yield self
+        finally:
+            self._batch_depth -= 1
+            if self._batch_depth == 0:
+                self.flush()
+
+    def flush(self) -> None:
+        """Write out a batched document, if any is pending."""
+        text, self._pending_text = self._pending_text, None
+        if text is not None:
+            self._write_journal(text)
+
     def _write_journal(self, text: str) -> None:
         """Write journal.md and invalidate the read cache."""
-        self._path.write_text(text)
+        if self._batch_depth > 0:
+            self._pending_text = text
+            self._parsed_cache.clear()
+            return
+        atomic_write_text(self._path, text)
         self._cache_stamp = None
         self._parsed_cache.clear()
 
@@ -796,8 +888,7 @@ def tick_count(self) -> int:
         return self._tick_count
 
     def _count_ticks(self) -> int:
-        section = self._get_section("Ticks")
-        return len([l for l in section.splitlines() if l.startswith(TICK_LINE_PREFIX)])
+        return highest_tick_number(self._get_section("Ticks"))
 
     def record_tick(self, response_summary: str = "", actions: int = 0) -> int:
         """Record a tick entry. Returns the new tick number."""
@@ -808,7 +899,7 @@ def record_tick(self, response_summary: str = "", actions: int = 0) -> int:
             f"{TICK_LINE_PREFIX}{self._tick_count} | {now} "
             f"| actions={actions} | {summary}"
         )
-        self._append_to_section("Ticks", entry)
+        self._append_bounded("Ticks", entry, MAX_TICK_LINES)
         return self._tick_count
 
     # ------------------------------------------------------------------
@@ -863,7 +954,7 @@ def record_snapshot(
             f"- {now} | pnl=${total_pnl:+.2f} | volume=${total_volume:,.0f} "
             f"| open={open_count} | exposure=${position_size:.2f}"
         )
-        self._append_to_section("Snapshots", entry)
+        self._append_bounded("Snapshots", entry, MAX_SNAPSHOT_LINES)
 
     # ------------------------------------------------------------------
     # Queries (used by RiskEngine)
@@ -896,24 +987,9 @@ def _parse_snapshots(self) -> list[dict]:
         section = self._get_section("Snapshots")
         results = []
         for line in section.splitlines():
-            if not line.startswith("- "):
+            if not line.startswith("- ") or line.startswith(ARCHIVE_MARKER_PREFIX):
                 continue
-            entry: dict[str, Any] = {}
-            for part in line[2:].split(" | "):
-                part = part.strip()
-                if part.startswith("pnl=$"):
-                    entry["pnl"] = float(part.replace("pnl=$", "").replace("+", ""))
-                elif part.startswith("volume=$"):
-                    entry["volume"] = float(
-                        part.replace("volume=$", "").replace(",", "")
-                    )
-                elif part.startswith("exposure=$"):
-                    entry["exposure"] = float(part.replace("exposure=$", ""))
-                elif part.startswith("open="):
-                    entry["open"] = int(part.replace("open=", ""))
-                elif re.match(r"\d{4}-\d{2}-\d{2}", part):
-                    entry["timestamp"] = part
-            results.append(entry)
+            results.append(_parse_snapshot_line(line))
         self._parsed_cache["snapshots"] = results
         return results
 
@@ -948,8 +1024,11 @@ def get_drawdown_pct(self) -> float:
         if not snapshots:
             return 0.0
         pnls = [s.get("pnl", 0) for s in snapshots]
-        peak = max(pnls)
         current = pnls[-1]
+        archived_peak = self._archived_peak_pnl()
+        if archived_peak is not None:
+            pnls.append(archived_peak)  # the high-water mark outlives the trim
+        peak = max(pnls)
         drawdown = peak - current
         if drawdown <= 0:
             return 0.0
@@ -959,6 +1038,12 @@ def get_drawdown_pct(self) -> float:
         return drawdown / exposure * 100
 
     def get_pnl_series(self) -> list[dict]:
+        """PnL points still held in journal.md (at most MAX_SNAPSHOT_LINES).
+
+        Older points are in ``journal_archive.md``; this is the equity-curve
+        fallback used when the bot's own series is empty, so a bounded tail is
+        what it needs -- it must not re-read the whole history every tick.
+        """
         return [
             {"timestamp": s.get("timestamp", ""), "pnl": s.get("pnl", 0)}
             for s in self._parse_snapshots()
@@ -1008,6 +1093,72 @@ def _replace_section(self, name: str, content: str) -> None:
             new_text = text.rstrip() + f"\n\n## {name}\n{content}\n"
         self._write_journal(new_text)
 
+    def _append_bounded(self, section: str, entry: str, max_lines: int) -> None:
+        """Append a line to a section, keeping at most ``max_lines`` of them.
+
+        Overflow is *moved* to ``journal_archive.md`` and replaced by a single
+        marker line naming the file and how much went into it, so the journal
+        never claims to be a complete record when it isn't. Costs the same one
+        read + one write as a plain append.
+        """
+        lines = [l for l in self._get_section(section).splitlines() if l.strip()]
+        marker = ""
+        if lines and lines[0].startswith(ARCHIVE_MARKER_PREFIX):
+            marker = lines.pop(0)
+        lines.append(entry)
+        if len(lines) > max_lines:
+            cut = len(lines) - max_lines
+            dropped, keep = lines[:cut], lines[cut:]
+            try:
+                self._archive_lines(section, dropped)
+            except OSError:
+                # Could not park them safely -> do not drop them. The section
+                # stays one line over the cap and the trim retries next tick.
+                log.exception("journal: archiving %s failed, keeping lines", section)
+            else:
+                lines = keep
+                marker = _next_marker(section, marker, dropped)
+        body = [marker, *lines] if marker else lines
+        self._replace_section(section, "\n".join(body))
+
+    def _archive_lines(self, section: str, lines: list[str]) -> None:
+        """Append trimmed lines to the session's archive sidecar.
+
+        Append-only and outside the journal's read path, so it costs O(lines
+        written) rather than O(history) -- the point of the trim. A failure
+        here must never take down a trading tick, but it must not silently
+        destroy the lines either, so it is logged loudly and the trim is
+        abandoned (the caller keeps them in journal.md for another round).
+        """
+        path = self._session_dir / ARCHIVE_NAME
+        header = ""
+        if not path.exists():
+            header = (
+                f"# Journal archive - {self.agent_id}\n\n"
+                "Entries trimmed out of journal.md to keep it bounded. "
+                "Append-only; nothing here is ever rewritten.\n"
+            )
+        if section != self._archive_last_section:
+            now = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M")
+            header += f"\n## {section} (archived {now} UTC)\n"
+        with path.open("a", encoding="utf-8") as fh:
+            fh.write(header + "\n".join(lines) + "\n")
+        self._archive_last_section = section
+
+    def _archived_peak_pnl(self) -> float | None:
+        """Peak PnL of the snapshots already archived, from the marker line.
+
+        get_drawdown_pct measures the fall from the session's high-water mark,
+        so the trim must not lower that mark -- a forgotten peak would quietly
+        make the risk gate less protective than it was yesterday.
+        """
+        for line in self._get_section("Snapshots").splitlines():
+            if not line.startswith(ARCHIVE_MARKER_PREFIX):
+                break
+            m = re.search(r"peak_pnl=\$([+-]?[\d.]+)", line)
+            return float(m.group(1)) if m else None
+        return None
+
     def _append_to_section(self, section: str, entry: str) -> None:
         """Append a line to a section."""
         text = self.read_full()
@@ -1037,6 +1188,59 @@ def entry_count(self) -> int:
         return len([l for l in section.splitlines() if l.startswith("- ")])
 
 
+def _parse_snapshot_line(line: str) -> dict[str, Any]:
+    """Parse one ``record_snapshot`` line into its fields."""
+    entry: dict[str, Any] = {}
+    for part in line[2:].split(" | "):
+        part = part.strip()
+        if part.startswith("pnl=$"):
+            entry["pnl"] = float(part.replace("pnl=$", "").replace("+", ""))
+        elif part.startswith("volume=$"):
+            entry["volume"] = float(part.replace("volume=$", "").replace(",", ""))
+        elif part.startswith("exposure=$"):
+            entry["exposure"] = float(part.replace("exposure=$", ""))
+        elif part.startswith("open="):
+            entry["open"] = int(part.replace("open=", ""))
+        elif re.match(r"\d{4}-\d{2}-\d{2}", part):
+            entry["timestamp"] = part
+    return entry
+
+
+def _next_marker(section: str, prev_marker: str, dropped: list[str]) -> str:
+    """Build the marker line that stands in for the archived entries.
+
+    It is what a reader sees at the boundary, so it says how many entries are
+    missing and where they went -- and, for Snapshots, carries forward the peak
+    PnL that get_drawdown_pct would otherwise lose with the lines.
+    """
+    prev_count = 0
+    if prev_marker:
+        m = re.search(r"archived (\d+)", prev_marker)
+        prev_count = int(m.group(1)) if m else 0
+    total = prev_count + len(dropped)
+
+    if section == "Snapshots":
+        peaks = [
+            entry["pnl"]
+            for entry in (_parse_snapshot_line(l) for l in dropped)
+            if "pnl" in entry
+        ]
+        m = re.search(r"peak_pnl=\$([+-]?[\d.]+)", prev_marker or "")
+        if m:
+            peaks.append(float(m.group(1)))
+        peak = f" | peak_pnl=${max(peaks):+.2f}" if peaks else ""
+        return (
+            f"{ARCHIVE_MARKER_PREFIX}{total} earlier snapshot"
+            f"{'' if total == 1 else 's'} to {ARCHIVE_NAME}{peak}"
+        )
+
+    noun = section.rstrip("s").lower()
+    return (
+        f"{ARCHIVE_MARKER_PREFIX}{total} earlier {noun}"
+        f"{'' if total == 1 else 's'} to {ARCHIVE_NAME}"
+    )
+
+
 def _normalize(text: str) -> str:
     """Lowercase, strip punctuation, collapse whitespace."""
     text = text.lower().strip()
diff --git a/tests/test_journal_retention.py b/tests/test_journal_retention.py
new file mode 100644
index 00000000..aa939114
--- /dev/null
+++ b/tests/test_journal_retention.py
@@ -0,0 +1,328 @@
+"""PERF-136: journal.md is bounded, and a tick rewrites it once.
+
+Two independent claims are pinned here.
+
+*Write amplification.* A tick used to rewrite the entire journal three times
+(record_tick, record_snapshot, write_summary) and a blocked tick twice. The
+counts below are the point of the change, so they are asserted as counts --
+asserting the resulting text would pass just as well with the old code.
+
+*Retention.* Ticks and Snapshots gained one line per tick forever, so per-tick
+IO grew with session age. They are now capped, and -- because the journal is
+the agent's memory and an audit trail -- the overflow is *moved* to
+``journal_archive.md`` rather than deleted, with a marker line saying so. What
+a reader sees at that boundary is asserted, not just the cap.
+"""
+
+import asyncio
+
+import pytest
+
+import condor.agents.journal as journal_mod
+import condor.reports as rep
+from condor.agents.journal import JournalManager, count_journal_ticks
+
+
+@pytest.fixture
+def journal(tmp_path) -> JournalManager:
+    return JournalManager("test-agent", session_dir=tmp_path)
+
+
+@pytest.fixture
+def writes(monkeypatch) -> list[str]:
+    """Record every full rewrite of a journal.md, in order."""
+    recorded: list[str] = []
+    original = journal_mod.atomic_write_text
+
+    def spy(path, text, **kwargs):
+        if str(path).endswith("journal.md"):
+            recorded.append(text)
+        return original(path, text, **kwargs)
+
+    monkeypatch.setattr(journal_mod, "atomic_write_text", spy)
+    return recorded
+
+
+def _tick_writes(journal: JournalManager, tick: int) -> None:
+    """The journal calls one engine tick makes, in engine.py's order."""
+    journal.record_tick(response_summary=f"tick {tick}")
+    journal.record_snapshot(
+        total_pnl=1.0, total_volume=10.0, open_count=1, position_size=100.0
+    )
+    journal.write_summary(
+        tick=tick, status="Running", pnl=1.0, open_count=1, last_action="held"
+    )
+
+
+# ── Write amplification ──
+
+
+def test_the_unbatched_calls_of_a_tick_write_the_file_three_times(journal, writes):
+    """Baseline: this is what every tick used to cost, unconditionally."""
+    _tick_writes(journal, 1)
+
+    assert len(writes) == 3
+
+
+def test_a_batched_tick_writes_the_file_once(journal, writes):
+    with journal.batch():
+        _tick_writes(journal, 1)
+
+    assert len(writes) == 1
+    # ...and the single write carries everything the three used to.
+    assert "- tick#1 " in writes[0]
+    assert "pnl=$+1.00" in writes[0]
+    assert "Last tick: #1" in writes[0]
+
+
+def test_a_reader_inside_the_batch_sees_the_pending_writes(journal):
+    """Nothing inside the block may read a stale journal off the disk."""
+    with journal.batch():
+        journal.record_tick(response_summary="one")
+        journal.record_snapshot(
+            total_pnl=7.0, total_volume=1.0, open_count=0, position_size=50.0
+        )
+
+        assert journal.tick_count == 1
+        assert journal.get_total_volume() == 1.0
+        assert journal.get_drawdown_pct() == 0.0
+        assert "- tick#1 " in journal.read_full()
+
+    assert "- tick#1 " in journal._path.read_text()
+
+
+def test_a_batch_that_raises_still_journals_what_it_recorded(journal, writes):
+    """A tick blowing up mid-way must not lose the tick it already recorded."""
+    with pytest.raises(RuntimeError):
+        with journal.batch():
+            journal.record_tick(response_summary="recorded before the crash")
+            raise RuntimeError("tick exploded")
+
+    assert len(writes) == 1
+    assert "recorded before the crash" in journal._path.read_text()
+
+
+def test_nested_batches_flush_once_at_the_outermost_exit(journal, writes):
+    with journal.batch():
+        journal.record_tick()
+        with journal.batch():
+            journal.record_tick()
+        assert not writes, "the inner block must not flush"
+
+    assert len(writes) == 1
+
+
+# ── Write amplification, through the real engine ──
+
+
+def _engine(tmp_path, monkeypatch):
+    from condor.agents import strategy as strategy_module
+    from condor.agents.agent import Agent
+    from condor.agents.engine import TickEngine
+    from condor.agents.strategy import Strategy
+
+    monkeypatch.setattr(strategy_module, "_DATA_ROOT", tmp_path)
+    strategy = Strategy(agent_slug="brigado", name="Grid")
+    strategy.dir.mkdir(parents=True, exist_ok=True)
+    agent = Agent(slug="brigado", name="Brigado")
+    return TickEngine(
+        agent=agent,
+        strategy=strategy,
+        config={"execution_mode": "loop"},
+        chat_id=1,
+        user_id=1,
+    )
+
+
+def _async(result):
+    async def go(*args, **kwargs):
+        return result
+
+    return go
+
+
+async def _empty_stream():
+    return
+    yield  # pragma: no cover -- makes this an async generator
+
+
+class _FakeACP:
+    async def start(self):
+        return None
+
+    async def stop(self):
+        return None
+
+
+def test_one_real_engine_tick_rewrites_the_journal_once(tmp_path, monkeypatch, writes):
+    monkeypatch.setattr(rep, "CHARTS_DIR", tmp_path / "reports")
+    monkeypatch.setattr(rep, "INDEX_FILE", tmp_path / "reports" / "reports_index.json")
+    engine = _engine(tmp_path / "agents", monkeypatch)
+    monkeypatch.setattr(engine, "_get_client", _async(object()))
+    monkeypatch.setattr(engine, "_adopt_running_bots", _async(None))
+    monkeypatch.setattr(engine, "_create_client", _async(_FakeACP()))
+    monkeypatch.setattr(engine, "_notify", _async(None))
+    monkeypatch.setattr(engine, "_collect_stream", lambda *a, **k: _empty_stream())
+    monkeypatch.setattr(engine.provider_registry, "run_core_providers", _async({}))
+    writes.clear()  # session setup is not part of the per-tick cost
+
+    asyncio.run(engine._tick())
+
+    assert len(writes) == 1, "a tick must rewrite journal.md exactly once"
+    assert engine.journal.tick_count == 1
+    text = engine.journal._path.read_text()
+    assert "- tick#1 " in text and "Last tick: #1" in text
+
+
+def test_a_risk_blocked_tick_rewrites_the_journal_once(tmp_path, monkeypatch, writes):
+    """The blocked path wrote twice (append_action + record_tick)."""
+    from condor.agents.risk import RiskState
+
+    monkeypatch.setattr(rep, "CHARTS_DIR", tmp_path / "reports")
+    monkeypatch.setattr(rep, "INDEX_FILE", tmp_path / "reports" / "reports_index.json")
+    engine = _engine(tmp_path / "agents", monkeypatch)
+    monkeypatch.setattr(engine, "_get_client", _async(object()))
+    monkeypatch.setattr(engine, "_adopt_running_bots", _async(None))
+    monkeypatch.setattr(engine, "_create_client", _async(_FakeACP()))
+    monkeypatch.setattr(engine, "_notify", _async(None))
+    monkeypatch.setattr(engine, "_collect_stream", lambda *a, **k: _empty_stream())
+    monkeypatch.setattr(engine.provider_registry, "run_core_providers", _async({}))
+    monkeypatch.setattr(
+        engine.risk,
+        "get_state",
+        lambda tracker: RiskState(is_blocked=True, block_reason="max drawdown"),
+    )
+    writes.clear()
+
+    asyncio.run(engine._tick())
+
+    assert len(writes) == 1
+    text = engine.journal._path.read_text()
+    assert "tick_blocked" in text and "- tick#1 " in text
+
+
+# ── Retention ──
+
+
+@pytest.fixture
+def small_caps(monkeypatch):
+    monkeypatch.setattr(journal_mod, "MAX_TICK_LINES", 10)
+    monkeypatch.setattr(journal_mod, "MAX_SNAPSHOT_LINES", 10)
+    return 10
+
+
+def _tick_lines(journal: JournalManager) -> list[str]:
+    return [
+        l
+        for l in journal._get_section("Ticks").splitlines()
+        if l.startswith(journal_mod.TICK_LINE_PREFIX)
+    ]
+
+
+def test_the_ticks_section_never_exceeds_the_cap(journal, small_caps):
+    for _ in range(small_caps * 5):
+        journal.record_tick()
+
+    assert len(_tick_lines(journal)) == small_caps
+
+
+def test_the_snapshots_section_never_exceeds_the_cap(journal, small_caps):
+    for i in range(small_caps * 5):
+        journal.record_snapshot(
+            total_pnl=float(i), total_volume=1.0, open_count=0, position_size=10.0
+        )
+
+    assert len(journal._parse_snapshots()) == small_caps
+
+
+def test_what_the_reader_sees_at_the_boundary(journal, small_caps):
+    """The visible marker must say what was dropped and where it went."""
+    for _ in range(small_caps + 3):
+        journal.record_tick()
+
+    lines = journal._get_section("Ticks").splitlines()
+    assert lines[0] == "- archived 3 earlier ticks to journal_archive.md"
+    assert lines[1].startswith("- tick#4 ")
+    assert lines[-1].startswith(f"- tick#{small_caps + 3} ")
+
+
+def test_the_trimmed_entries_are_archived_not_destroyed(journal, small_caps):
+    for i in range(small_caps + 3):
+        journal.record_tick(response_summary=f"tick {i + 1}")
+    for i in range(small_caps + 2):
+        journal.record_snapshot(
+            total_pnl=float(i), total_volume=1.0, open_count=0, position_size=10.0
+        )
+
+    archive = (journal._session_dir / journal_mod.ARCHIVE_NAME).read_text()
+    assert "## Ticks" in archive and "## Snapshots" in archive
+    for n in (1, 2, 3):
+        assert f"- tick#{n} " in archive
+    assert "pnl=$+0.00" in archive, "the oldest snapshot must survive in the sidecar"
+    # Nothing that is still live got copied out.
+    assert f"- tick#{small_caps + 3} " not in archive
+
+
+def test_the_marker_is_not_read_back_as_data(journal, small_caps):
+    for i in range(small_caps + 5):
+        journal.record_snapshot(
+            total_pnl=1.0, total_volume=float(i), open_count=0, position_size=10.0
+        )
+
+    assert journal._get_section("Snapshots").startswith("- archived ")
+    # A marker parsed as a snapshot would show up as a zero-volume point.
+    assert all("volume" in s for s in journal._parse_snapshots())
+    assert journal.get_total_volume() == float(small_caps + 4)
+    assert all(p["timestamp"] for p in journal.get_pnl_series())
+
+
+def test_the_drawdown_high_water_mark_survives_the_trim(journal, small_caps):
+    """A forgotten peak would quietly make the risk gate less protective."""
+    journal.record_snapshot(
+        total_pnl=100.0, total_volume=1.0, open_count=1, position_size=100.0
+    )
+    for _ in range(small_caps * 2):
+        journal.record_snapshot(
+            total_pnl=50.0, total_volume=1.0, open_count=1, position_size=100.0
+        )
+
+    assert 100.0 not in [s["pnl"] for s in journal._parse_snapshots()]
+    assert journal._archived_peak_pnl() == 100.0
+    assert journal.get_drawdown_pct() == pytest.approx(50.0)
+
+
+def test_tick_numbering_survives_the_trim_across_a_restart(journal, small_caps, writes):
+    """Acceptance criterion: numbering resumes from the number, not the count."""
+    for _ in range(150):
+        journal.record_tick()
+
+    assert journal.tick_count == 150
+    assert len(_tick_lines(journal)) == small_caps
+
+    reopened = JournalManager("test-agent", session_dir=journal._session_dir)
+
+    assert reopened.tick_count == 150
+    assert reopened.record_tick() == 151
+    assert count_journal_ticks(reopened._path) == 151
+
+
+def test_count_journal_ticks_falls_back_to_counting_unnumbered_lines(tmp_path):
+    """A malformed tick line is no reason to restart history at zero."""
+    path = tmp_path / "journal.md"
+    path.write_text("# Journal\n\n## Ticks\n- tick#x | bad\n- tick#y | bad\n")
+
+    assert count_journal_ticks(path) == 2
+
+
+def test_an_unwritable_archive_keeps_the_entries_in_the_journal(
+    journal, small_caps, caplog
+):
+    """Losing the sidecar must never mean losing the entries."""
+    # Something else already holds the name -- the sidecar cannot be appended to.
+    (journal._session_dir / journal_mod.ARCHIVE_NAME).mkdir()
+
+    for _ in range(small_caps + 1):
+        journal.record_tick()
+
+    assert len(_tick_lines(journal)) == small_caps + 1
+    assert "archiving Ticks failed" in caplog.text

From 7b9468e9f886523e7e537b58a2f59e4778176961 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Fri, 14 Aug 2026 17:04:58 +0300
Subject: [PATCH 078/116] (fix) CORR-171: a null trade timestamp must not kill
 the whole PnL report

sorted(trades, key=lambda t: t.get("timestamp", 0)) raised
TypeError: '<' not supported between instances of 'NoneType' and 'int'
as soon as one archived row carried an explicit timestamp: None next to a
numeric one. A *missing* timestamp was already covered by the 0 default; an
explicitly null one was not, so a single malformed row from the archive took
down the entire realized-PnL computation instead of degrading.

Sort through _timestamp_sort_key, which maps every shape the archive returns
onto a total order: numbers first (null and missing both as 0, as before),
then strings, then anything else - stable, so unorderable rows keep their
input order. Grouping by shape rather than coercing everything through
parse_timestamp is deliberate: it leaves the ordering of any homogeneous list
byte-identical to the naive sort, which is what the characterization goldens
pin (a list of unparseable strings still sorts lexicographically, epoch
seconds and epoch millis still sort as the numbers they are).

The crash was found while shipping ARCH-158, whose differential fuzz proved
the dedup reproduced it identically; the characterization fixtures had to be
split around it. They now cover the mixed null/missing/epoch list directly.
---
 condor/archived_pnl.py                      | 28 ++++++-
 tests/test_archived_pnl_characterization.py | 82 ++++++++++++++++++++-
 2 files changed, 108 insertions(+), 2 deletions(-)

diff --git a/condor/archived_pnl.py b/condor/archived_pnl.py
index 8eb82b6a..f356d1a4 100644
--- a/condor/archived_pnl.py
+++ b/condor/archived_pnl.py
@@ -273,6 +273,32 @@ def summary(self, trade_count: int, running_pnl: float) -> str:
         )
 
 
+def _timestamp_sort_key(trade: dict[str, Any]) -> tuple[int, float, str]:
+    """Total order over every timestamp shape the archive can hand us.
+
+    Sorting on the raw field blew up with ``TypeError: '<' not supported
+    between instances of 'NoneType' and 'int'`` as soon as one row carried an
+    explicit ``timestamp: None`` next to a numeric one - a single malformed
+    archive row killed the whole PnL report instead of degrading.
+
+    Grouping by shape first (numbers, then strings, then anything else) keeps
+    the ordering of a homogeneous list byte-identical to the naive sort, while
+    a mixed list becomes merely ordered rather than fatal. A null timestamp
+    sorts as ``0``, exactly like a missing one already did.
+    """
+    ts = trade.get("timestamp")
+    if ts is None:
+        return (0, 0.0, "")
+    if isinstance(ts, (int, float)):  # bool included, as before
+        return (0, float(ts), "")
+    if isinstance(ts, str):
+        return (1, 0.0, ts)
+    parsed = parse_timestamp(ts)  # datetime / pandas Timestamp
+    if parsed is not None:
+        return (0, parsed.timestamp(), "")
+    return (2, 0.0, "")  # unknown shape: stable, keeps input order
+
+
 def _walk_trades(trades: list[dict[str, Any]], accounting) -> dict[str, Any]:
     """Run the per-trade frame both PnL modes share.
 
@@ -288,7 +314,7 @@ def _walk_trades(trades: list[dict[str, Any]], accounting) -> dict[str, Any]:
     total_volume = 0.0
 
     # Sort trades by timestamp
-    sorted_trades = sorted(trades, key=lambda t: t.get("timestamp", 0))
+    sorted_trades = sorted(trades, key=_timestamp_sort_key)
 
     for trade in sorted_trades:
         parsed = _ParsedTrade(
diff --git a/tests/test_archived_pnl_characterization.py b/tests/test_archived_pnl_characterization.py
index 2e08a492..bb91229e 100644
--- a/tests/test_archived_pnl_characterization.py
+++ b/tests/test_archived_pnl_characterization.py
@@ -19,6 +19,7 @@
 from condor.archived_pnl import (
     _calculate_pnl_average_cost,
     _calculate_pnl_open_close,
+    _timestamp_sort_key,
     calculate_pnl_from_trades,
     parse_timestamp,
 )
@@ -95,6 +96,22 @@ def _trade(ts, pair, side, position, price, amount, fee):
         _trade(1735689600, "SOL-USDC", "BUY", "NIL", 100.0, 1.0, 0.1),
         _trade(1735689660000, "SOL-USDC", "SELL", "NIL", 130.0, 1.0, 0.1),
     ],
+    # CORR-171: an explicit null next to a number used to raise TypeError and
+    # take the whole report down. Null and missing both sort as 0, ahead of
+    # any real epoch, so the deliberately shuffled input reorders to BUY,
+    # BUY, SELL.
+    "nil_null_missing_and_epoch": [
+        _trade(1735689660, "SOL-USDC", "SELL", "NIL", 130.0, 4.0, 0.2),
+        _trade(None, "SOL-USDC", "BUY", "NIL", 100.0, 2.0, 0.1),
+        {
+            "trading_pair": "SOL-USDC",
+            "trade_type": "BUY",
+            "position": "NIL",
+            "price": 110.0,
+            "amount": 2.0,
+            "trade_fee_in_quote": 0.1,
+        },
+    ],
     # ---- OPEN/CLOSE mode ---------------------------------------------
     "oc_long_full": [
         _trade("2026-01-01T00:00:00", "SOL-USDT", "BUY", "OPEN", 100.0, 10.0, 0.5),
@@ -168,6 +185,7 @@ def _trade(ts, pair, side, position, price, amount, fee):
     "nil_unparseable_timestamps": "avg",
     "nil_unknown_trade_type": "avg",
     "nil_epoch_timestamps": "avg",
+    "nil_null_missing_and_epoch": "avg",
     "oc_long_full": "oc",
     "oc_short_full": "oc",
     "oc_partial_then_over_close": "oc",
@@ -304,6 +322,20 @@ def _trade(ts, pair, side, position, price, amount, fee):
             (29.9, "SOL-USDC"),
         ],
     },
+    "nil_null_missing_and_epoch": {
+        "total_pnl": 99.8,
+        "total_fees": 0.4,
+        "total_volume": 940.0,
+        "pnl_by_pair": {
+            "SOL-USDC": 99.8,
+        },
+        # the null-timestamp BUY charts no point (same as nil_none_timestamp);
+        # the missing-timestamp one still charts at epoch 0
+        "cumulative": [
+            (0.0, "SOL-USDC"),
+            (99.8, "SOL-USDC"),
+        ],
+    },
     "oc_long_full": {
         "total_pnl": 99.45,
         "total_fees": 1.05,
@@ -421,7 +453,7 @@ def _expected_timestamps(trades):
     """Timestamps the cumulative series must carry, derived independently."""
     stamps = [
         parse_timestamp(t.get("timestamp", 0))
-        for t in sorted(trades, key=lambda t: t.get("timestamp", 0))
+        for t in sorted(trades, key=_timestamp_sort_key)
     ]
     return [ts for ts in stamps if ts]
 
@@ -520,3 +552,51 @@ def test_empty_trades_short_circuits_with_integer_zeros():
         "cumulative_pnl": [],
         "total_volume": 0,
     }
+
+
+def test_null_timestamp_next_to_a_number_does_not_raise():
+    """CORR-171: one ``timestamp: None`` row must not kill the whole report."""
+    trades = SCENARIOS["nil_null_missing_and_epoch"]
+    result = calculate_pnl_from_trades(trades)  # used to raise TypeError
+    assert result["total_pnl"] == 99.8
+
+    # null and missing sort as 0, ahead of the epoch row, input order kept
+    assert [t.get("price") for t in sorted(trades, key=_timestamp_sort_key)] == [
+        100.0,
+        110.0,
+        130.0,
+    ]
+
+
+def test_sort_key_orders_each_shape_without_mixing_comparisons():
+    """Homogeneous lists keep the ordering the naive sort gave them."""
+    numeric = [{"timestamp": 3}, {"timestamp": 1}, {"timestamp": 2.5}]
+    assert [t["timestamp"] for t in sorted(numeric, key=_timestamp_sort_key)] == [
+        1,
+        2.5,
+        3,
+    ]
+
+    strings = [{"timestamp": "garbage"}, {"timestamp": ""}, {"timestamp": "2026-01-01"}]
+    assert [t["timestamp"] for t in sorted(strings, key=_timestamp_sort_key)] == [
+        "",
+        "2026-01-01",
+        "garbage",
+    ]
+
+    # every shape at once: numbers, then strings, then anything unorderable
+    mixed = [
+        {"timestamp": object()},
+        {"timestamp": "2026-01-01"},
+        {"timestamp": None},
+        {"timestamp": 5},
+        {},
+    ]
+    ordered = sorted(mixed, key=_timestamp_sort_key)
+    assert [type(t.get("timestamp")).__name__ for t in ordered] == [
+        "NoneType",  # explicit null -> 0
+        "NoneType",  # missing -> 0
+        "int",
+        "str",
+        "object",
+    ]

From 997f47f72f826894a2a6cb39ad9b9cc6a0a8894e Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Fri, 14 Aug 2026 17:08:29 +0300
Subject: [PATCH 079/116] (fix) CORR-160: backtest_store and the telemetry
 outbox wrote through a fixed .tmp sibling
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

ARCH-148 folded seven tmp+os.replace copies into condor/fsutil.py. It missed
three more sites, and all three carried the exact defect it was written to
kill: the temp path was derived as path.with_suffix(".tmp"), a *fixed* sibling
name. Two writers racing on the same target — a backtest re-run overwriting a
result, or any two saves both persisting the shared _index.json — pick the
identical temp path, one truncates the other's partial write, and os.replace
publishes the blend as if it were whole. The index is the sharp end: every
save_result rewrites it, so the collision window is every write, and a torn
index is silently rebuilt from disk on the next load, losing nothing loudly.

Both backtest_store sites and telemetry outbox._trim now go through the shared
writer, which also brings what the hand-rolled copies lacked: a unique temp
file per writer (mkstemp, O_EXCL), no litter left behind on failure, fsync of
the data and of the parent directory so the rename survives a crash, and UTF-8
on disk. The reads in backtest_store were decoding in the locale encoding,
which would have made a non-ASCII result unreadable on a machine whose locale
differed from the writer's; they are pinned to UTF-8 to match.

grep -rn 'with_suffix(".tmp")' condor/ now returns nothing.
---
 condor/backtest_store.py            |  19 ++---
 condor/telemetry/outbox.py          |  12 +--
 tests/test_backtest_store_atomic.py | 117 ++++++++++++++++++++++++++++
 3 files changed, 131 insertions(+), 17 deletions(-)
 create mode 100644 tests/test_backtest_store_atomic.py

diff --git a/condor/backtest_store.py b/condor/backtest_store.py
index 8aa5cc65..f710f83b 100644
--- a/condor/backtest_store.py
+++ b/condor/backtest_store.py
@@ -11,6 +11,8 @@
 from pathlib import Path
 from typing import Any
 
+from condor.fsutil import atomic_write_json
+
 logger = logging.getLogger(__name__)
 
 _DATA_DIR = Path("data") / "backtests"
@@ -79,29 +81,24 @@ def _read_file(self, task_id: str) -> dict[str, Any] | None:
         if not path.exists():
             return None
         try:
-            return json.loads(path.read_text())
+            return json.loads(path.read_text(encoding="utf-8"))
         except Exception:
             logger.warning("Failed to read backtest file %s", path)
             return None
 
     def _write_file(self, task_id: str, data: dict[str, Any]) -> None:
-        path = self._task_path(task_id)
-        tmp = path.with_suffix(".tmp")
-        tmp.write_text(json.dumps(data))
-        tmp.replace(path)
+        atomic_write_json(self._task_path(task_id), data)
 
     def _load_index(self) -> None:
         if self._index_path.exists():
             try:
-                self._index = json.loads(self._index_path.read_text())
+                self._index = json.loads(self._index_path.read_text(encoding="utf-8"))
             except Exception:
                 logger.warning("Failed to load backtest index, rebuilding")
                 self._rebuild_index()
 
     def _persist_index(self) -> None:
-        tmp = self._index_path.with_suffix(".tmp")
-        tmp.write_text(json.dumps(self._index))
-        tmp.replace(self._index_path)
+        atomic_write_json(self._index_path, self._index)
 
     def _rebuild_index(self) -> None:
         """Rebuild index from individual files on disk."""
@@ -110,7 +107,7 @@ def _rebuild_index(self) -> None:
             if path.name == "_index.json":
                 continue
             try:
-                data = json.loads(path.read_text())
+                data = json.loads(path.read_text(encoding="utf-8"))
                 task_id = path.stem
                 self._index[task_id] = {
                     "server": data.get("server", ""),
@@ -129,7 +126,7 @@ def _migrate_legacy(self) -> None:
         if not _LEGACY_FILE.exists():
             return
         try:
-            legacy_data = json.loads(_LEGACY_FILE.read_text())
+            legacy_data = json.loads(_LEGACY_FILE.read_text(encoding="utf-8"))
             if not isinstance(legacy_data, dict) or not legacy_data:
                 _LEGACY_FILE.unlink()
                 return
diff --git a/condor/telemetry/outbox.py b/condor/telemetry/outbox.py
index 8f4b5f7e..48a96e8a 100644
--- a/condor/telemetry/outbox.py
+++ b/condor/telemetry/outbox.py
@@ -30,6 +30,8 @@
 import time
 from pathlib import Path
 
+from condor.fsutil import atomic_write_text
+
 log = logging.getLogger(__name__)
 
 MAX_OUTBOX_EVENTS = 5000
@@ -149,12 +151,10 @@ def _trim() -> None:
     if len(kept) == len(events):
         return
     try:
-        path.parent.mkdir(parents=True, exist_ok=True)
-        tmp = path.with_suffix(".tmp")
-        with open(tmp, "w", encoding="utf-8") as fh:
-            for record in kept:
-                fh.write(json.dumps(record, separators=(",", ":")) + "\n")
-        tmp.replace(path)
+        atomic_write_text(
+            path,
+            "".join(json.dumps(r, separators=(",", ":")) + "\n" for r in kept),
+        )
     except OSError:
         log.debug("Telemetry could not trim the outbox", exc_info=True)
 
diff --git a/tests/test_backtest_store_atomic.py b/tests/test_backtest_store_atomic.py
new file mode 100644
index 00000000..a4436a21
--- /dev/null
+++ b/tests/test_backtest_store_atomic.py
@@ -0,0 +1,117 @@
+"""CORR-160: ``BacktestStore`` publishes whole files, never torn ones.
+
+Both write sites used to derive their temp path as ``path.with_suffix(".tmp")``
+— a *fixed* sibling name. Two writers racing on the same task (a re-run
+overwriting a result, or two servers persisting into the shared index) picked
+the identical temp path, one truncated the other's partial write, and
+``os.replace`` published the blend. These pin the properties the shared
+``condor.fsutil`` writer gives both sites instead: a unique temp file per
+writer, no litter left behind, and UTF-8 on disk regardless of locale.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import threading
+
+from condor.backtest_store import BacktestStore
+
+
+def _tmp_files(directory):
+    return sorted(p.name for p in directory.glob("*.tmp"))
+
+
+def _store(tmp_path) -> BacktestStore:
+    return BacktestStore(data_dir=tmp_path / "backtests")
+
+
+def test_result_file_survives_concurrent_writers_intact(tmp_path):
+    """Eight threads rewrite one task; the survivor is one writer's payload."""
+    store = _store(tmp_path)
+    # Big enough that a single write is many filesystem blocks, so a shared
+    # temp file would reliably tear rather than race by luck.
+    payloads = [
+        {"server": f"srv{i}", "blob": chr(ord("a") + i) * 40_000} for i in range(8)
+    ]
+    barrier = threading.Barrier(len(payloads))
+
+    def writer(payload):
+        barrier.wait()
+        for _ in range(10):
+            store.save_result(payload["server"], "task-1", payload)
+
+    threads = [threading.Thread(target=writer, args=(p,)) for p in payloads]
+    for t in threads:
+        t.start()
+    for t in threads:
+        t.join()
+
+    survivor = store.get_result("task-1")
+    assert survivor is not None  # parsed as JSON at all, i.e. not truncated
+    assert {"server": survivor["server"], "blob": survivor["blob"]} in payloads
+    assert _tmp_files(store._dir) == []
+
+
+def test_index_survives_concurrent_writers_intact(tmp_path):
+    """The index is the shared file: every writer persists it on every save."""
+    store = _store(tmp_path)
+    barrier = threading.Barrier(8)
+
+    def writer(n: int):
+        barrier.wait()
+        for i in range(10):
+            store.save_result(
+                f"srv{n}", f"task-{n}-{i}", {"config": {"id": "c" * 5_000}}
+            )
+
+    threads = [threading.Thread(target=writer, args=(n,)) for n in range(8)]
+    for t in threads:
+        t.start()
+    for t in threads:
+        t.join()
+
+    # A torn index is unparseable; a reload that has to rebuild would mask it,
+    # so read the bytes directly.
+    on_disk = json.loads(store._index_path.read_text(encoding="utf-8"))
+    assert isinstance(on_disk, dict) and on_disk
+    assert all(isinstance(v, dict) and "server" in v for v in on_disk.values())
+    assert _tmp_files(store._dir) == []
+
+
+def test_writers_never_share_a_temp_path(tmp_path, monkeypatch):
+    """The defect itself: a fixed sibling name is what let two writers collide."""
+    store = _store(tmp_path)
+    seen: list[str] = []
+    real_replace = os.replace
+
+    def spy(src, dst):
+        seen.append(os.path.basename(src))
+        return real_replace(src, dst)
+
+    monkeypatch.setattr(os, "replace", spy)
+    store.save_result("srv", "task-1", {"n": 1})
+    store.save_result("srv", "task-1", {"n": 2})
+
+    assert len(seen) == len(set(seen))
+    assert not any(name == "task-1.tmp" or name == "_index.tmp" for name in seen)
+
+
+def test_round_trip_is_utf8_regardless_of_locale(tmp_path):
+    store = _store(tmp_path)
+    store.save_result("srv", "task-1", {"note": "café ☕"})
+
+    assert store.get_result("task-1")["note"] == "café ☕"
+    # Decoded explicitly as UTF-8, not as whatever the reader's locale is.
+    raw = (store._dir / "task-1.json").read_bytes().decode("utf-8")
+    assert json.loads(raw)["note"] == "café ☕"
+
+
+def test_delete_still_removes_file_and_index_entry(tmp_path):
+    store = _store(tmp_path)
+    store.save_result("srv", "task-1", {"n": 1})
+
+    assert store.delete_result("task-1") is True
+    assert store.get_result("task-1") is None
+    assert not (store._dir / "task-1.json").exists()
+    assert json.loads(store._index_path.read_text(encoding="utf-8")) == {}

From 18b2705f51d072e8b1f5807650aaa97d3f9a402c Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Fri, 14 Aug 2026 17:10:49 +0300
Subject: [PATCH 080/116] (fix) CORR-161: give new_run_id 64 bits of entropy
 instead of 16
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

new_run_id() returned code_<epoch_ms>_<token_hex(2)> — 4 hex chars, 16 bits,
to disambiguate runs landing in the same millisecond. Same-millisecond runs
are not rare: a loop or a burst of tool calls produces them routinely.

CodeRunStore is per-file JSON keyed by that id, so a collision does not
raise — it silently overwrites the earlier run's stored output. The visible
symptom was a ~1% flake in test_new_run_id_is_unique_and_well_formed, which
draws 50 ids in a tight loop and collided by birthday; the invisible one was
a 1/65536 chance of destroying a real run's record.

token_hex(8) makes both vanish. The id stays sortable-by-time and scannable
at 35 chars, still inside the store's 64-char _ID_RE, which validates shape
and not width — so ids already on disk keep loading unchanged.
---
 condor/code_runs.py           | 9 +++++++--
 tests/test_code_runs_store.py | 8 ++++++++
 2 files changed, 15 insertions(+), 2 deletions(-)

diff --git a/condor/code_runs.py b/condor/code_runs.py
index 8a37bc3a..d34e51e1 100644
--- a/condor/code_runs.py
+++ b/condor/code_runs.py
@@ -65,8 +65,13 @@ def to_dict(self) -> dict:
 
 
 def new_run_id() -> str:
-    """``code_<epoch_ms>_<4 hex>`` — sortable by time, unique under concurrency."""
-    return f"code_{int(time.time() * 1000)}_{secrets.token_hex(2)}"
+    """``code_<epoch_ms>_<16 hex>`` — sortable by time, unique under concurrency.
+
+    The suffix carries 64 bits: runs starting in the same millisecond are common
+    (a loop, a burst of tool calls) and the store is keyed by this id, so a
+    collision silently overwrites the earlier run instead of raising.
+    """
+    return f"code_{int(time.time() * 1000)}_{secrets.token_hex(8)}"
 
 
 class CodeRunStore:
diff --git a/tests/test_code_runs_store.py b/tests/test_code_runs_store.py
index 66267200..17c2b84d 100644
--- a/tests/test_code_runs_store.py
+++ b/tests/test_code_runs_store.py
@@ -116,3 +116,11 @@ def test_new_run_id_is_unique_and_well_formed():
     ids = {new_run_id() for _ in range(50)}
     assert len(ids) == 50
     assert all(i.startswith("code_") and i.count("_") == 2 for i in ids)
+
+
+def test_new_run_id_suffix_carries_at_least_64_bits():
+    """The store is keyed by the id, so a same-millisecond collision overwrites."""
+    for run_id in (new_run_id() for _ in range(10)):
+        suffix = run_id.rsplit("_", 1)[1]
+        assert len(suffix) >= 16, run_id
+        assert int(suffix, 16) >= 0

From fbaac0e12c7f6c02a751098811514a5e52fcb0eb Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Fri, 14 Aug 2026 17:15:46 +0300
Subject: [PATCH 081/116] (fix) SEC-167: respawn checks the caller's server
 access, not the owner's
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`_respawn` gated a server switch with
`check_server_access(info.user_id or 0, body.server_name)` — it asked whether
the *session's owner* could reach the target server, when the question is
whether the caller can. Reaching a session whose owner has broader access
therefore licensed the owner's permissions rather than the caller's. The
authenticated `WebUser` was already in the handler; it is now threaded into
`_respawn` and named as the subject, matching how every other body-param site
gates (`agents.consult_agent`, `delegate_agent`, `update_agent_config`).

Not exploitable today: `_require_ownership` only lets the owner or an admin
reach `_respawn`, and a real admin holds OWNER on every server. But a
permission check whose subject is the wrong principal is not a property to
leave resting on who happens to be able to call it.

The `or 0` fallback is gone rather than relocated. A respawn *creates* a
session, and the new spec's owner, its user_data, the remembered model choice
and the conversation it writes into are all keyed by `user_id`; an ownerless
record has no honest subject to create it for, so it is refused with 403
"Session has no owner" instead of being checked as user 0. That is the
fail-closed treatment SEC-150 gave ownerless routine instances. Both checks
run before the teardown, so a refused switch leaves the session running.

Regression tests pin all of it: a stranger cannot respawn a foreign session
(with or without a server), an admin is held to their own access on a session
whose owner has more, and an ownerless session is refused without any
placeholder id reaching the access check. The three SEC-167 tests fail against
the previous code.
---
 condor/web/routes/sessions.py               |  25 ++-
 tests/test_session_respawn_authorization.py | 197 ++++++++++++++++++++
 2 files changed, 217 insertions(+), 5 deletions(-)
 create mode 100644 tests/test_session_respawn_authorization.py

diff --git a/condor/web/routes/sessions.py b/condor/web/routes/sessions.py
index 90fa81e6..9dbfa255 100644
--- a/condor/web/routes/sessions.py
+++ b/condor/web/routes/sessions.py
@@ -227,12 +227,14 @@ async def session_action(
         return {"ok": await runtime.abort(parsed)}
 
     if body.action in ("new", "switch"):
-        return await _respawn(parsed, info, body)
+        return await _respawn(parsed, info, body, user)
 
     raise HTTPException(status_code=400, detail=f"Unknown action: {body.action}")
 
 
-async def _respawn(key: SessionKey, info: SessionInfo, body: SessionAction) -> dict:
+async def _respawn(
+    key: SessionKey, info: SessionInfo, body: SessionAction, user: WebUser
+) -> dict:
     """Tear the session down and bring it back under the same key.
 
     ACP has no identity hot-swap, so switching who is answering means reaping
@@ -249,12 +251,25 @@ async def _respawn(key: SessionKey, info: SessionInfo, body: SessionAction) -> d
 
     switching = body.action == "switch"
 
+    # A respawn *creates* a session, so it needs a real owner to create it for:
+    # the new spec's ``user_id``, the user_data loaded for it, the remembered
+    # model choice and the conversation it writes into are all keyed by that id.
+    # A record carrying none has no such subject, so refuse rather than stand a
+    # placeholder id in for it — the same fail-closed treatment SEC-150 gave
+    # ownerless routine instances. Only an admin can get here with one anyway:
+    # ``_require_ownership`` already refuses everyone else.
+    if info.user_id is None:
+        raise HTTPException(status_code=403, detail="Session has no owner")
+
     # The new session's tools are built against this server's credentials, so
     # gate it exactly like consult/delegate do — otherwise a switch would be a
-    # way to reach a server the caller was never granted (IDOR). Checked before
-    # the teardown, so a refused switch leaves the session running as it was.
+    # way to reach a server the caller was never granted (IDOR). The subject is
+    # the *caller*, never the session's owner (SEC-167): an admin acting on
+    # someone else's session must be held to their own reach, not licensed by
+    # the owner's. Checked before the teardown, so a refused switch leaves the
+    # session running as it was.
     if body.server_name:
-        check_server_access(info.user_id or 0, body.server_name)
+        check_server_access(user.id, body.server_name)
 
     # Unspecified fields keep their current value, so "new" is just a switch
     # to the same identity.
diff --git a/tests/test_session_respawn_authorization.py b/tests/test_session_respawn_authorization.py
new file mode 100644
index 00000000..309d9926
--- /dev/null
+++ b/tests/test_session_respawn_authorization.py
@@ -0,0 +1,197 @@
+"""SEC-167: respawn's access check names the caller, not the session's owner.
+
+``POST /sessions/{key}/action`` with ``new``/``switch`` used to ask
+``check_server_access`` whether the *session's owner* could reach the requested
+server, with ``info.user_id or 0`` standing in when the record carried no owner
+at all. Two properties are pinned here:
+
+* the subject of the server check is the **caller** — reaching a session whose
+  owner has broader access must not license the owner's permissions; and
+* an **ownerless** session is refused outright rather than checked as user 0,
+  the same fail-closed treatment SEC-150 gave ownerless routine instances.
+
+The fake config manager below deliberately does *not* grant the admin universal
+server access, which the real one does (``get_server_permission`` returns OWNER
+for any admin). That is what makes caller and owner distinguishable at all: with
+the real semantics the two subjects agree for every caller who can reach
+``_respawn``, so the bug is latent rather than exploitable — which is exactly
+why it needs a test to stay fixed.
+"""
+
+import asyncio
+
+import pytest
+from fastapi import FastAPI, HTTPException
+from starlette.testclient import TestClient
+
+from condor.runtime import SessionInfo, SessionKey
+from condor.web.auth import get_current_user
+from condor.web.models import WebUser
+from condor.web.routes import sessions as routes
+
+OWNER = WebUser(id=111, username="owner", first_name="O", role="user")
+STRANGER = WebUser(id=222, username="stranger", first_name="S", role="user")
+ADMIN = WebUser(id=999, username="admin", first_name="A", role="admin")
+
+# Only OWNER is granted it, so a check that passes for ADMIN can only have
+# asked about OWNER.
+OWNER_ONLY_SERVER = "prod"
+
+KEY = f"web:{OWNER.id}:main"
+
+
+class FakeConfigManager:
+    def is_admin(self, user_id):
+        return user_id == ADMIN.id
+
+    def has_server_access(self, user_id, server_name, *a, **k):
+        return user_id == OWNER.id and server_name == OWNER_ONLY_SERVER
+
+
+def _info(user_id: int | None) -> SessionInfo:
+    return SessionInfo(
+        key=KEY,
+        agent_key="claude-code",
+        user_id=user_id,
+        surface="web",
+        slot="main",
+        server_name="local",
+        alive=True,
+    )
+
+
+@pytest.fixture
+def env(monkeypatch):
+    """Stub the runtime so only the authorization layer is under test."""
+    destroyed: list[SessionKey] = []
+
+    async def _get_info(key):
+        return _info(OWNER.id)
+
+    async def _destroy(key):
+        destroyed.append(key)
+        return True
+
+    monkeypatch.setattr(routes.runtime, "get_info", _get_info)
+    monkeypatch.setattr(routes.runtime, "destroy", _destroy)
+    monkeypatch.setattr(routes, "get_config_manager", lambda: FakeConfigManager())
+    monkeypatch.setattr(
+        "condor.web.auth.get_config_manager", lambda: FakeConfigManager()
+    )
+    return destroyed
+
+
+def _client(user: WebUser) -> TestClient:
+    app = FastAPI()
+    app.include_router(routes.router)
+    app.dependency_overrides[get_current_user] = lambda: user
+    return TestClient(app)
+
+
+def _switch(user: WebUser, **body):
+    return _client(user).post(
+        f"/sessions/{KEY}/action",
+        json={"action": "switch", **body},
+    )
+
+
+def test_a_stranger_cannot_respawn_someone_elses_session(env):
+    """The ownership gate runs before anything is torn down."""
+    resp = _switch(STRANGER, server_name=OWNER_ONLY_SERVER)
+
+    assert resp.status_code == 403
+    assert resp.json()["detail"] == "Not your session"
+    assert env == [], "a refused respawn must leave the session running"
+
+
+def test_a_stranger_cannot_respawn_even_without_naming_a_server(env):
+    """``new`` on a foreign session is refused too, server or no server."""
+    resp = _client(STRANGER).post(f"/sessions/{KEY}/action", json={"action": "new"})
+
+    assert resp.status_code == 403
+    assert env == []
+
+
+def test_the_owner_passes_the_server_check_on_their_own_server(env, monkeypatch):
+    """Sanity: the guard is not simply refusing everyone."""
+    spawned = {}
+
+    async def _create_session(spec, user_data=None):
+        spawned["spec"] = spec
+        return _info(OWNER.id)
+
+    monkeypatch.setattr(routes.runtime, "create_session", _create_session)
+    monkeypatch.setattr(routes, "remember_model_choice", lambda *a, **k: None)
+    monkeypatch.setattr("condor.preferences.load_user_data_for", lambda *a, **k: {})
+
+    resp = _switch(OWNER, server_name=OWNER_ONLY_SERVER)
+
+    assert resp.status_code == 200
+    assert spawned["spec"].server_name == OWNER_ONLY_SERVER
+    assert env == [SessionKey.parse(KEY)]
+
+
+def test_the_server_check_names_the_caller_not_the_session_owner(env):
+    """An admin reaching a foreign session is held to their own access.
+
+    ADMIN clears ``_require_ownership`` (admins see every session) but has no
+    grant on ``OWNER_ONLY_SERVER``. Before SEC-167 the check asked about
+    ``info.user_id`` — the owner, who does — and the switch went through.
+    """
+    resp = _switch(ADMIN, server_name=OWNER_ONLY_SERVER)
+
+    assert resp.status_code == 403
+    assert resp.json()["detail"] == "No access"
+    assert env == [], "the check must run before the teardown"
+
+
+def test_an_ownerless_session_is_refused_not_checked_as_user_zero(env, monkeypatch):
+    """``info.user_id or 0`` asked about a placeholder id; now it refuses.
+
+    An ownerless record only reaches ``_respawn`` through an admin, and a
+    respawn re-creates the session — spec owner, user_data, remembered model
+    and transcript are all keyed by ``user_id``, so there is no honest subject
+    to create it for.
+    """
+    asked: list[int] = []
+
+    def _spy(user_id, server_name):
+        asked.append(user_id)
+        raise AssertionError("must not reach the server check")
+
+    monkeypatch.setattr(routes, "check_server_access", _spy)
+
+    async def _orphan(key):
+        return _info(None)
+
+    monkeypatch.setattr(routes.runtime, "get_info", _orphan)
+
+    with pytest.raises(HTTPException) as exc:
+        asyncio.run(
+            routes._respawn(
+                SessionKey.parse(KEY),
+                _info(None),
+                routes.SessionAction(action="switch", server_name=OWNER_ONLY_SERVER),
+                ADMIN,
+            )
+        )
+
+    assert exc.value.status_code == 403
+    assert exc.value.detail == "Session has no owner"
+    assert asked == [], "no placeholder id may be handed to the access check"
+    assert env == []
+
+
+def test_an_ownerless_session_is_refused_over_http_too(env, monkeypatch):
+    """Same refusal through the route, for the admin who can reach it."""
+
+    async def _orphan(key):
+        return _info(None)
+
+    monkeypatch.setattr(routes.runtime, "get_info", _orphan)
+
+    resp = _switch(ADMIN, server_name=OWNER_ONLY_SERVER)
+
+    assert resp.status_code == 403
+    assert resp.json()["detail"] == "Session has no owner"
+    assert env == []

From 29cc80790fad6dbcbcf4c517163ae56b19510292 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Fri, 14 Aug 2026 17:19:38 +0300
Subject: [PATCH 082/116] (fix) CORR-168: one malformed candle row must not 500
 the whole chart
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The REST candle route ran the shared fetcher with strict=True, a behaviour
ARCH-146 preserved from the route's old inline normalizer. The result: a
single upstream row whose value did not parse (open="n/a") raised out of
the handler as a 500 and the client got no chart at all, while the two WS
call sites on the very same payload dropped that one row and carried on.

Flip the route to strict=False so it degrades like the WS paths. Dropping
a row silently is its own problem — the series just loses a candle and no
consumer can tell that hole apart from a genuine gap in upstream data — so
fetch_historical_candles now reports what it discarded: one warning per
fetch (not per row, which a systematically broken payload would turn into
a flood from the pollers) naming the count, the connector/pair/interval
and the first offending row.

A real upstream failure is untouched: it still raises past the drop path
and is wrapped as upstream_error, so a payload bug and an outage stay
distinguishable.

Tests cover the route surviving a bad row mid-window, the warning carrying
enough context to diagnose it, a clean window logging nothing, and an
outage still surfacing as an upstream error.
---
 condor/fetchers/market_data.py           |  37 ++++-
 condor/web/routes/market.py              |  11 +-
 tests/test_candle_route_malformed_row.py | 171 +++++++++++++++++++++++
 3 files changed, 209 insertions(+), 10 deletions(-)
 create mode 100644 tests/test_candle_route_malformed_row.py

diff --git a/condor/fetchers/market_data.py b/condor/fetchers/market_data.py
index 184ba754..48da5b69 100644
--- a/condor/fetchers/market_data.py
+++ b/condor/fetchers/market_data.py
@@ -59,9 +59,10 @@ def normalize_candle(c: Any, *, strict: bool = False) -> Optional[Dict[str, floa
 
     Args:
         strict: Re-raise ``TypeError``/``ValueError`` from a malformed value
-            (e.g. ``open="n/a"``) instead of dropping the row. The REST candles
-            route has always surfaced those; the WS paths have always swallowed
-            them, so the behaviour stays per-caller.
+            (e.g. ``open="n/a"``) instead of dropping the row. No candle caller
+            asks for this today — every one of them would rather lose a candle
+            than a whole series (see CORR-168) — but the raise stays available
+            for a consumer that cannot tolerate a hole.
     """
     try:
         if isinstance(c, dict):
@@ -124,7 +125,9 @@ async def fetch_historical_candles(
         fallback_on_error: Treat a failing historical call as an empty result and
             continue to the fallback, instead of propagating. Callers that abort
             on failure (WS backfill, REST poll) leave it off.
-        strict: Passed through to `normalize_candle`.
+        strict: Passed through to `normalize_candle`. Rows dropped instead of
+            raised are logged once per call at warning, so a payload bug is
+            still discoverable rather than silently thinning the series.
 
     Returns:
         Normalized candles in upstream order; empty when nothing was usable.
@@ -170,7 +173,31 @@ async def fetch_historical_candles(
         )
         rows = _unwrap_candles(result)
 
-    return [c for r in rows if (c := normalize_candle(r, strict=strict)) is not None]
+    normalized: List[Dict[str, float]] = []
+    dropped: List[Any] = []
+    for r in rows:
+        c = normalize_candle(r, strict=strict)
+        if c is None:
+            dropped.append(r)
+        else:
+            normalized.append(c)
+
+    if dropped:
+        # A dropped row leaves a hole in the series that consumers cannot tell
+        # apart from a genuine gap in upstream data, so keep it discoverable.
+        # One line per fetch, not per bad row: a systematically broken payload
+        # would otherwise flood the log from the WS pollers.
+        logger.warning(
+            "Dropped %d of %d unusable candle rows for %s %s %s; first: %r",
+            len(dropped),
+            len(rows),
+            connector_name,
+            trading_pair,
+            interval,
+            dropped[0],
+        )
+
+    return normalized
 
 
 async def fetch_candle_connectors(client, **_kw) -> List[str]:
diff --git a/condor/web/routes/market.py b/condor/web/routes/market.py
index 479499ee..0df93d7e 100644
--- a/condor/web/routes/market.py
+++ b/condor/web/routes/market.py
@@ -446,12 +446,13 @@ async def _fetch_candles_upstream(
             end_time=int(end_time) if end_time else int(time.time()),
             limit=limit,
             fallback_on_error=True,
-            strict=True,
+            # CORR-168: one malformed row costs one candle, not the whole
+            # chart. The fetcher logs what it dropped at warning, so a payload
+            # bug is still diagnosable without 500ing every request for the
+            # pair. A real upstream failure still raises below and is wrapped
+            # as `upstream_error` — the two stay distinguishable.
+            strict=False,
         )
-    except (TypeError, ValueError):
-        # A malformed row (strict=True) is a bug in the payload, not an upstream
-        # outage — surface it as-is, as this route always has.
-        raise
     except Exception as e:
         logger.exception(
             "Failed to fetch candles for %s on %s of '%s'",
diff --git a/tests/test_candle_route_malformed_row.py b/tests/test_candle_route_malformed_row.py
new file mode 100644
index 00000000..2dad1134
--- /dev/null
+++ b/tests/test_candle_route_malformed_row.py
@@ -0,0 +1,171 @@
+"""CORR-168: a malformed upstream row costs one candle, not the whole chart.
+
+The REST candle route used to run the fetcher with ``strict=True``, so a single
+row whose value did not parse raised out of the handler as a 500 and the client
+got no chart at all — while the WS paths on the very same payload dropped that
+one row and carried on. The route now degrades the same way, and the drop is
+logged so a payload bug is still discoverable instead of a silent hole.
+"""
+
+import asyncio
+import logging
+
+import pytest
+
+import condor.web.routes.market as market
+from condor.fetchers.market_data import fetch_historical_candles
+from condor.web.models import WebUser
+
+GOOD = {
+    "timestamp": 1000.0,
+    "open": 1.0,
+    "high": 2.0,
+    "low": 0.5,
+    "close": 1.5,
+    "volume": 10.0,
+}
+# `open` is not a number: float() raises ValueError on this row and only this row.
+MALFORMED = {**GOOD, "timestamp": 1060.0, "open": "n/a"}
+ALSO_GOOD = {**GOOD, "timestamp": 1120.0}
+
+
+@pytest.fixture(autouse=True)
+def _clean_state():
+    market._candle_cache.clear()
+    market._candle_inflight.clear()
+    yield
+    market._candle_cache.clear()
+    market._candle_inflight.clear()
+
+
+class _Cm:
+    def __init__(self, client):
+        self._client = client
+
+    def has_server_access(self, user_id, name):
+        return True
+
+    async def get_client(self, name):
+        return self._client
+
+
+class _Client:
+    """Returns a window with one unparseable row in the middle."""
+
+    def __init__(self, rows=None, fail=False):
+        self._rows = rows if rows is not None else [GOOD, MALFORMED, ALSO_GOOD]
+        self._fail = fail
+
+    @property
+    def market_data(self):
+        return self
+
+    async def get_historical_candles(self, *a, **kw):
+        if self._fail:
+            raise RuntimeError("upstream down")
+        return self._rows
+
+    async def get_candles(self, *a, **kw):
+        if self._fail:
+            raise RuntimeError("upstream down")
+        return []
+
+
+def _call(monkeypatch, client, **overrides):
+    monkeypatch.setattr(
+        "condor.web.routes.market.get_config_manager", lambda: _Cm(client), raising=True
+    )
+    params = dict(
+        connector="binance",
+        trading_pair="BTC-USDT",
+        interval="1m",
+        limit=100,
+        start_time=1_700_000_000.0,
+        end_time=1_700_003_600.0,
+        pool_address=None,
+        user=WebUser(id=1, role="user"),
+    )
+    params.update(overrides)
+    return asyncio.run(market.get_candles("srv", **params))
+
+
+def test_one_malformed_row_no_longer_fails_the_whole_request(monkeypatch):
+    candles = _call(monkeypatch, _Client())
+
+    # The request succeeds, minus exactly the bad row.
+    assert [c.timestamp for c in candles] == [1000.0, 1120.0]
+
+
+def test_the_dropped_row_is_logged_with_enough_context(caplog):
+    """The gap is not silent: one warning per fetch names the row and the pair."""
+
+    class _Upstream:
+        @property
+        def market_data(self):
+            return self
+
+        async def get_historical_candles(self, *a, **kw):
+            return [GOOD, MALFORMED, ALSO_GOOD]
+
+        async def get_candles(self, *a, **kw):
+            return []
+
+    with caplog.at_level(logging.WARNING, logger="condor.fetchers.market_data"):
+        rows = asyncio.run(
+            fetch_historical_candles(
+                _Upstream(),
+                "binance",
+                "BTC-USDT",
+                "1m",
+                start_time=1_700_000_000,
+                end_time=1_700_003_600,
+                limit=100,
+                fallback_on_error=True,
+            )
+        )
+
+    assert len(rows) == 2
+    warnings = [r for r in caplog.records if r.levelno == logging.WARNING]
+    assert len(warnings) == 1, "one line per fetch, not one per bad row"
+    message = warnings[0].getMessage()
+    assert "1 of 3" in message
+    assert "BTC-USDT" in message
+    assert "n/a" in message, "the offending row itself must be in the log"
+
+
+def test_a_clean_window_logs_nothing(caplog):
+    class _Upstream:
+        @property
+        def market_data(self):
+            return self
+
+        async def get_historical_candles(self, *a, **kw):
+            return [GOOD, ALSO_GOOD]
+
+        async def get_candles(self, *a, **kw):
+            return []
+
+    with caplog.at_level(logging.WARNING, logger="condor.fetchers.market_data"):
+        rows = asyncio.run(
+            fetch_historical_candles(
+                _Upstream(),
+                "binance",
+                "BTC-USDT",
+                "1m",
+                start_time=1_700_000_000,
+                limit=100,
+            )
+        )
+
+    assert len(rows) == 2
+    assert [r for r in caplog.records if r.levelno == logging.WARNING] == []
+
+
+def test_a_genuine_upstream_outage_is_still_an_upstream_error(monkeypatch):
+    """Degrading on a bad row must not swallow a real failure."""
+    with pytest.raises(Exception) as exc:
+        _call(monkeypatch, _Client(fail=True))
+
+    # Wrapped as the route's upstream error, not leaked as the raw RuntimeError.
+    assert not isinstance(exc.value, RuntimeError)
+    assert getattr(exc.value, "status_code", None) in (502, 503)

From 26ea738fdf63ddf97a6a20981de241ee5a5b79c2 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Fri, 14 Aug 2026 17:22:38 +0300
Subject: [PATCH 083/116] (fix) CORR-175: a mis-called hook dispatch must not
 look like a delivery
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

_fire_hooks wrapped the dispatch call in a broad `except Exception`. That is
right for a failing hook — a broken Telegram delivery is not a reason to fail
the routine run — but it also swallowed the TypeError a signature mismatch
raises. SEC-152 changed dispatch's signature; had it missed one of the two
call sites, hooks would have stopped firing entirely and said so in a single
log line, indistinguishable from a run with no hooks configured.

Catching TypeError separately would be the wrong boundary: dispatch already
absorbs its own delivery failures per chat, and a TypeError raised *while*
delivering is a runtime failure that must stay tolerated. The distinction is
when the error happens, not its type. So the coroutine is now built outside
the try: argument binding happens at creation and nothing in dispatch's body
runs until the await, which makes a call that no longer matches the signature
raise loudly while everything the dispatch itself hits is still logged and
swallowed. Same shape applied to the Telegram call site.

Costs nothing at runtime and needs no inspect/assert scaffolding.
---
 condor/routine_store.py                    | 26 +++++---
 handlers/routines/__init__.py              | 23 ++++---
 tests/test_routine_hooks_error_boundary.py | 75 ++++++++++++++++++++++
 3 files changed, 105 insertions(+), 19 deletions(-)
 create mode 100644 tests/test_routine_hooks_error_boundary.py

diff --git a/condor/routine_store.py b/condor/routine_store.py
index 97051cc5..6d84e20a 100644
--- a/condor/routine_store.py
+++ b/condor/routine_store.py
@@ -324,16 +324,24 @@ async def _fire_hooks(
         routine_name = meta.get("routine_name") if meta else None
         if not routine_name:
             return
+        # Built outside the try on purpose (CORR-175). Binding the arguments
+        # happens here, at coroutine creation; nothing inside ``dispatch`` runs
+        # until it is awaited. So a call that no longer matches the signature
+        # raises TypeError *here* and surfaces, while every failure the dispatch
+        # itself hits stays swallowed below. The boundary is when the error
+        # happens, not its type: a TypeError raised while delivering is a
+        # runtime failure and must not break the run either.
+        coro = routine_hooks.dispatch(
+            routine_name,
+            result,
+            report_id,
+            failed=failed,
+            bot=(self._bot or _http_bot),
+            # Only the hooks of whoever started this run fire (SEC-152).
+            owner_id=meta.get("user_id"),
+        )
         try:
-            await routine_hooks.dispatch(
-                routine_name,
-                result,
-                report_id,
-                failed=failed,
-                bot=(self._bot or _http_bot),
-                # Only the hooks of whoever started this run fire (SEC-152).
-                owner_id=meta.get("user_id"),
-            )
+            await coro
         except Exception as e:
             logger.error(
                 f"Post-execution hooks failed for {routine_name}[{instance_id}]: {e}"
diff --git a/handlers/routines/__init__.py b/handlers/routines/__init__.py
index 09d0c44c..0c99672f 100644
--- a/handlers/routines/__init__.py
+++ b/handlers/routines/__init__.py
@@ -307,17 +307,20 @@ async def _execute_routine(
     hook_result = (
         rich_result if rich_result is not None else normalize_result(result_text)
     )
+    # Built outside the try so a signature mismatch surfaces instead of being
+    # logged as a delivered hook — see RoutineStore._fire_hooks (CORR-175).
+    hook_coro = routine_hooks.dispatch(
+        routine_name,
+        hook_result,
+        report_id,
+        failed=failed,
+        bot=context.bot,
+        # The chat that started the run owns its hooks — the same identity
+        # user_data is keyed by, and the one the store records (SEC-152).
+        owner_id=chat_id,
+    )
     try:
-        await routine_hooks.dispatch(
-            routine_name,
-            hook_result,
-            report_id,
-            failed=failed,
-            bot=context.bot,
-            # The chat that started the run owns its hooks — the same identity
-            # user_data is keyed by, and the one the store records (SEC-152).
-            owner_id=chat_id,
-        )
+        await hook_coro
     except Exception as e:
         logger.error(
             f"Post-execution hooks failed for {routine_name}[{instance_id}]: {e}"
diff --git a/tests/test_routine_hooks_error_boundary.py b/tests/test_routine_hooks_error_boundary.py
new file mode 100644
index 00000000..b7ed09bf
--- /dev/null
+++ b/tests/test_routine_hooks_error_boundary.py
@@ -0,0 +1,75 @@
+"""Tests for CORR-175: a mis-called hook dispatch must not look like a delivery.
+
+``RoutineStore._fire_hooks`` deliberately tolerates a failing hook — a broken
+Telegram delivery is not a reason to fail the routine run. But the broad
+``except Exception`` also swallowed the ``TypeError`` that a signature mismatch
+raises, so a call site left behind by a refactor (SEC-152 changed dispatch's
+signature) would stop firing hooks entirely and say so in one log line.
+
+The fix splits on *when* the error happens, not on its type: the coroutine is
+built outside the try, so argument binding fails loudly, while anything raised
+while awaiting stays swallowed.
+"""
+
+import asyncio
+import logging
+
+import pytest
+
+import condor.routine_hooks as hooks
+from condor.routine_store import RoutineStore
+
+ROUTINE = "brigado/bot_report"
+
+
+class FakeResult:
+    text = "done"
+
+
+@pytest.fixture
+def store():
+    s = RoutineStore()
+    s._instances["i1"] = {"routine_name": ROUTINE, "user_id": 111}
+    return s
+
+
+def test_mis_called_dispatch_surfaces(store, monkeypatch):
+    """A dispatch whose signature no longer matches the call blows up loudly."""
+
+    async def stale_dispatch(routine_name, result, report_id, *, failed, bot):
+        # Pre-SEC-152 signature: no owner_id.
+        raise AssertionError("must not be reached")
+
+    monkeypatch.setattr(hooks, "dispatch", stale_dispatch)
+
+    with pytest.raises(TypeError):
+        asyncio.run(store._fire_hooks("i1", FakeResult(), None, False))
+
+
+def test_delivery_failure_is_tolerated(store, monkeypatch, caplog):
+    """A hook that fails while delivering is logged, and the run survives."""
+
+    async def failing_dispatch(*args, **kwargs):
+        raise RuntimeError("telegram is down")
+
+    monkeypatch.setattr(hooks, "dispatch", failing_dispatch)
+
+    with caplog.at_level(logging.ERROR):
+        asyncio.run(store._fire_hooks("i1", FakeResult(), None, False))
+
+    assert "telegram is down" in caplog.text
+
+
+def test_type_error_raised_while_delivering_is_still_tolerated(store, monkeypatch):
+    """The boundary is when the error happens, not its type.
+
+    A ``TypeError`` from inside the dispatch body is a runtime failure like any
+    other and must not break the routine run — only a mismatched *call* does.
+    """
+
+    async def bad_delivery(*args, **kwargs):
+        raise TypeError("bot.send_document got something odd")
+
+    monkeypatch.setattr(hooks, "dispatch", bad_delivery)
+
+    asyncio.run(store._fire_hooks("i1", FakeResult(), None, False))

From 6c7947fa59564a6d0c2a1ad86e883aba8413d4f3 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Fri, 14 Aug 2026 17:26:44 +0300
Subject: [PATCH 084/116] (perf) PERF-173: batch the winddown's journal writes

PERF-136 coalesced the engine's per-tick journal writes into a single file
rewrite via JournalManager.batch(), but left shutdown.py out of scope. Both of
its terminal paths still did append_action followed by record_tick, rewriting
journal.md twice per winddown.

Each path now wraps that pair in journal.batch(), the same idiom TickEngine
uses: 2 writes -> 1, and the flush-in-finally means a winddown that raises
still journals the action it had recorded. The opening shutdown_start stays
its own unbatched write on purpose -- it must land before the API-bound
winddown, not after it.

Once per session rather than per tick, so the saving is small; the point is
that the two writers now share one idiom.
---
 condor/agents/shutdown.py | 24 ++++++-----
 tests/test_shutdown.py    | 85 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 99 insertions(+), 10 deletions(-)

diff --git a/condor/agents/shutdown.py b/condor/agents/shutdown.py
index 3912b859..a6ed6095 100644
--- a/condor/agents/shutdown.py
+++ b/condor/agents/shutdown.py
@@ -380,10 +380,11 @@ async def run_shutdown(engine: Any, reason: str) -> None:
         log.error(msg)
         await engine._notify(msg)
         if engine.journal:
-            engine.journal.append_action(
-                engine.journal.tick_count + 1, "shutdown_failed", "no API client"
-            )
-            engine.journal.record_tick("shutdown failed (no client): " + reason)
+            with engine.journal.batch():
+                engine.journal.append_action(
+                    engine.journal.tick_count + 1, "shutdown_failed", "no API client"
+                )
+                engine.journal.record_tick("shutdown failed (no client): " + reason)
         return
 
     stopped, failures = await _deterministic_baseline(engine, client, policy)
@@ -412,9 +413,12 @@ async def run_shutdown(engine: Any, reason: str) -> None:
 
     if engine.journal:
         verified = "flat" if not stranded else f"{len(stranded)} stranded"
-        engine.journal.append_action(
-            engine.journal.tick_count + 1,
-            "shutdown_done",
-            f"stopped={stopped}, failures={len(failures)}, verify={verified}",
-        )
-        engine.journal.record_tick("shutdown: " + reason)
+        # Both journal.md updates of this winddown go into one batch, so the file
+        # is rewritten once instead of twice (PERF-136 idiom, PERF-173).
+        with engine.journal.batch():
+            engine.journal.append_action(
+                engine.journal.tick_count + 1,
+                "shutdown_done",
+                f"stopped={stopped}, failures={len(failures)}, verify={verified}",
+            )
+            engine.journal.record_tick("shutdown: " + reason)
diff --git a/tests/test_shutdown.py b/tests/test_shutdown.py
index b5175806..273c3bd5 100644
--- a/tests/test_shutdown.py
+++ b/tests/test_shutdown.py
@@ -6,11 +6,16 @@
 """
 
 import asyncio
+from contextlib import contextmanager
 from types import SimpleNamespace
 
+import pytest
+
+import condor.agents.journal as journal_mod
 from condor.agents import shutdown as shutdown_module
 from condor.agents import strategy as strategy_module
 from condor.agents.engine import TickEngine
+from condor.agents.journal import JournalManager
 from condor.agents.shutdown import (
     DEFAULT_POLICY,
     POLICY_FLATTEN_ALL,
@@ -181,6 +186,10 @@ def __init__(self):
         self.actions = []
         self.ticks = []
 
+    @contextmanager
+    def batch(self):
+        yield self
+
     def append_action(self, tick, action, reasoning, risk_note=""):
         self.actions.append((action, reasoning))
 
@@ -280,6 +289,82 @@ async def _no_client():
     assert any("🚨" in n and "could NOT reach the API" in n for n in notes)
 
 
+# ── journal write amplification (PERF-173) ──
+
+
+@pytest.fixture
+def journal_writes(monkeypatch) -> list[str]:
+    """Record every full rewrite of a journal.md, in order."""
+    recorded: list[str] = []
+    original = journal_mod.atomic_write_text
+
+    def spy(path, text, **kwargs):
+        if str(path).endswith("journal.md"):
+            recorded.append(text)
+        return original(path, text, **kwargs)
+
+    monkeypatch.setattr(journal_mod, "atomic_write_text", spy)
+    return recorded
+
+
+def _with_real_journal(engine, tmp_path) -> JournalManager:
+    engine.journal = JournalManager(engine.agent_id, session_dir=tmp_path)
+    return engine.journal
+
+
+def test_winddown_rewrites_the_journal_once_at_the_end(
+    tmp_path, monkeypatch, journal_writes
+):
+    """The terminal pair (append_action + record_tick) wrote the file twice."""
+    running = [{"id": "e_perp", "connector": "binance_perpetual"}]
+    engine, _client, _notes = _fake_engine(running, [[]], monkeypatch, tmp_path)
+    _with_real_journal(engine, tmp_path)
+
+    asyncio.run(run_shutdown(engine, "breach"))
+
+    # shutdown_start (its own write, so it lands before the API-bound winddown)
+    # plus ONE write for the shutdown_done pair -- three writes before.
+    assert len(journal_writes) == 2
+    last = journal_writes[-1]
+    assert "shutdown_done" in last and "- tick#1 " in last
+
+
+def test_winddown_without_client_rewrites_the_journal_once(
+    tmp_path, monkeypatch, journal_writes
+):
+    engine, _client, _notes = _fake_engine([], [[]], monkeypatch, tmp_path)
+    _with_real_journal(engine, tmp_path)
+
+    async def _no_client():
+        return None
+
+    engine._get_client = _no_client
+    asyncio.run(run_shutdown(engine, "breach"))
+
+    assert len(journal_writes) == 2
+    last = journal_writes[-1]
+    assert "shutdown_failed" in last and "- tick#1 " in last
+
+
+def test_a_winddown_that_raises_still_journals_what_it_recorded(
+    tmp_path, monkeypatch, journal_writes
+):
+    """The batch flushes in a finally, so the recorded action is not lost."""
+    running = [{"id": "e_perp", "connector": "binance_perpetual"}]
+    engine, _client, _notes = _fake_engine(running, [[]], monkeypatch, tmp_path)
+    journal = _with_real_journal(engine, tmp_path)
+
+    def boom(*args, **kwargs):
+        raise RuntimeError("disk on fire")
+
+    monkeypatch.setattr(journal, "record_tick", boom)
+
+    with pytest.raises(RuntimeError):
+        asyncio.run(run_shutdown(engine, "breach"))
+
+    assert "shutdown_done" in journal._path.read_text()
+
+
 # ── engine wrapper idempotency ──
 
 

From 069a4bd3f0f97a22a8e25f1bcf3c6277a22c3981 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Fri, 14 Aug 2026 17:41:00 +0300
Subject: [PATCH 085/116] (refactor) READ-172: drop the dead `email` block from
 routine hook configs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Hook configs on disk carry an `email` block with recipients, sitting next to
the telegram one as if it were a live destination. It is not: the sender was
deleted in cb4b213 and `_default_config` never rebuilt the field, so the block
was inert config that any save silently discarded — a user's recipients could
vanish on the next hooks edit with nothing said.

Drop it on *load* instead of on save. `_normalize` strips the field from every
stored config it returns, so what the dashboard shows, what dispatch acts on,
and what the next save writes are finally the same shape, and the discard
lands in the log rather than nowhere. `data/routine_hooks.json` is a user's
live runtime state and is not tracked by git, so nothing rewrites it here: an
existing file keeps loading, keeps its telegram destinations, and is cleaned
the next time hooks are saved.

Also removes the `"email"` arm of the legacy-shape sniff in `_normalize`. Pre-
SEC-152 configs always wrote `telegram` and `trigger` alongside `email`, so
that arm never discriminated an entry the other two missed, and the field is
stripped before the check now anyway.

Tests cover a legacy on-disk config carrying an `email` block in both stored
shapes: it loads, it still delivers to telegram, the dashboard never sees the
dead field, and the next write cleans the file.
---
 condor/routine_hooks.py               | 65 ++++++++++++++++++++++----
 tests/test_routine_hooks_ownership.py | 67 +++++++++++++++++++++++++++
 2 files changed, 124 insertions(+), 8 deletions(-)

diff --git a/condor/routine_hooks.py b/condor/routine_hooks.py
index 4bd33a7c..2e2f7165 100644
--- a/condor/routine_hooks.py
+++ b/condor/routine_hooks.py
@@ -33,6 +33,13 @@
 ``_UNOWNED`` key: they are nobody's, so they no longer fire for everyone —
 only an admin's runs trigger them, and an admin saving that routine's hooks
 adopts them under their own id.
+
+Dead ``email`` block (READ-172). Hooks once had an email destination; the
+sender was deleted long ago, so configs written back then carry an ``email``
+block nothing reads and every save quietly dropped. It is now dropped on
+*load* instead — see :data:`_DEAD_FIELDS` — so the config the dashboard shows,
+the config dispatch acts on, and the config a save writes are the same thing,
+and an old file on disk still loads without a fuss.
 """
 
 from __future__ import annotations
@@ -56,6 +63,14 @@
 # on disk, readable and adoptable by an admin, fired only for an admin's runs.
 _UNOWNED = ""
 
+# Config keys written by older builds that no code reads anymore (READ-172).
+# Dropped when a stored entry is loaded, not when it is saved.
+_DEAD_FIELDS = ("email",)
+
+# Routines already logged about, so a stale file does not repeat itself on
+# every read.
+_dead_field_warned: set[str] = set()
+
 
 class ForbiddenRecipient(Exception):
     """Raised when a hook targets a chat its owner is not allowed to reach."""
@@ -97,19 +112,53 @@ def _allowed_recipient(chat_id: str, user_id: int | None) -> bool:
 # ── Persistence ──
 
 
-def _normalize(entry: Any) -> dict[str, dict]:
+def _strip_dead_fields(cfg: Any, routine_name: str) -> Any:
+    """Drop config keys no code reads anymore, so a stale file still loads.
+
+    A user's ``routine_hooks.json`` is live state we do not get to rewrite out
+    from under them, so removing a destination from the code has to leave the
+    old shape loadable. Dropping it here — rather than letting the next
+    ``save_hooks`` silently discard it — keeps what is read, shown and written
+    identical, and the discard shows up in the log instead of nowhere.
+    """
+    if not isinstance(cfg, dict):
+        return cfg
+    dead = [k for k in _DEAD_FIELDS if k in cfg]
+    if not dead:
+        return cfg
+    if routine_name not in _dead_field_warned:
+        _dead_field_warned.add(routine_name)
+        logger.info(
+            "Dropping unused hook field(s) %s from %s; nothing has sent to them "
+            "since the email destination was removed",
+            ", ".join(dead),
+            routine_name,
+        )
+    return {k: v for k, v in cfg.items() if k not in _DEAD_FIELDS}
+
+
+def _normalize(entry: Any, routine_name: str) -> dict[str, dict]:
     """Coerce one stored routine entry into ``{owner_key: config}``.
 
     Pre-SEC-152 files hold a bare config per routine name. Those entries are
-    preserved as-is under :data:`_UNOWNED` rather than dropped or reassigned to
-    a made-up owner — losing an admin's delivery config silently would be as
-    bad a surprise as leaving it firing for everyone.
+    preserved under :data:`_UNOWNED` rather than dropped or reassigned to a
+    made-up owner — losing an admin's delivery config silently would be as bad
+    a surprise as leaving it firing for everyone.
+
+    A bare config is told apart from an owner map by its known keys. ``email``
+    is deliberately not one of them: those files always carried ``telegram``
+    and ``trigger`` alongside it, so it never discriminated anything, and it is
+    stripped before the check anyway.
     """
     if not isinstance(entry, dict):
         return {}
-    if "telegram" in entry or "trigger" in entry or "email" in entry:
-        return {_UNOWNED: entry}
-    return {str(k): v for k, v in entry.items() if isinstance(v, dict)}
+    if "telegram" in entry or "trigger" in entry:
+        return {_UNOWNED: _strip_dead_fields(entry, routine_name)}
+    return {
+        str(k): _strip_dead_fields(v, routine_name)
+        for k, v in entry.items()
+        if isinstance(v, dict)
+    }
 
 
 def _read_all() -> dict[str, dict[str, dict]]:
@@ -119,7 +168,7 @@ def _read_all() -> dict[str, dict[str, dict]]:
         data = json.loads(_HOOKS_FILE.read_text())
         if not isinstance(data, dict):
             return {}
-        return {name: _normalize(entry) for name, entry in data.items()}
+        return {name: _normalize(entry, name) for name, entry in data.items()}
     except Exception:  # noqa: BLE001
         logger.warning("Failed to read %s; treating as empty", _HOOKS_FILE)
         return {}
diff --git a/tests/test_routine_hooks_ownership.py b/tests/test_routine_hooks_ownership.py
index 6665ca09..6a1c5693 100644
--- a/tests/test_routine_hooks_ownership.py
+++ b/tests/test_routine_hooks_ownership.py
@@ -43,6 +43,8 @@ def hooks_file(tmp_path, monkeypatch):
     path = tmp_path / "routine_hooks.json"
     monkeypatch.setattr(hooks, "_HOOKS_FILE", path)
     monkeypatch.setattr(config_manager, "get_config_manager", FakeConfigManager)
+    # The "dropped a dead field" log fires once per routine per process.
+    monkeypatch.setattr(hooks, "_dead_field_warned", set())
     return path
 
 
@@ -262,3 +264,68 @@ async def fake_dispatch(name, result, report_id, *, failed, bot, owner_id):
     asyncio.run(store._fire_hooks("i1", FakeResult(), None, False))
 
     assert seen == {"name": ROUTINE, "owner_id": OWNER.id}
+
+
+# ── READ-172: the dead `email` block on old on-disk configs ──
+
+
+def legacy_email_body(chat_ids, recipients=("someone@example.com",)):
+    """A hook config as written before the email destination was deleted."""
+    body = hook_body(chat_ids)
+    body["email"] = {"enabled": True, "recipients": list(recipients)}
+    return body
+
+
+def test_owned_config_with_a_legacy_email_block_still_loads(hooks_file):
+    """A config a user already has on disk must survive the field's removal."""
+    write_raw(
+        hooks_file, {ROUTINE: {str(OWNER.id): legacy_email_body([str(OWNER.id)])}}
+    )
+
+    cfg = hooks.load_hooks(ROUTINE, OWNER.id)
+
+    assert cfg is not None, "an old config must not fail to load"
+    assert "email" not in cfg
+    assert cfg["telegram"]["chat_ids"] == [str(OWNER.id)]
+    assert cfg["trigger"] == "success"
+
+
+def test_unowned_legacy_entry_with_an_email_block_still_loads(hooks_file):
+    write_raw(hooks_file, {ROUTINE: legacy_email_body([GROUP_CHAT])})
+
+    cfg = hooks.load_hooks(ROUTINE, ADMIN.id)
+
+    assert cfg is not None
+    assert "email" not in cfg
+    assert cfg["telegram"]["chat_ids"] == [GROUP_CHAT]
+
+
+def test_a_legacy_email_block_does_not_stop_telegram_delivery(hooks_file):
+    write_raw(
+        hooks_file, {ROUTINE: {str(OWNER.id): legacy_email_body([str(OWNER.id)])}}
+    )
+    bot = FakeBot()
+
+    fire(ROUTINE, OWNER.id, bot)
+
+    assert bot.sent == [OWNER.id]
+
+
+def test_the_dashboard_is_never_shown_the_dead_email_block(make_client, hooks_file):
+    write_raw(
+        hooks_file, {ROUTINE: {str(OWNER.id): legacy_email_body([str(OWNER.id)])}}
+    )
+
+    assert "email" not in make_client(OWNER).get(f"/routines/{ROUTINE}/hooks").json()
+
+
+def test_the_email_block_is_dropped_on_load_not_silently_on_save(hooks_file):
+    """The next write cleans the file because the *loader* already dropped it."""
+    write_raw(hooks_file, {ROUTINE: legacy_email_body([GROUP_CHAT])})
+
+    # Saving an unrelated routine rewrites the whole file.
+    hooks.save_hooks("other_routine", hook_body([str(OWNER.id)]), OWNER.id)
+
+    stored = read_raw(hooks_file)
+    assert "email" not in stored[ROUTINE][""]
+    assert stored[ROUTINE][""]["telegram"]["chat_ids"] == [GROUP_CHAT]

From efb5191e58f7837aea3579308accc30cb654999a Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Fri, 14 Aug 2026 17:46:03 +0300
Subject: [PATCH 086/116] (fix) CORR-163: bound the routine store's instance
 dict
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CORR-142 bounded `_results` and stopped there. `_instances` leaked in the
same shape: every `execute()` mints a fresh instance id, and the only
removals were the explicit `remove_instance` and `stop` paths, so a one-shot
that simply completed was never reaped. Slower than the PNG leak — metadata,
not payload — but monotonic in a process designed to run for weeks with
schedules firing on an interval.

Retention, not deletion-on-completion. A finished one-shot is not garbage:
the dashboard renders its detail panel after the run ends, fetches the chart
only when the user opens that run, and an MCP agent that submitted with
`run_async` reads it back through `get_instance` an unbounded time later.
Dropping the record the moment the run ends would 404 all three. So the
record outlives its run, and only the cap ends it: the oldest terminal
instances past `_MAX_TERMINAL_INSTANCES` are evicted, oldest by last run.

The cap is global and deliberately the same number as `_MAX_RESULTS`: an
instance older than the result cap has already lost its result and is a
hollow record, and sharing the bound is what keeps the two dicts from
drifting. Eviction goes through `remove_instance`, so a dropped instance
takes its result and its `_tasks` entry with it — `set(_results) <=
set(_instances)` still holds, and `_tasks`, which leaked the same way for
completed one-shots, is bounded by the same cap for free.

Liveness is checked twice, because evicting a live run would be worse than
the leak: the status must be terminal (`completed`/`failed`/`stopped`) and
the instance's task must be off the loop. A scheduled instance sits at
`scheduled` between ticks and a Telegram-owned one keeps `running` for its
whole life, so neither is ever a candidate — and neither counts toward the
cap, so one-shot churn cannot push a live instance over the edge either.
---
 condor/routine_store.py                  |  65 ++++++++
 tests/test_routine_instance_retention.py | 182 +++++++++++++++++++++++
 2 files changed, 247 insertions(+)
 create mode 100644 tests/test_routine_instance_retention.py

diff --git a/condor/routine_store.py b/condor/routine_store.py
index 6d84e20a..4bb04491 100644
--- a/condor/routine_store.py
+++ b/condor/routine_store.py
@@ -157,6 +157,30 @@ def user_data(self) -> dict:
 # in a process designed to run for weeks.
 _MAX_RESULTS = 200
 
+# CORR-163: the same bound, applied to the instance records themselves.
+# `_results` was the expensive half of the leak (a RoutineResult can pin a raw
+# PNG) but the `_instances` entry that owns it leaked in exactly the same shape:
+# every `execute()` mints a fresh id, and only the explicit `remove_instance`
+# and `stop` paths ever dropped one, so a completed one-shot was never reaped.
+#
+# Retention, not deletion-on-completion: a finished one-shot is precisely what
+# the dashboard's detail panel renders after the run ends and what an MCP agent
+# reads back through `get_instance` after a `run_async`, so the record has to
+# outlive its own run. Only *terminal* instances count against the cap —
+# anything in flight, continuous or scheduled is exempt from the count and from
+# eviction, so a scheduled routine can never be reaped out from under its own
+# task no matter how many one-shots run alongside it.
+#
+# Deliberately the same number as `_MAX_RESULTS`: an instance older than the
+# result cap has already lost its result and is a hollow record, and sharing the
+# bound is what keeps the two dicts from drifting apart.
+_MAX_TERMINAL_INSTANCES = _MAX_RESULTS
+
+# Statuses a run cannot come back from. `running` (one-shot in flight, or a
+# Telegram-owned instance, which keeps that status for its whole life) and
+# `scheduled` (between ticks of an interval schedule) are the live ones.
+_TERMINAL_STATUSES = frozenset({"completed", "failed", "stopped"})
+
 
 class RoutineStore:
     """Singleton store for routine instances and results."""
@@ -279,6 +303,7 @@ def get_instance(self, instance_id: str) -> dict | None:
 
     def add_instance(self, instance_id: str, metadata: dict) -> None:
         self._instances[instance_id] = metadata
+        self._prune_instances()
 
     def remove_instance(self, instance_id: str) -> None:
         self._instances.pop(instance_id, None)
@@ -289,6 +314,43 @@ def remove_instance(self, instance_id: str) -> None:
         # behind here is unreachable memory rather than a cache.
         self._results.pop(instance_id, None)
 
+    def _has_live_task(self, instance_id: str) -> bool:
+        """True while the instance's own task is still on the loop."""
+        task = self._tasks.get(instance_id)
+        return task is not None and not task.done()
+
+    def _prune_instances(self) -> None:
+        """Evict the oldest terminal instances past ``_MAX_TERMINAL_INSTANCES``.
+
+        The backstop for the unbounded case: every ``execute()`` mints a fresh
+        instance id and a one-shot that completes normally is removed by nobody,
+        so without this the dict is monotonic for the life of the process.
+
+        Only instances in a terminal status are candidates, and only once their
+        task is off the loop — a run still in flight, a continuous routine and a
+        scheduled one between ticks are all exempt from eviction *and* from the
+        count, so no amount of one-shot churn can reap a live instance or push a
+        live one over the edge. The just-finished run is excluded on its own
+        prune for the same reason (its task is still executing this call); it is
+        the youngest candidate anyway, so it is never the one to go.
+
+        Oldest-first by last run, falling back to creation for an instance that
+        never ran. Eviction goes through ``remove_instance`` so a dropped
+        instance takes its result and its task entry with it, preserving
+        CORR-142's ``set(_results) <= set(_instances)``.
+        """
+        terminal = [
+            (meta.get("last_run_at") or meta.get("created_at") or 0.0, iid)
+            for iid, meta in self._instances.items()
+            if meta.get("status") in _TERMINAL_STATUSES and not self._has_live_task(iid)
+        ]
+        excess = len(terminal) - _MAX_TERMINAL_INSTANCES
+        if excess <= 0:
+            return
+        terminal.sort()
+        for _, iid in terminal[:excess]:
+            self.remove_instance(iid)
+
     # ── Results ──
 
     def store_result(self, instance_id: str, result: RoutineResult) -> None:
@@ -525,6 +587,9 @@ async def _execute_and_record(
                     "error": error_msg,
                 }
             )
+            # The run just reached its final status: this is the moment a new
+            # terminal instance appears, so it is the moment to enforce the cap.
+            self._prune_instances()
 
         # Usage telemetry (FEAT-023): whether it ran, how it was triggered and
         # how long it took. The routine's own name only when the file ships in
diff --git a/tests/test_routine_instance_retention.py b/tests/test_routine_instance_retention.py
new file mode 100644
index 00000000..a77a022a
--- /dev/null
+++ b/tests/test_routine_instance_retention.py
@@ -0,0 +1,182 @@
+"""CORR-163: the store's instance dict is bounded, and only for finished runs.
+
+``RoutineStore._instances`` only ever grew: every ``execute()`` mints a fresh
+instance id and the only removals were the explicit ``remove_instance`` and
+``stop`` paths, so a one-shot that simply completed was never reaped — a slow
+but monotonic leak in a process designed to run for weeks with scheduled
+routines firing on an interval.
+
+The fix is retention, not deletion-on-completion. A finished one-shot is what
+the dashboard's detail panel renders after the run ends and what an MCP agent
+reads back through ``get_instance`` after a ``run_async``, so the record has to
+outlive its run; what it must not do is outlive the cap. Only *terminal*
+instances count, and only once their task is off the loop, so a run in flight, a
+continuous routine and a scheduled one between ticks are never candidates.
+"""
+
+import asyncio
+import time
+from types import SimpleNamespace
+
+import pytest
+from pydantic import BaseModel
+
+import condor.reports as rep
+from condor.routine_store import _MAX_TERMINAL_INSTANCES, RoutineStore
+from routines.base import RoutineResult
+
+
+@pytest.fixture
+def reports_dir(tmp_path, monkeypatch):
+    monkeypatch.setattr(rep, "CHARTS_DIR", tmp_path)
+    monkeypatch.setattr(rep, "INDEX_FILE", tmp_path / "reports_index.json")
+    return tmp_path
+
+
+def _routine():
+    class Config(BaseModel):
+        pass
+
+    async def run_fn(config, ctx):
+        return "run output"
+
+    return SimpleNamespace(
+        name="probe", source="global", config_class=Config, run_fn=run_fn
+    )
+
+
+def _terminal(store: RoutineStore, iid: str, *, age: float, status="completed"):
+    """A finished run, already off the loop, that ran ``age`` seconds ago."""
+    meta = store._new_instance_meta("probe", {}, "srv", 0, source="web")
+    meta["status"] = status
+    meta["last_run_at"] = time.time() - age
+    store._instances[iid] = meta
+    store._results[iid] = RoutineResult(text=iid)
+
+
+# ── The bound is enforced ──
+
+
+def test_one_shot_runs_stop_growing_the_instance_dict(reports_dir):
+    """The leak itself: N one-shots used to leave N instances behind forever."""
+    store = RoutineStore()
+    routine = _routine()
+
+    for n in range(_MAX_TERMINAL_INSTANCES + 50):
+        iid = f"run-{n:04d}"
+        store._instances[iid] = store._new_instance_meta(
+            "probe", {}, "srv", 0, source="web"
+        )
+        asyncio.run(
+            store._execute_and_record(
+                iid, routine, {}, "srv", status_after="completed", fire_hooks=False
+            )
+        )
+
+    # +1: the run that triggers a prune is still executing its own task, so it
+    # is exempt from that pass and settles on the next one.
+    assert len(store._instances) <= _MAX_TERMINAL_INSTANCES + 1
+    assert set(store._results) <= set(store._instances)
+
+
+def test_the_oldest_finished_runs_are_the_ones_evicted():
+    store = RoutineStore()
+    for n in range(_MAX_TERMINAL_INSTANCES + 10):
+        # Descending age: run-0 is the oldest.
+        _terminal(store, f"run-{n:04d}", age=10_000 - n)
+
+    store._prune_instances()
+
+    assert len(store._instances) == _MAX_TERMINAL_INSTANCES
+    assert "run-0000" not in store._instances
+    assert "run-0009" not in store._instances
+    assert "run-0010" in store._instances
+    assert f"run-{_MAX_TERMINAL_INSTANCES + 9:04d}" in store._instances
+
+
+def test_evicting_an_instance_takes_its_result_with_it():
+    """No orphan in ``_results`` — CORR-142's invariant survives eviction."""
+    store = RoutineStore()
+    for n in range(_MAX_TERMINAL_INSTANCES + 10):
+        _terminal(store, f"run-{n:04d}", age=10_000 - n)
+
+    store._prune_instances()
+
+    assert store.get_result("run-0000") is None
+    assert set(store._results) <= set(store._instances)
+
+
+def test_a_terminal_instance_is_not_evicted_below_the_cap():
+    store = RoutineStore()
+    _terminal(store, "old", age=10_000_000)
+
+    store._prune_instances()
+
+    assert "old" in store._instances
+    assert store.get_result("old") is not None
+
+
+# ── Live instances are exempt ──
+
+
+def test_a_running_instance_is_never_evicted():
+    """An in-flight one-shot outlives any amount of churn around it."""
+    store = RoutineStore()
+    inflight = store._new_instance_meta("probe", {}, "srv", 0, source="web")
+    inflight["created_at"] = 0.0  # the oldest thing in the dict
+    store._instances["inflight"] = inflight
+    store._tasks["inflight"] = SimpleNamespace(done=lambda: False)
+    for n in range(_MAX_TERMINAL_INSTANCES + 10):
+        _terminal(store, f"run-{n:04d}", age=1000 - n)
+
+    store._prune_instances()
+
+    assert "inflight" in store._instances
+    assert store._instances["inflight"]["status"] == "running"
+
+
+def test_a_scheduled_instance_is_never_evicted():
+    """A schedule sits idle between ticks — old by every clock, still alive."""
+    store = RoutineStore()
+    scheduled = store._new_instance_meta(
+        "probe", {}, "srv", 0, source="web", status="scheduled"
+    )
+    scheduled["created_at"] = 0.0
+    scheduled["last_run_at"] = 0.0
+    store._instances["sched"] = scheduled
+    for n in range(_MAX_TERMINAL_INSTANCES + 10):
+        _terminal(store, f"run-{n:04d}", age=1000 - n)
+
+    store._prune_instances()
+
+    assert "sched" in store._instances
+    # And it does not count against the cap: the terminal ones alone fill it.
+    assert len(store._instances) == _MAX_TERMINAL_INSTANCES + 1
+
+
+def test_a_terminal_instance_whose_task_is_still_alive_is_exempt():
+    """Belt and braces: status says stopped, the loop says otherwise."""
+    store = RoutineStore()
+    _terminal(store, "cancelling", age=10_000_000, status="stopped")
+    store._tasks["cancelling"] = SimpleNamespace(done=lambda: False)
+    for n in range(_MAX_TERMINAL_INSTANCES + 10):
+        _terminal(store, f"run-{n:04d}", age=1000 - n)
+
+    store._prune_instances()
+
+    assert "cancelling" in store._instances
+
+
+def test_telegram_instances_are_not_touched():
+    """Telegram-owned instances stay ``running`` for life and are removed by hand."""
+    store = RoutineStore()
+    meta = store._new_instance_meta("probe", {}, "srv", 0, source="telegram")
+    meta["created_at"] = 0.0
+    store.add_instance("tg", meta)
+    for n in range(_MAX_TERMINAL_INSTANCES + 10):
+        _terminal(store, f"run-{n:04d}", age=1000 - n)
+
+    store.add_instance("tg2", dict(meta))
+
+    assert "tg" in store._instances
+    assert "tg2" in store._instances

From 66fae0935791cfb2a850f5741ba5053a7b982521 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Fri, 14 Aug 2026 17:51:57 +0300
Subject: [PATCH 087/116] (fix) CORR-165: a Telegram-started routine belongs to
 the user who started it
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

SEC-150 gates the dashboard's routine-instance endpoints on the ``user_id``
in the instance meta, but the Telegram bridge only ever threaded ``chat_id``:
every routine started from Telegram reached the store unowned, so the gate —
which fails closed — hid it from the very person who started it and left it
admin-only.

The owner is now stamped where the run is born: ``_create_scheduled_instance``
and ``_create_continuous_instance`` take a ``user_id`` and every Telegram call
site passes ``_starter_id(update)`` — the *user*, not the chat, so a run
launched in a group attributes to the member who pressed the button rather
than to the room. ``_sync_instance_to_store`` never downgrades a recorded
owner, so a later tick whose meta lost the field can't un-own a live instance.

Pre-existing instances: the gate is left untouched (ownerless stays
admin-only, as SEC-167 chose for ownerless sessions) and the adoption happens
at load instead, like READ-172 — ``restore_scheduled_jobs`` stamps the owner
of an ownerless persisted instance from the ``user_data`` bucket holding it,
which PTB keys by user id, so that is the real starter and not a guess.
Anything still ownerless afterwards (MCP runs that carried no user) keeps
failing closed.

Status handling is unchanged, so CORR-163's eviction still exempts these
instances while they sit at ``running``.
---
 condor/web/routes/routines.py            |   9 +-
 handlers/routines/__init__.py            |  67 +++++-
 tests/test_routine_telegram_ownership.py | 268 +++++++++++++++++++++++
 3 files changed, 331 insertions(+), 13 deletions(-)
 create mode 100644 tests/test_routine_telegram_ownership.py

diff --git a/condor/web/routes/routines.py b/condor/web/routes/routines.py
index b033f60e..5af572a8 100644
--- a/condor/web/routes/routines.py
+++ b/condor/web/routes/routines.py
@@ -77,10 +77,11 @@ def _owns(inst: dict, user: WebUser) -> bool:
     """Whether ``user`` started this instance.
 
     The owner is the ``user_id`` RoutineStore records in the instance meta.
-    An instance without one is nobody's: MCP runs that carried no user and
-    Telegram instances synced into the store both land here, and treating them
-    as unowned keeps them out of every non-admin's reach instead of handing
-    them to whoever asks first.
+    Telegram-started instances now carry it too (CORR-165: the starting user,
+    not the chat). An instance without one is nobody's — MCP runs that carried
+    no user, or meta written by an older build — and treating them as unowned
+    keeps them out of every non-admin's reach instead of handing them to
+    whoever asks first.
     """
     owner = inst.get("user_id")
     return bool(owner) and owner == user.id
diff --git a/handlers/routines/__init__.py b/handlers/routines/__init__.py
index 0c99672f..0521ef93 100644
--- a/handlers/routines/__init__.py
+++ b/handlers/routines/__init__.py
@@ -104,18 +104,36 @@ def _get_routine_instances(
     ]
 
 
+def _starter_id(update: Update) -> int | None:
+    """The user who pressed the button — the owner of whatever they start.
+
+    ``chat_id`` only coincides with it in private chats; in a group the routine
+    belongs to the member who launched it, not to the group.
+    """
+    return update.effective_user.id if update.effective_user else None
+
+
 def _generate_instance_id() -> str:
     """Generate a short unique instance ID."""
     return hashlib.md5(f"{time.time()}{id(object())}".encode()).hexdigest()[:6]
 
 
 def _sync_instance_to_store(instance_id: str, inst_meta: dict) -> None:
-    """Sync a Telegram instance's state to the shared RoutineStore."""
+    """Sync a Telegram instance's state to the shared RoutineStore.
+
+    The owner (``user_id``, stamped at creation) is never downgraded: a later
+    tick whose meta lost it must not turn an owned instance into an unowned
+    one, which the dashboard's ownership gate (SEC-150) would hide from its
+    own starter.
+    """
     try:
         store = get_routine_store()
         existing = store._instances.get(instance_id)
         if existing:
-            existing.update(inst_meta)
+            update = dict(inst_meta)
+            if not update.get("user_id") and existing.get("user_id"):
+                update.pop("user_id", None)
+            existing.update(update)
         else:
             store.add_instance(instance_id, inst_meta.copy())
     except Exception:
@@ -601,8 +619,14 @@ def _create_scheduled_instance(
     schedule: dict,
     msg_id: int | None = None,
     background: bool = False,
+    user_id: int | None = None,
 ) -> str:
-    """Create a scheduled one-shot instance. Returns instance_id."""
+    """Create a scheduled one-shot instance. Returns instance_id.
+
+    ``user_id`` is the Telegram user who started it — the owner the dashboard
+    checks (SEC-150). It is not ``chat_id``: in a group those differ, and the
+    run belongs to the person, not to the room.
+    """
     instance_id = _generate_instance_id()
     job_name_str = _job_name(chat_id, instance_id)
 
@@ -614,6 +638,7 @@ def _create_scheduled_instance(
         "schedule": schedule.copy(),
         "status": "running",
         "source": "telegram",
+        "user_id": user_id,
         "created_at": time.time(),
         "last_run_at": None,
         "last_result": None,
@@ -688,8 +713,13 @@ def _create_continuous_instance(
     chat_id: int,
     routine_name: str,
     config_dict: dict,
+    user_id: int | None = None,
 ) -> str:
-    """Create a continuous routine instance. Returns instance_id."""
+    """Create a continuous routine instance. Returns instance_id.
+
+    ``user_id`` is the starting Telegram user (the dashboard owner), which in a
+    group chat is not ``chat_id``.
+    """
     instance_id = _generate_instance_id()
 
     # Capture active server at creation time (same fix as scheduled instances)
@@ -709,6 +739,7 @@ def _create_continuous_instance(
         "schedule": {"type": "continuous"},
         "status": "running",
         "source": "telegram",
+        "user_id": user_id,
         "created_at": time.time(),
         "last_run_at": None,
         "last_result": None,
@@ -1316,7 +1347,14 @@ async def _run_once(
     schedule = {"type": "once"}
 
     _create_scheduled_instance(
-        context, chat_id, routine_name, draft, schedule, msg_id, background
+        context,
+        chat_id,
+        routine_name,
+        draft,
+        schedule,
+        msg_id,
+        background,
+        user_id=_starter_id(update),
     )
 
     if background:
@@ -1352,7 +1390,9 @@ async def _start_continuous(
         await update.callback_query.answer(f"Config error: {e}")
         return
 
-    instance_id = _create_continuous_instance(context, chat_id, routine_name, draft)
+    instance_id = _create_continuous_instance(
+        context, chat_id, routine_name, draft, user_id=_starter_id(update)
+    )
     logger.info(f"Started continuous routine {instance_id}: {routine_name}")
 
     await update.callback_query.answer("▶️ Started")
@@ -1383,7 +1423,7 @@ async def _start_interval(
 
     schedule = {"type": "interval", "interval_sec": interval_sec}
     instance_id = _create_scheduled_instance(
-        context, chat_id, routine_name, draft, schedule
+        context, chat_id, routine_name, draft, schedule, user_id=_starter_id(update)
     )
     logger.info(
         f"Created interval schedule {instance_id} for {routine_name}: every {interval_sec}s"
@@ -1428,7 +1468,7 @@ async def _start_daily(
 
     schedule = {"type": "daily", "daily_time": time_str}
     instance_id = _create_scheduled_instance(
-        context, chat_id, routine_name, draft, schedule
+        context, chat_id, routine_name, draft, schedule, user_id=_starter_id(update)
     )
     logger.info(
         f"Created daily schedule {instance_id} for {routine_name}: at {time_str}"
@@ -1570,7 +1610,9 @@ async def _process_daily_time(
         return
 
     schedule = {"type": "daily", "daily_time": time_str}
-    _create_scheduled_instance(context, chat_id, routine_name, draft, schedule)
+    _create_scheduled_instance(
+        context, chat_id, routine_name, draft, schedule, user_id=_starter_id(update)
+    )
 
     msg = await update.message.reply_text(f"📅 Scheduled daily at {time_str}")
     asyncio.create_task(_delete_after(msg, 2))
@@ -1760,6 +1802,13 @@ async def restore_scheduled_jobs(application) -> int:
             if inst.get("status") != "running":
                 continue
 
+            # Adopt instances persisted before owners were stamped: PTB keys
+            # ``user_data`` by user id, so the bucket holding the instance is
+            # its starter — a fact, not a guess. Anything still ownerless after
+            # this stays admin-only in the dashboard (SEC-150 fails closed).
+            if not inst.get("user_id"):
+                inst["user_id"] = chat_id
+
             routine_name = inst.get("routine_name")
             config_dict = inst.get("config", {})
             schedule = inst.get("schedule", {})
diff --git a/tests/test_routine_telegram_ownership.py b/tests/test_routine_telegram_ownership.py
new file mode 100644
index 00000000..e39d6003
--- /dev/null
+++ b/tests/test_routine_telegram_ownership.py
@@ -0,0 +1,268 @@
+"""Tests for CORR-165: a routine started from Telegram belongs to its starter.
+
+SEC-150 gates the dashboard's instance endpoints on the ``user_id`` recorded in
+the instance meta, but the Telegram bridge only ever threaded ``chat_id``, so
+every Telegram-started routine reached the store unowned and the gate — which
+fails closed — hid it from the very person who started it, leaving it
+admin-only.
+
+The fix stamps the owner at creation (the *user*, not the chat, so a group run
+attributes to the member who pressed the button), never downgrades it on a
+later sync, and adopts instances persisted by an older build at restore time
+from the ``user_data`` bucket holding them (PTB keys that by user id). The
+ownership gate itself is untouched: whatever is still ownerless stays
+admin-only, as SEC-167 chose for ownerless sessions.
+"""
+
+import asyncio
+
+import pytest
+from fastapi import FastAPI
+from starlette.testclient import TestClient
+
+import condor.web.routes.routines as routes_routines
+import handlers.routines as tg_routines
+from condor.web.auth import get_current_user
+from condor.web.models import WebUser
+
+STARTER = WebUser(id=111, username="starter", first_name="S", role="user")
+STRANGER = WebUser(id=222, username="stranger", first_name="X", role="user")
+ADMIN = WebUser(id=999, username="admin", first_name="A", role="admin")
+
+GROUP_CHAT = -1002222222222
+
+
+# ── Doubles ──
+
+
+class FakeStore:
+    """Just the slice of RoutineStore the Telegram bridge and the routes use."""
+
+    def __init__(self):
+        self._instances = {}
+
+    def add_instance(self, instance_id, metadata):
+        self._instances[instance_id] = metadata
+
+    def get_instance(self, instance_id):
+        return self._instances.get(instance_id)
+
+    def list_instances(self):
+        return [dict(meta, instance_id=iid) for iid, meta in self._instances.items()]
+
+    def get_result(self, instance_id):
+        return None
+
+    def stop(self, instance_id):
+        return self._instances.pop(instance_id, None) is not None
+
+
+class FakeJobQueue:
+    def __init__(self):
+        self.jobs = []
+
+    def _record(self, **kwargs):
+        self.jobs.append(kwargs)
+
+    def run_once(self, callback, **kwargs):
+        self._record(kind="once", **kwargs)
+
+    def run_repeating(self, callback, **kwargs):
+        self._record(kind="repeating", **kwargs)
+
+    def run_daily(self, callback, **kwargs):
+        self._record(kind="daily", **kwargs)
+
+    def get_jobs_by_name(self, name):
+        return []
+
+
+class FakeContext:
+    def __init__(self):
+        self.user_data = {}
+        self.job_queue = FakeJobQueue()
+        self.application = None
+
+
+class FakeUpdate:
+    """Only ``effective_chat`` / ``effective_user`` matter to the creators."""
+
+    def __init__(self, chat_id, user_id):
+        self.effective_chat = type("Chat", (), {"id": chat_id})()
+        self.effective_user = type("User", (), {"id": user_id})()
+
+
+class FakeConfigManager:
+    def is_admin(self, user_id):
+        return user_id == ADMIN.id
+
+
+@pytest.fixture
+def store(monkeypatch):
+    fake = FakeStore()
+    monkeypatch.setattr(tg_routines, "get_routine_store", lambda: fake)
+    monkeypatch.setattr(routes_routines, "get_routine_store", lambda: fake)
+    monkeypatch.setattr(routes_routines, "get_config_manager", FakeConfigManager)
+    return fake
+
+
+@pytest.fixture
+def make_client():
+    def _make(user: WebUser):
+        app = FastAPI()
+        app.include_router(routes_routines.router)
+        app.dependency_overrides[get_current_user] = lambda: user
+        return TestClient(app)
+
+    return _make
+
+
+def start_from_telegram(store, chat_id=STARTER.id, user_id=STARTER.id, **kwargs):
+    """Start a scheduled routine the way the Telegram handlers do."""
+    context = FakeContext()
+    update = FakeUpdate(chat_id, user_id)
+    return tg_routines._create_scheduled_instance(
+        context,
+        update.effective_chat.id,
+        "probe",
+        {"pair": "SOL-USDC"},
+        {"type": "interval", "interval_sec": 60},
+        user_id=tg_routines._starter_id(update),
+        **kwargs,
+    )
+
+
+# ── Ownership is stamped at creation ──
+
+
+def test_scheduled_instance_records_the_starting_user(store):
+    instance_id = start_from_telegram(store)
+    assert store.get_instance(instance_id)["user_id"] == STARTER.id
+
+
+def test_group_run_attributes_to_the_member_not_the_group(store):
+    instance_id = start_from_telegram(store, chat_id=GROUP_CHAT, user_id=STARTER.id)
+    meta = store.get_instance(instance_id)
+    assert meta["user_id"] == STARTER.id
+    assert meta["user_id"] != GROUP_CHAT
+
+
+def test_continuous_instance_records_the_starting_user(store, monkeypatch):
+    async def fake_runner(*args, **kwargs):
+        return None
+
+    monkeypatch.setattr(tg_routines, "_run_continuous_routine", fake_runner)
+
+    async def scenario():
+        context = FakeContext()
+        update = FakeUpdate(GROUP_CHAT, STARTER.id)
+        instance_id = tg_routines._create_continuous_instance(
+            context,
+            update.effective_chat.id,
+            "watcher",
+            {},
+            user_id=tg_routines._starter_id(update),
+        )
+        await asyncio.gather(*tg_routines._continuous_tasks.values())
+        tg_routines._continuous_tasks.clear()
+        return instance_id
+
+    instance_id = asyncio.run(scenario())
+    assert store.get_instance(instance_id)["user_id"] == STARTER.id
+
+
+def test_starter_id_survives_an_update_with_no_user():
+    update = FakeUpdate(GROUP_CHAT, STARTER.id)
+    update.effective_user = None
+    assert tg_routines._starter_id(update) is None
+
+
+# ── The dashboard now shows it to its starter, and to nobody else ──
+
+
+def test_telegram_run_is_visible_and_stoppable_by_its_starter(store, make_client):
+    instance_id = start_from_telegram(store)
+    client = make_client(STARTER)
+
+    listed = client.get("/routines/instances")
+    assert [i["instance_id"] for i in listed.json()] == [instance_id]
+
+    detail = client.get(f"/routines/instances/{instance_id}")
+    assert detail.status_code == 200
+    assert detail.json()["routine_name"] == "probe"
+
+    assert client.post(f"/routines/instances/{instance_id}/stop").status_code == 200
+    assert store.get_instance(instance_id) is None
+
+
+def test_telegram_run_stays_hidden_from_an_unrelated_user(store, make_client):
+    instance_id = start_from_telegram(store)
+    client = make_client(STRANGER)
+
+    assert client.get("/routines/instances").json() == []
+    assert client.get(f"/routines/instances/{instance_id}").status_code == 403
+    assert client.post(f"/routines/instances/{instance_id}/stop").status_code == 403
+    assert store.get_instance(instance_id) is not None
+
+
+def test_admin_still_sees_every_telegram_run(store, make_client):
+    instance_id = start_from_telegram(store)
+    assert (
+        make_client(ADMIN).get(f"/routines/instances/{instance_id}").status_code == 200
+    )
+
+
+# ── The owner is never downgraded by a later sync ──
+
+
+def test_sync_keeps_the_owner_when_the_tick_meta_lost_it(store):
+    instance_id = start_from_telegram(store)
+    tg_routines._sync_instance_to_store(
+        instance_id, {"run_count": 3, "last_result": "ok"}
+    )
+    meta = store.get_instance(instance_id)
+    assert meta["user_id"] == STARTER.id
+    assert meta["run_count"] == 3
+
+
+def test_sync_can_still_adopt_an_instance_that_had_no_owner(store):
+    store.add_instance("legacy", {"routine_name": "probe", "status": "running"})
+    tg_routines._sync_instance_to_store("legacy", {"user_id": STARTER.id})
+    assert store.get_instance("legacy")["user_id"] == STARTER.id
+
+
+# ── Instances persisted before the fix ──
+
+
+class FakeApplication:
+    def __init__(self, user_data):
+        self.user_data = user_data
+        self.job_queue = FakeJobQueue()
+
+
+def test_restore_adopts_ownerless_instances_from_their_user_data_bucket(
+    store, monkeypatch
+):
+    """PTB keys ``user_data`` by user id, so the bucket names the real starter."""
+    monkeypatch.setattr(tg_routines, "get_routine", lambda name: object())
+    legacy = {
+        "routine_name": "probe",
+        "config": {},
+        "schedule": {"type": "interval", "interval_sec": 60},
+        "status": "running",
+        "source": "telegram",
+    }
+    app = FakeApplication({STARTER.id: {"routine_instances": {"legacy": legacy}}})
+
+    assert asyncio.run(tg_routines.restore_scheduled_jobs(app)) == 1
+
+    assert legacy["user_id"] == STARTER.id
+    assert store.get_instance("legacy")["user_id"] == STARTER.id
+
+
+def test_an_instance_with_no_owner_at_all_stays_admin_only(store, make_client):
+    """Anything still ownerless (MCP runs, older meta) keeps failing closed."""
+    store.add_instance("orphan", {"routine_name": "probe", "status": "running"})
+    assert make_client(STARTER).get("/routines/instances/orphan").status_code == 403
+    assert make_client(STARTER).get("/routines/instances").json() == []
+    assert make_client(ADMIN).get("/routines/instances/orphan").status_code == 200

From e4c42dd90cac2d8e67b2bcdd723b247e27a53b72 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Fri, 14 Aug 2026 17:57:05 +0300
Subject: [PATCH 088/116] (refactor) ARCH-162: one shared tracker for
 fire-and-forget tasks
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CORR-107 gave ws_manager a strong-ref set plus a done-callback that
discards the task and logs whatever it raised; CORR-141 hit the same
hazard in ServerDataService and mirrored the idiom by hand. Two private
copies of the same six lines, and nothing to import for the third caller
— who is the one who would get it subtly wrong.

condor/asyncutil.TaskSet is now the single implementation, next to
fsutil as a low-level shared module of the package. It holds the strong
reference (the event loop only keeps a weak one, so an unreferenced task
can be collected mid-await), drops it on completion, retrieves the
exception so a crash is not deferred to asyncio's "Task exception was
never retrieved" at GC time, and treats cancellation as a non-failure.

The two sites did differ in what they say and where they say it, so both
are parameterised rather than flattened: the logger is the caller's, not
this module's, and the message template plus the label are passed in.
ws_manager keeps "One-shot task %s failed" labelled by task name; SDS
keeps "SDS callback error for %s" labelled by the guilty subscriber_id,
which is not derivable from the task at all. cancel_all() folds both
shutdown loops, which were identical down to the snapshot taken because
cancel() re-enters the done-callback that mutates the set.

Tests pin the two invisible properties directly on the helper: a task
whose only referent is the TaskSet survives a gc.collect() to
completion, and a task that raises has its exception retrieved and
logged on the caller's logger. The existing site tests keep their
coverage; only their `== set()` assertions become len() == 0, since the
attribute is now a TaskSet rather than a bare set.
---
 condor/asyncutil.py                    |  92 ++++++++++++++
 condor/server_data_service.py          |  35 +-----
 condor/web/ws_manager.py               |  38 ++----
 tests/test_asyncutil_taskset.py        | 163 +++++++++++++++++++++++++
 tests/test_sds_callback_tasks.py       |   6 +-
 tests/test_sds_listener_typed_keys.py  |   2 +-
 tests/test_ws_manager_oneshot_tasks.py |   4 +-
 7 files changed, 273 insertions(+), 67 deletions(-)
 create mode 100644 condor/asyncutil.py
 create mode 100644 tests/test_asyncutil_taskset.py

diff --git a/condor/asyncutil.py b/condor/asyncutil.py
new file mode 100644
index 00000000..481e7bed
--- /dev/null
+++ b/condor/asyncutil.py
@@ -0,0 +1,92 @@
+"""Shared asyncio helpers.
+
+``TaskSet`` is the one implementation of the fire-and-forget task tracker that
+``condor`` had hand-rolled twice: once in ``condor/web/ws_manager.py``
+(CORR-107, one-shot broadcasts and backfills) and once in
+``condor/server_data_service.py`` (CORR-141, subscriber callbacks). Both copies
+existed because ``asyncio.create_task`` / ``ensure_future`` alone is unsafe for
+work nobody awaits:
+
+* **The event loop only holds a weak reference**, so a task with no other
+  referent can be garbage-collected mid-await and silently disappear.
+* **The exception is never retrieved**, so a crash surfaces only as asyncio's
+  "Task exception was never retrieved" at GC time — on no module's logger, with
+  nothing naming what stalled.
+
+``TaskSet`` holds the strong reference until the task completes, drops it
+automatically, and reports failures on the *caller's* logger. Both call sites
+word their error differently and identify the guilty task differently — the
+ws manager by task name, SDS by ``subscriber_id`` — so the message template and
+the label are the two things this helper parameterises rather than flattens.
+Everything else (discard-then-check, cancellation is not a failure, snapshot
+before cancelling because ``cancel()`` re-enters the done-callback) was
+identical in both copies and is fixed here.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Iterator
+
+
+class TaskSet:
+    """Strong references to fire-and-forget tasks, with their failures logged.
+
+    ``error_message`` is a printf-style template taking exactly two ``%s``: the
+    label of the task and the exception. It is logged on ``logger``, so failures
+    land on the calling module's logger and not on this one.
+    """
+
+    def __init__(self, logger: logging.Logger, error_message: str) -> None:
+        self._logger = logger
+        self._error_message = error_message
+        self._tasks: set[asyncio.Task] = set()
+
+    def track(self, task: asyncio.Task, label: str | None = None) -> asyncio.Task:
+        """Keep a strong reference to ``task`` until it finishes.
+
+        ``label`` names the task in the failure log; it defaults to the task's
+        own name, which is what a caller that names its tasks wants. The
+        reference is dropped automatically on completion. Returns the task so a
+        caller can keep dispatching in one expression.
+        """
+        self._tasks.add(task)
+        task.add_done_callback(lambda t, lbl=label: self._on_done(t, lbl))
+        return task
+
+    def cancel_all(self) -> None:
+        """Cancel every still-pending task and forget all of them.
+
+        Iterates a snapshot: ``cancel()`` fires the done-callback, which mutates
+        the underlying set.
+        """
+        for task in list(self._tasks):
+            if not task.done():
+                task.cancel()
+        self._tasks.clear()
+
+    def _on_done(self, task: asyncio.Task, label: str | None) -> None:
+        """Release the strong reference and surface the failure, if any."""
+        self._tasks.discard(task)
+        if task.cancelled():
+            return
+        exc = task.exception()
+        if exc is not None:
+            self._logger.error(
+                self._error_message, label or task.get_name(), exc, exc_info=exc
+            )
+
+    # -- Introspection (tests and log lines; not part of the hot path) --
+
+    def __len__(self) -> int:
+        return len(self._tasks)
+
+    def __iter__(self) -> Iterator[asyncio.Task]:
+        return iter(self._tasks)
+
+    def __contains__(self, task: object) -> bool:
+        return task in self._tasks
+
+    def __bool__(self) -> bool:
+        return bool(self._tasks)
diff --git a/condor/server_data_service.py b/condor/server_data_service.py
index 96a02b8f..33af529f 100644
--- a/condor/server_data_service.py
+++ b/condor/server_data_service.py
@@ -22,6 +22,8 @@
 from functools import partial
 from typing import Any, Callable, Dict, FrozenSet, List, Optional, Tuple
 
+from condor.asyncutil import TaskSet
+
 logger = logging.getLogger(__name__)
 
 
@@ -282,7 +284,7 @@ def __init__(self):
         # Strong refs to fire-and-forget subscriber-callback tasks so the GC
         # can't cancel them mid-flight (the event loop only keeps a weak
         # reference). Entries auto-remove on completion.
-        self._callback_tasks: set[asyncio.Task] = set()
+        self._callback_tasks = TaskSet(logger, "SDS callback error for %s: %s")
 
     # ------ Fetch registry ------
 
@@ -636,10 +638,7 @@ def stop(self) -> None:
         if self._poll_task and not self._poll_task.done():
             self._poll_task.cancel()
             logger.info("ServerDataService stopped")
-        for task in list(self._callback_tasks):
-            if not task.done():
-                task.cancel()
-        self._callback_tasks.clear()
+        self._callback_tasks.cancel_all()
 
     # ------ Poll loop ------
 
@@ -774,30 +773,6 @@ async def _do_fetch_and_cache(self, key: CacheKey) -> Optional[Any]:
 
         return result
 
-    def _track_callback_task(self, task: asyncio.Task, subscriber_id: str) -> None:
-        """Keep a strong reference to a fire-and-forget subscriber callback
-        until it finishes, so the GC can't silently cancel it mid-await (the
-        event loop only holds a weak reference). The reference is dropped
-        automatically on completion."""
-        self._callback_tasks.add(task)
-        task.add_done_callback(
-            lambda t, sid=subscriber_id: self._on_callback_done(t, sid)
-        )
-
-    def _on_callback_done(self, task: asyncio.Task, subscriber_id: str) -> None:
-        """Release the strong reference and surface failures on this module's
-        logger. Nobody awaits a subscriber callback, so without this a crash
-        would only show up as asyncio's "Task exception was never retrieved"
-        at GC time, leaving the subscriber silently broken."""
-        self._callback_tasks.discard(task)
-        if task.cancelled():
-            return
-        exc = task.exception()
-        if exc is not None:
-            logger.error(
-                "SDS callback error for %s: %s", subscriber_id, exc, exc_info=exc
-            )
-
     def _fire_callbacks(self, key: CacheKey, old_value: Any, new_value: Any) -> None:
         """Fire subscriber callbacks asynchronously.
 
@@ -816,7 +791,7 @@ def _fire_callbacks(self, key: CacheKey, old_value: Any, new_value: Any) -> None
                 except Exception as e:
                     logger.debug("SDS callback error for %s: %s", sub.subscriber_id, e)
                 else:
-                    self._track_callback_task(task, sub.subscriber_id)
+                    self._callback_tasks.track(task, sub.subscriber_id)
 
     def _cleanup_stale(self) -> None:
         """Remove cache entries with no subscribers and expired TTL."""
diff --git a/condor/web/ws_manager.py b/condor/web/ws_manager.py
index 00558020..456a2fe0 100644
--- a/condor/web/ws_manager.py
+++ b/condor/web/ws_manager.py
@@ -10,6 +10,7 @@
 from fastapi import WebSocket
 
 from condor import dex_candles
+from condor.asyncutil import TaskSet
 from condor.fetchers.market_data import fetch_historical_candles, normalize_candle
 from condor.web.auth import decode_jwt
 
@@ -248,33 +249,12 @@ def __init__(self):
         # Strong refs to fire-and-forget one-shot tasks (backfill, warm cache)
         # so the GC can't cancel them mid-flight (the event loop only keeps a
         # weak reference). Entries auto-remove on completion.
-        self._oneshot_tasks: set[asyncio.Task] = set()
+        self._oneshot_tasks = TaskSet(logger, "One-shot task %s failed: %s")
         # Lazily-built registry of per-type stream lifecycles (see _stream_registry)
         self._stream_registry_cache: dict | None = None
 
     # -- Helpers --
 
-    def _track_oneshot(self, task: asyncio.Task) -> None:
-        """Keep a strong reference to a fire-and-forget task until it finishes,
-        so the GC can't silently cancel it (the event loop only holds a weak
-        reference). The reference is dropped automatically on completion."""
-        self._oneshot_tasks.add(task)
-        task.add_done_callback(self._on_oneshot_done)
-
-    def _on_oneshot_done(self, task: asyncio.Task) -> None:
-        """Release the strong reference and surface failures on this module's
-        logger. Nobody awaits a one-shot task, so without this a crash would
-        only show up as asyncio's "Task exception was never retrieved" at GC
-        time, leaving a channel silently stalled."""
-        self._oneshot_tasks.discard(task)
-        if task.cancelled():
-            return
-        exc = task.exception()
-        if exc is not None:
-            logger.error(
-                "One-shot task %s failed: %s", task.get_name(), exc, exc_info=exc
-            )
-
     @staticmethod
     def _server_from_channel(channel: str) -> str | None:
         """Server name encoded as the second segment of a channel
@@ -331,12 +311,8 @@ def stop(self) -> None:
         self._last_candle_ws_update.clear()
         self._candle_first_msg_logged.clear()
 
-        # Cancel any still-pending one-shot tasks (snapshot: cancel() fires the
-        # done-callback that mutates the set).
-        for task in list(self._oneshot_tasks):
-            if not task.done():
-                task.cancel()
-        self._oneshot_tasks.clear()
+        # Cancel any still-pending one-shot tasks.
+        self._oneshot_tasks.cancel_all()
 
         if self._cleanup_task and not self._cleanup_task.done():
             self._cleanup_task.cancel()
@@ -500,7 +476,7 @@ async def _handle_candle_subscribe(
                 old_max = buf.max_size
                 buf.set_duration(dur)
                 if buf.max_size > old_max and buf.needs_backfill:
-                    self._track_oneshot(
+                    self._oneshot_tasks.track(
                         asyncio.create_task(
                             self._backfill_candles(channel),
                             name=f"backfill:{channel}",
@@ -650,7 +626,7 @@ async def _subscribe_sds(self, channel: str) -> None:
             # Portfolio history rides on the portfolio subscription: one SDS
             # key per range, primed now and polled until the last client leaves.
             if prefix == "portfolio":
-                self._track_oneshot(
+                self._oneshot_tasks.track(
                     asyncio.create_task(
                         self._subscribe_portfolio_history(channel, server_name),
                         name=f"portfolio_history:{server_name}",
@@ -788,7 +764,7 @@ def _on_data_update(self, key: CacheKey, value: Any) -> None:
                 logger.debug("Failed to transform bots data for WS: %s", e)
                 return
 
-        self._track_oneshot(
+        self._oneshot_tasks.track(
             asyncio.create_task(
                 self._broadcast_update(channel, value),
                 name=f"broadcast:{channel}",
diff --git a/tests/test_asyncutil_taskset.py b/tests/test_asyncutil_taskset.py
new file mode 100644
index 00000000..516ad2b2
--- /dev/null
+++ b/tests/test_asyncutil_taskset.py
@@ -0,0 +1,163 @@
+"""`TaskSet` is the one tracker behind ws_manager's one-shots and SDS's
+subscriber callbacks (ARCH-162). Both hazards it exists for are invisible in
+normal operation, so they are pinned here: the strong reference that keeps a
+fire-and-forget task alive when nothing else refers to it, and the exception
+retrieval that turns a silent "Task exception was never retrieved" at GC time
+into an ERROR on the *caller's* logger.
+"""
+
+import asyncio
+import gc
+import logging
+
+import pytest
+
+from condor.asyncutil import TaskSet
+
+LOGGER_NAME = "tests.asyncutil_taskset"
+logger = logging.getLogger(LOGGER_NAME)
+
+
+def _tracker(message: str = "Tracked task %s failed: %s") -> TaskSet:
+    return TaskSet(logger, message)
+
+
+def test_strong_reference_keeps_the_task_alive_to_completion():
+    """Nothing but the TaskSet refers to the task: the event loop holds only a
+    weak reference, so without tracking a GC pass mid-await can drop it."""
+    tracker = _tracker()
+    finished = []
+
+    async def work():
+        await asyncio.sleep(0)
+        finished.append("done")
+
+    async def scenario():
+        tracker.track(asyncio.create_task(work(), name="worker"))
+        # Drop every local handle and force a collection while it is suspended.
+        gc.collect()
+        assert len(tracker) == 1, "the task was not held"
+        await asyncio.gather(*list(tracker), return_exceptions=True)
+        await asyncio.sleep(0)
+
+    asyncio.run(scenario())
+
+    assert finished == ["done"], "the tracked task did not run to completion"
+    assert len(tracker) == 0, "the strong reference was not released"
+
+
+def test_failure_is_retrieved_and_logged_on_the_callers_logger(caplog):
+    """A crash must leave a traceback on the logger the site passed in, and the
+    exception must be consumed so asyncio never warns about it."""
+    tracker = _tracker()
+
+    async def boom():
+        raise RuntimeError("downstream exploded")
+
+    async def scenario():
+        task = tracker.track(asyncio.create_task(boom(), name="worker"))
+        await asyncio.gather(task, return_exceptions=True)
+        await asyncio.sleep(0)
+        return task
+
+    with caplog.at_level(logging.ERROR, logger=LOGGER_NAME):
+        task = asyncio.run(scenario())
+
+    records = [r for r in caplog.records if r.name == LOGGER_NAME]
+    assert records, "the failure produced no ERROR on the caller's logger"
+    assert "worker" in records[0].getMessage()
+    assert "downstream exploded" in records[0].getMessage()
+    assert records[0].exc_info is not None, "traceback was not attached"
+    # This is the property that matters: the exception was already retrieved,
+    # so the task is not left holding an unretrieved one at GC time.
+    assert isinstance(task.exception(), RuntimeError)
+    assert len(tracker) == 0
+
+
+def test_explicit_label_names_the_task_instead_of_its_name(caplog):
+    """SDS identifies the guilty callback by subscriber_id, which is not
+    derivable from the task; ws_manager falls back to the task name."""
+    tracker = _tracker("SDS callback error for %s: %s")
+
+    async def boom():
+        raise ValueError("subscriber blew up")
+
+    async def scenario():
+        task = tracker.track(
+            asyncio.create_task(boom(), name="unhelpful"), "ws_manager"
+        )
+        await asyncio.gather(task, return_exceptions=True)
+        await asyncio.sleep(0)
+
+    with caplog.at_level(logging.ERROR, logger=LOGGER_NAME):
+        asyncio.run(scenario())
+
+    message = caplog.records[0].getMessage()
+    assert message == "SDS callback error for ws_manager: subscriber blew up"
+    assert "unhelpful" not in message
+
+
+def test_cancellation_is_not_a_failure(caplog):
+    """Shutdown cancels whatever is pending; that must not log an error."""
+    tracker = _tracker()
+
+    async def scenario():
+        task = tracker.track(asyncio.create_task(asyncio.Event().wait()))
+        await asyncio.sleep(0)
+        task.cancel()
+        await asyncio.gather(task, return_exceptions=True)
+        await asyncio.sleep(0)
+
+    with caplog.at_level(logging.ERROR, logger=LOGGER_NAME):
+        asyncio.run(scenario())
+
+    assert [r for r in caplog.records if r.name == LOGGER_NAME] == []
+    assert len(tracker) == 0
+
+
+def test_cancel_all_drains_pending_tasks_without_mutating_mid_iteration():
+    """`cancel()` re-enters the done-callback that discards from the set, so
+    cancel_all must iterate a snapshot."""
+    tracker = _tracker()
+
+    async def scenario():
+        for i in range(5):
+            tracker.track(asyncio.create_task(asyncio.Event().wait(), name=f"t{i}"))
+        await asyncio.sleep(0)
+        tasks = list(tracker)
+        tracker.cancel_all()
+        await asyncio.gather(*tasks, return_exceptions=True)
+        return tasks
+
+    tasks = asyncio.run(scenario())
+
+    assert all(t.cancelled() for t in tasks), "cancel_all left a task running"
+    assert len(tracker) == 0
+    assert not tracker
+
+
+@pytest.mark.parametrize(
+    "module, attr, message",
+    [
+        ("condor.web.ws_manager", "_oneshot_tasks", "One-shot task %s failed: %s"),
+        (
+            "condor.server_data_service",
+            "_callback_tasks",
+            "SDS callback error for %s: %s",
+        ),
+    ],
+)
+def test_both_call_sites_share_the_helper_and_keep_their_own_wording(
+    module, attr, message
+):
+    """The point of ARCH-162: one implementation, but each site still logs its
+    own sentence on its own logger."""
+    import importlib
+    import inspect
+
+    mod = importlib.import_module(module)
+    source = inspect.getsource(mod)
+    assert "TaskSet" in source, f"{module} does not use the shared tracker"
+    assert f"self.{attr} = TaskSet(" in source, f"{module} does not hold one"
+    assert message in source, f"{module} lost its own error wording"
+    assert "def _track_" not in source, f"{module} still hand-rolls a tracker"
diff --git a/tests/test_sds_callback_tasks.py b/tests/test_sds_callback_tasks.py
index 1c45205b..eaa2618b 100644
--- a/tests/test_sds_callback_tasks.py
+++ b/tests/test_sds_callback_tasks.py
@@ -57,7 +57,7 @@ async def _drive():
     sds = asyncio.run(_drive())
 
     assert ran["done"] is True, "callback was lost mid-flight"
-    assert sds._callback_tasks == set(), "done-callback must discard the task"
+    assert len(sds._callback_tasks) == 0, "done-callback must discard the task"
 
 
 def test_callback_exception_is_logged_and_isolated(caplog):
@@ -95,7 +95,7 @@ async def _drive():
     ), f"callback failure was not logged: {messages}"
 
     assert good_ran["count"] == 1, "a failing subscriber must not block the others"
-    assert sds._callback_tasks == set(), "failed task must still be discarded"
+    assert len(sds._callback_tasks) == 0, "failed task must still be discarded"
 
 
 def test_publisher_survives_failing_callback():
@@ -149,4 +149,4 @@ async def _drive():
 
     assert pending[0].cancelled(), "pending callback task must be cancelled by stop()"
     assert finished["done"] is False
-    assert sds._callback_tasks == set()
+    assert len(sds._callback_tasks) == 0
diff --git a/tests/test_sds_listener_typed_keys.py b/tests/test_sds_listener_typed_keys.py
index 5e4f6f71..de299fcc 100644
--- a/tests/test_sds_listener_typed_keys.py
+++ b/tests/test_sds_listener_typed_keys.py
@@ -114,7 +114,7 @@ async def scenario():
     asyncio.run(scenario())
 
     assert ws.sent == [], "portfolio history leaked onto the portfolio channel"
-    assert manager._oneshot_tasks == set()
+    assert len(manager._oneshot_tasks) == 0
 
 
 def test_account_scoped_portfolio_is_not_broadcast_to_the_server_channel():
diff --git a/tests/test_ws_manager_oneshot_tasks.py b/tests/test_ws_manager_oneshot_tasks.py
index e27e527f..82096c15 100644
--- a/tests/test_ws_manager_oneshot_tasks.py
+++ b/tests/test_ws_manager_oneshot_tasks.py
@@ -74,7 +74,7 @@ async def scenario():
 
     asyncio.run(scenario())
 
-    assert manager._oneshot_tasks == set()
+    assert len(manager._oneshot_tasks) == 0
 
 
 def test_failing_broadcast_is_logged_on_this_modules_logger(caplog):
@@ -125,7 +125,7 @@ async def scenario():
         asyncio.run(scenario())
 
     assert [r for r in caplog.records if r.name == WS_LOGGER] == []
-    assert manager._oneshot_tasks == set()
+    assert len(manager._oneshot_tasks) == 0
 
 
 def test_no_untracked_fire_and_forget_dispatch_remains():

From cb33ff79a94f558af209ed3e98dc2397ae5bdb77 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Fri, 14 Aug 2026 18:01:59 +0300
Subject: [PATCH 089/116] (perf) PERF-174: poll each portfolio-history range at
 its own TTL
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

ARCH-145 moved the history poll into ServerDataService and preserved the
old dashboard cadence exactly: all four ranges every 120s, because the
hand-rolled loop re-fetched them together on one timer. But the per-range
TTLs it also carried across are 1D=120s, 1W=600s, 1M=3600s, 3M=7200s — so
the 3M window was refetched ~60 times per TTL, and 1M ~30 times, for data
that had not moved.

The cadence is now derived from the TTL that already exists rather than
declared a second time: DataTypeDefaults.interval_for(params) scales the
declared interval by ttl_for(params)/ttl, so a variant that stays valid
60x longer is polled 60x less often. PORTFOLIO_HISTORY declares
interval == ttl == 120, so each range polls exactly at its own TTL: 1D
unchanged at 120s, 3M at 7200s. Data types with no ttl_by_param are
untouched — interval_for returns the flat interval.

subscribe() builds the CacheKey before resolving the interval so it can
consult the key's own params; ws_manager stops passing an explicit
interval and PORTFOLIO_HISTORY_INTERVAL is gone, since a second table of
cadences is the same defect this item fixes.

Slowing the poll does not make the chart stale: the range switch goes
through the REST route's get_or_fetch, which refetches the moment the
entry is past its TTL instead of waiting for the next tick.
---
 condor/fetchers/portfolio.py        |  6 +-
 condor/server_data_service.py       | 29 +++++++--
 condor/web/ws_manager.py            |  6 +-
 tests/test_portfolio_history_sds.py | 92 +++++++++++++++++++++++++----
 4 files changed, 109 insertions(+), 24 deletions(-)

diff --git a/condor/fetchers/portfolio.py b/condor/fetchers/portfolio.py
index e69c2a67..7e11ffba 100644
--- a/condor/fetchers/portfolio.py
+++ b/condor/fetchers/portfolio.py
@@ -19,8 +19,10 @@
     "3M": (7776000, "1d"),
 }
 
-# Poll cadence for a subscribed history range (seconds).
-PORTFOLIO_HISTORY_INTERVAL = 120
+# The poll cadence is not declared here: each range is polled at its own TTL,
+# which ``ServerDataType.PORTFOLIO_HISTORY``'s defaults already state (see
+# ``DataTypeDefaults.interval_for``). A second table here would only be one
+# more thing that has to agree with that one.
 
 
 async def fetch_portfolio(client, **_kw) -> Any:
diff --git a/condor/server_data_service.py b/condor/server_data_service.py
index 33af529f..318f50fa 100644
--- a/condor/server_data_service.py
+++ b/condor/server_data_service.py
@@ -72,12 +72,27 @@ def ttl_for(self, params: Dict[str, str]) -> float:
         param_name, table = self.ttl_by_param
         return table.get(params.get(param_name, ""), self.ttl)
 
+    def interval_for(self, params: Dict[str, str]) -> float:
+        """Default poll cadence for a specific cache key's params.
+
+        Derived from that key's own TTL rather than a second per-param table:
+        polling a variant far more often than its data goes stale is pure
+        waste, and two tables that must agree eventually stop agreeing. The
+        declared ``interval:ttl`` ratio is what carries over, so a variant that
+        stays valid 60x longer is polled 60x less often.
+        """
+        if not self.ttl_by_param or not self.ttl:
+            return self.interval
+        return self.interval * (self.ttl_for(params) / self.ttl)
+
 
 _DEFAULTS: Dict[ServerDataType, DataTypeDefaults] = {
     ServerDataType.PORTFOLIO: DataTypeDefaults(interval=10, ttl=60),
-    # History is polled at one cadence for every range (what the dashboard's
-    # hand-rolled refresh loop did), but each range stays valid for as long as
-    # its own resolution warrants once nobody is subscribed.
+    # One entry per range window, each with its own freshness horizon: a 1D
+    # window at 5m candles is stale within minutes, a 3M window at 1d candles
+    # holds for hours. ``interval == ttl`` here, so ``interval_for`` polls each
+    # range exactly at its own TTL instead of refetching the 3M series 60x per
+    # window like the dashboard's old shared 120s loop did.
     ServerDataType.PORTFOLIO_HISTORY: DataTypeDefaults(
         interval=120,
         ttl=120,
@@ -326,13 +341,15 @@ async def subscribe(
     ) -> CacheKey:
         """Subscribe to data updates. Returns the CacheKey.
 
-        If interval is 0 or not provided, the default for the data type is used.
+        If interval is 0 or not provided, the data type's default cadence is
+        used — derived per key from its own TTL, so a long-lived variant is
+        polled as rarely as its freshness contract allows.
         Callback signature: async callback(key: CacheKey, old_value, new_value)
         """
+        key = CacheKey.make(server, data_type, **params)
         if interval <= 0:
-            interval = _DEFAULTS[data_type].interval
+            interval = _DEFAULTS[data_type].interval_for(key.params_dict)
 
-        key = CacheKey.make(server, data_type, **params)
         sub = Subscription(
             subscriber_id=subscriber_id,
             key=key,
diff --git a/condor/web/ws_manager.py b/condor/web/ws_manager.py
index 456a2fe0..6122c5f3 100644
--- a/condor/web/ws_manager.py
+++ b/condor/web/ws_manager.py
@@ -647,10 +647,7 @@ async def _subscribe_portfolio_history(
         while the priming is in flight, unsubscribe again — otherwise the poll
         would outlive its last subscriber.
         """
-        from condor.fetchers.portfolio import (
-            PORTFOLIO_HISTORY_INTERVAL,
-            PORTFOLIO_HISTORY_RANGES,
-        )
+        from condor.fetchers.portfolio import PORTFOLIO_HISTORY_RANGES
         from condor.server_data_service import ServerDataType, get_server_data_service
 
         sds = get_server_data_service()
@@ -661,7 +658,6 @@ async def _sub(range_key: str) -> None:
                     server=server_name,
                     data_type=ServerDataType.PORTFOLIO_HISTORY,
                     subscriber_id="ws_manager",
-                    interval=PORTFOLIO_HISTORY_INTERVAL,
                     range_key=range_key,
                 )
             except Exception as e:
diff --git a/tests/test_portfolio_history_sds.py b/tests/test_portfolio_history_sds.py
index 8b2685ee..5e5dd312 100644
--- a/tests/test_portfolio_history_sds.py
+++ b/tests/test_portfolio_history_sds.py
@@ -18,11 +18,7 @@
 
 import pytest
 
-from condor.fetchers.portfolio import (
-    PORTFOLIO_HISTORY_INTERVAL,
-    PORTFOLIO_HISTORY_RANGES,
-    fetch_portfolio_history,
-)
+from condor.fetchers.portfolio import PORTFOLIO_HISTORY_RANGES, fetch_portfolio_history
 from condor.server_data_service import (
     _DEFAULTS,
     CacheKey,
@@ -211,7 +207,6 @@ def test_per_range_ttls_survived_the_move():
     """The old _RANGE_TTLS table now lives on the data type's defaults."""
     defaults = _DEFAULTS[ServerDataType.PORTFOLIO_HISTORY]
 
-    assert defaults.interval == PORTFOLIO_HISTORY_INTERVAL
     assert {
         rk: defaults.ttl_for({"range_key": rk}) for rk in PORTFOLIO_HISTORY_RANGES
     } == {"1D": 120, "1W": 600, "1M": 3600, "3M": 7200}
@@ -239,6 +234,12 @@ def _expire(sds: ServerDataService) -> None:
         entry.fetched_at = 0.0
 
 
+def _age(sds: ServerDataService, seconds: float) -> None:
+    """Backdate every cache entry by ``seconds`` (per-range cadences differ)."""
+    for entry in sds._cache.values():
+        entry.fetched_at -= seconds
+
+
 def test_poll_starts_with_the_portfolio_subscriber_and_stops_with_it(env):
     """A silently-never-started poll is a dead chart no shape test would catch:
     drive real poll ticks before and after the subscriber leaves."""
@@ -279,24 +280,93 @@ async def _drive():
     assert not any(k in sds._subscriptions for k in _history_keys("srv"))
 
 
-def test_history_subscriptions_use_the_previous_refresh_cadence(env):
-    """The loop re-warmed every range every 120s; the subscriptions must too."""
+def test_history_subscriptions_poll_each_range_at_its_own_ttl(env):
+    """PERF-174: one shared 120s cadence refetched the 3M window ~60x per TTL.
+
+    The cadence must come from the range's own TTL — the table that already
+    exists — not from a second table of intervals that has to agree with it.
+    """
     sds, _client = env()
+    defaults = _DEFAULTS[ServerDataType.PORTFOLIO_HISTORY]
 
     async def _drive():
         manager = WebSocketManager()
         await manager._subscribe_sds("portfolio:srv")
         await _drain(manager)
         return {
-            key: [s.interval for s in subs.values()]
+            key.params_dict["range_key"]: [s.interval for s in subs.values()]
             for key, subs in sds._subscriptions.items()
             if key.data_type is ServerDataType.PORTFOLIO_HISTORY
         }
 
     intervals = asyncio.run(_drive())
 
-    assert len(intervals) == len(PORTFOLIO_HISTORY_RANGES)
-    assert all(iv == [PORTFOLIO_HISTORY_INTERVAL] for iv in intervals.values())
+    assert intervals == {
+        rk: [defaults.ttl_for({"range_key": rk})] for rk in PORTFOLIO_HISTORY_RANGES
+    }
+    # And that is the concrete cadence: 1D unchanged, the rest much rarer.
+    assert {rk: iv[0] for rk, iv in intervals.items()} == {
+        "1D": 120,
+        "1W": 600,
+        "1M": 3600,
+        "3M": 7200,
+    }
+
+
+def _ranges_fetched(client: FakeClient, since: int) -> set[str]:
+    """Which range windows the client was asked for after call ``since``."""
+    by_candle = {candle: rk for rk, (_, candle) in PORTFOLIO_HISTORY_RANGES.items()}
+    return {by_candle[c["interval"]] for c in client.history_calls[since:]}
+
+
+def test_a_slow_range_is_not_refetched_on_the_fast_range_cadence(env):
+    """The saving itself: 120s of subscription must cost one fetch, not four."""
+    sds, client = env()
+
+    async def _drive():
+        manager = WebSocketManager()
+        await manager._subscribe_sds("portfolio:srv")
+        await _drain(manager)
+        primed = len(client.history_calls)
+
+        # 121s later: only the 1D window has outlived its TTL.
+        _age(sds, 121)
+        await sds._poll_tick()
+        after_2min = _ranges_fetched(client, primed)
+
+        # 2h later: every window is due.
+        mark = len(client.history_calls)
+        _age(sds, 7201)
+        await sds._poll_tick()
+        return after_2min, _ranges_fetched(client, mark)
+
+    after_2min, after_2h = asyncio.run(_drive())
+
+    assert after_2min == {"1D"}, "only the 1D window is stale after two minutes"
+    assert after_2h == set(PORTFOLIO_HISTORY_RANGES), "every window is due after 2h"
+
+
+def test_expired_slow_range_refreshes_on_an_explicit_request(env):
+    """Switching to 3M must not serve a two-hour-old chart while waiting for
+    the next (now much rarer) poll: the request itself refetches."""
+    sds, client = env()
+
+    async def _drive():
+        manager = WebSocketManager()
+        await manager._subscribe_sds("portfolio:srv")
+        await _drain(manager)
+        primed = len(client.history_calls)
+
+        # Past the 3M TTL, but with no poll tick in between.
+        _age(sds, 7201)
+        resp = await get_portfolio_history(name="srv", range="3M", user=_USER)
+        return primed, _ranges_fetched(client, primed), resp
+
+    primed, fetched, resp = asyncio.run(_drive())
+
+    assert primed == len(PORTFOLIO_HISTORY_RANGES)
+    assert fetched == {"3M"}, "the explicit read refetches its own range on the spot"
+    assert [p.total_usd for p in resp.points] == [150.0, 160.0]
 
 
 def test_second_subscriber_does_not_spawn_a_duplicate_poll(env):

From d1e8c664fd2f1f4434d9fd835190e60c0af89588 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Fri, 14 Aug 2026 18:09:47 +0300
Subject: [PATCH 090/116] (perf) PERF-170: bound transcript.jsonl and archive
 the overflow
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The conversation transcript was append-only with no sweep. PERF-138 fixed the
read half — replay_context and a bounded read_transcript walk the file
backwards and stop at the budget — but the file itself grew for the life of
the conversation, and read_transcript(limit=0) stayed O(file).

transcript.jsonl is now capped at CONDOR_TRANSCRIPT_MAX_BYTES (2 MiB). Past
it, the oldest turns are *moved* — never deleted — to transcript_archive.jsonl
beside it, leaving the newest CONDOR_TRANSCRIPT_KEEP_BYTES (1 MiB) plus one
marker turn naming the sidecar and the running count, so the file never claims
to be a complete record when it is not. Same bargain PERF-136 struck for the
agent journal, and a stricter one here: this is the user's own chat history.

Bounded in bytes rather than turns because bytes are what grow — one turn runs
from ~100 B to ~3 KB of tool payload — and because it makes the trigger a
single stat() on the append path. MAX and KEEP are far apart on purpose: a
trim leaves the file at KEEP, so the rewrite amortizes to a constant per byte
appended.

The marker is a real system turn, not a bespoke line format, so every existing
reader already handles it: the dashboard renders it like any other system
note, read_transcript returns it, _render_turn would replay it. read_transcript
gains include_archive= for the genuinely full record, which drops the marker
because with both files in hand there is no boundary left to mark.

replay_context is unaffected by design, not by luck: it reads the live file
only, and _keep_bytes() floors the kept tail at 4x REPLAY_MAX_CHARS, so a trim
can only ever remove turns the backwards walk had already stopped short of.
The tests pin that as an equality against the same conversation with retention
off.

Crash-safe in every window. The archive append is fsync-ed before the live
file is republished, and the republish goes through condor.fsutil's atomic
writer: a crash before the archive write leaves the transcript untouched, one
between the two leaves the moved turns in both files, and one during the
rename leaves the whole old file and retries on the next append. There is no
ordering in which a turn is lost — and if the sidecar cannot be written at
all, nothing is dropped and the file simply stays over the bound.

No migration: an existing transcript has no marker and no sidecar, and gets
both the first time it crosses the bound.
---
 condor/runtime/conversations.py            | 254 ++++++++++++++--
 tests/runtime/test_transcript_retention.py | 333 +++++++++++++++++++++
 2 files changed, 565 insertions(+), 22 deletions(-)
 create mode 100644 tests/runtime/test_transcript_retention.py

diff --git a/condor/runtime/conversations.py b/condor/runtime/conversations.py
index 93d6a561..e59e2f83 100644
--- a/condor/runtime/conversations.py
+++ b/condor/runtime/conversations.py
@@ -8,8 +8,9 @@
 a subprocess is. The conversation is a directory:
 
     condor/.runtime/conversations/{user_id}/{conv_id}/
-        meta.json          # atomic merge, via registry_file.write_status()
-        transcript.jsonl   # append-only, one JSON object per line
+        meta.json                  # atomic merge, via registry_file.write_status()
+        transcript.jsonl           # append-only, bounded; one JSON object per line
+        transcript_archive.jsonl   # turns retired out of the file above
 
 Same idiom as the rest of the runtime's durable facts: ``registry_file`` for
 atomic status, ``journal.py`` for an append-only narrative. No database.
@@ -39,6 +40,7 @@
 
 from pydantic import BaseModel, ConfigDict, Field
 
+from condor.fsutil import atomic_write_bytes
 from condor.runtime.events import EventType
 from condor.runtime.registry_file import read_status, write_status
 
@@ -46,6 +48,7 @@
 
 META_FILENAME = "meta.json"
 TRANSCRIPT_FILENAME = "transcript.jsonl"
+TRANSCRIPT_ARCHIVE_FILENAME = "transcript_archive.jsonl"
 
 # conv_id and user_id both become directory names, so neither may escape one.
 # Same guard, same reason, as state.py's namespace check.
@@ -66,14 +69,62 @@
 # turn is bigger than this.
 _TAIL_BLOCK_BYTES = 64 * 1024
 
+# Retention for the live transcript. The file is append-only, so without a
+# sweep its footprint grows for the life of the conversation — PERF-138 made
+# *reading* it cheap, not writing it. Past ``MAX`` bytes the oldest turns are
+# **moved**, never deleted, to ``transcript_archive.jsonl`` beside it; the live
+# file keeps the newest ``KEEP`` bytes plus one marker turn naming the sidecar
+# and how many turns went into it. Same shape as PERF-136's journal archive and
+# for the same reason: this is the user's own chat history, so a retention
+# policy whose failure mode is "the chat is gone" is not one worth having.
+#
+# Bounded in bytes rather than in turns because bytes are what grow: one turn
+# runs from ~100 B to ~3 KB (a tool call keeps up to ``TOOL_INPUT_MAX_CHARS`` +
+# ``TOOL_OUTPUT_MAX_CHARS`` of payload), so a turn count would pin the
+# footprint only to within a factor of thirty. It also makes the trigger a
+# single ``stat()`` on the append path rather than a line count.
+#
+# MAX and KEEP are deliberately far apart: a trim leaves the file at KEEP, so
+# the next one is a whole MAX−KEEP of appends away and the rewrite amortizes to
+# a constant per byte appended. They are read from the environment here, beside
+# ``REPLAY_MAX_CHARS`` and for the same reason, rather than from
+# ``timeouts.py``, whose loader only understands deadlines in seconds.
+TRANSCRIPT_MAX_BYTES = int(
+    os.environ.get("CONDOR_TRANSCRIPT_MAX_BYTES", "2097152") or 2097152
+)
+TRANSCRIPT_KEEP_BYTES = int(
+    os.environ.get("CONDOR_TRANSCRIPT_KEEP_BYTES", "1048576") or 1048576
+)
+
+# The kept tail is never allowed below this multiple of the replay budget, and
+# that is the load-bearing half of the policy: ``replay_context`` reads the live
+# file only, so a trim must never be able to change what a resumed session is
+# handed. Holding the tail well above ``REPLAY_MAX_CHARS`` guarantees a trim
+# only ever removes turns that were already past the replay bound — the replay
+# is identical before and after. A rendered replay line is a strict subset of
+# the JSON line it came from, so bytes here dominate chars there; the multiple
+# is slack on top of that.
+_REPLAY_HEADROOM = 4
+
+# The turn left behind in place of the archived ones. A real ``system`` entry
+# rather than a bespoke line format, so every existing reader already handles
+# it: the dashboard renders it like any other system note, ``read_transcript``
+# returns it, and ``_render_turn`` would replay it as "(N older turns moved to
+# …)" if a replay window ever reached back that far. The count is folded
+# forward on each trim, so the file states the running total and never claims
+# to be a complete record when it is not.
+ARCHIVE_MARKER_KIND = "archived"
+_ARCHIVE_MARKER_RE = re.compile(r"^(\d+) older turns? moved to ")
+
 TITLE_MAX_CHARS = 80
 SNIPPET_MAX_CHARS = 160
 
 # Upper bounds on the tool IO kept per call, in characters. Load-bearing, not
 # defensive: a tool result is routinely a market-data dump, a whole portfolio
-# payload or a base64 image, and the transcript has no retention sweep — kept
-# verbatim, one turn could outweigh the entire conversation and slow every
-# read of the file. They live here, beside ``REPLAY_MAX_CHARS`` and for the
+# payload or a base64 image — kept verbatim, one turn could outweigh the
+# entire conversation, slow every read of the file and, since PERF-170, push
+# the rest of the chat into the archive on its own. They live here, beside
+# ``REPLAY_MAX_CHARS`` and ``TRANSCRIPT_MAX_BYTES``, and for the
 # same reason, rather than in ``timeouts.py``: that policy is
 # deadlines-in-seconds parsed from ``CONDOR_TIMEOUT_*``, and a character count
 # would not survive its loader.
@@ -399,22 +450,8 @@ def _iter_turns_reverse(path: Path) -> Iterator[TurnEntry]:
         log.debug("Unreadable transcript at %s", path, exc_info=True)
 
 
-def read_transcript(user_id: int, conv_id: str, *, limit: int = 200) -> list[TurnEntry]:
-    """The tail of a transcript. ``limit=0`` means all of it.
-
-    A line that fails to parse is skipped, never fatal — the same tolerance
-    ``read_status()`` shows for a truncated status file.
-
-    A bounded tail is read backwards from the end, so a conversation with
-    thousands of turns costs its tail rather than its whole history; only
-    ``limit=0`` still walks the file.
-    """
-    path = _conv_dir(user_id, conv_id) / TRANSCRIPT_FILENAME
-    if limit:
-        tail = list(islice(_iter_turns_reverse(path), limit))
-        tail.reverse()
-        return tail
-
+def _read_turns(path: Path) -> list[TurnEntry]:
+    """Every turn in one file, oldest first. Absent or unreadable reads empty."""
     entries: list[TurnEntry] = []
     try:
         if not path.is_file():
@@ -434,6 +471,56 @@ def read_transcript(user_id: int, conv_id: str, *, limit: int = 200) -> list[Tur
     return entries
 
 
+def read_transcript(
+    user_id: int,
+    conv_id: str,
+    *,
+    limit: int = 200,
+    include_archive: bool = False,
+) -> list[TurnEntry]:
+    """The tail of a transcript. ``limit=0`` means all of it.
+
+    A line that fails to parse is skipped, never fatal — the same tolerance
+    ``read_status()`` shows for a truncated status file.
+
+    A bounded tail is read backwards from the end, so a conversation with
+    thousands of turns costs its tail rather than its whole history; only
+    ``limit=0`` still walks the file.
+
+    "All of it" means the live transcript, which retention bounds — a long
+    conversation's older turns live in the sidecar and are represented in the
+    result by the archive marker turn, so a caller is never quietly handed a
+    partial history that looks whole. ``include_archive=True`` is the full
+    record: the sidecar is read too and the marker is dropped, because with
+    both files in hand nothing is missing for it to mark. It costs the whole
+    history by definition, so it belongs to an export or a support dig, never
+    to a request path.
+    """
+    conv_dir = _conv_dir(user_id, conv_id)
+    path = conv_dir / TRANSCRIPT_FILENAME
+    archive = conv_dir / TRANSCRIPT_ARCHIVE_FILENAME
+
+    if limit:
+        turns: Iterator[TurnEntry] = _iter_turns_reverse(path)
+        if include_archive:
+            turns = (
+                turn
+                for turn in chain(turns, _iter_turns_reverse(archive))
+                if not _is_archive_marker(turn)
+            )
+        tail = list(islice(turns, limit))
+        tail.reverse()
+        return tail
+
+    if not include_archive:
+        return _read_turns(path)
+    return [
+        turn
+        for turn in chain(_read_turns(archive), _read_turns(path))
+        if not _is_archive_marker(turn)
+    ]
+
+
 def append_turn(user_id: int, conv_id: str, entry: TurnEntry) -> None:
     """Append one turn and touch the conversation's meta.
 
@@ -450,6 +537,11 @@ def append_turn(user_id: int, conv_id: str, entry: TurnEntry) -> None:
         log.warning("Could not append turn to %s", conv_dir, exc_info=True)
         return
 
+    try:
+        _trim_transcript(conv_dir)
+    except Exception:  # noqa: BLE001 - retention must not break a live prompt
+        log.warning("Could not trim transcript for %s", conv_dir, exc_info=True)
+
     meta = get_conversation(user_id, conv_id)
     if meta is None:
         # The turn is on disk either way; without a meta there is nothing
@@ -465,6 +557,115 @@ def append_turn(user_id: int, conv_id: str, entry: TurnEntry) -> None:
     write_status(conv_dir, META_FILENAME, **fields)
 
 
+# ── Retention ──
+
+
+def _keep_bytes() -> int:
+    """How much of the newest transcript a trim has to leave behind."""
+    return max(TRANSCRIPT_KEEP_BYTES, REPLAY_MAX_CHARS * _REPLAY_HEADROOM)
+
+
+def _is_archive_marker(turn: TurnEntry) -> bool:
+    return turn.role == "system" and turn.kind == ARCHIVE_MARKER_KIND
+
+
+def _archived_count(line: bytes) -> int | None:
+    """Turns already archived according to ``line``; None if it is no marker.
+
+    A marker we cannot read the count out of returns 0 rather than None: it is
+    still a marker, so it must be replaced instead of kept as a turn, and
+    under-counting the total beats emitting two markers.
+    """
+    try:
+        data = json.loads(line.decode("utf-8"))
+    except (ValueError, UnicodeDecodeError):
+        return None
+    if not isinstance(data, dict) or data.get("kind") != ARCHIVE_MARKER_KIND:
+        return None
+    match = _ARCHIVE_MARKER_RE.match(str(data.get("text") or ""))
+    return int(match.group(1)) if match else 0
+
+
+def _archive_marker(count: int) -> bytes:
+    entry = TurnEntry(
+        role="system",
+        kind=ARCHIVE_MARKER_KIND,
+        text=f"{count} older turns moved to {TRANSCRIPT_ARCHIVE_FILENAME}",
+    )
+    return json.dumps(entry.model_dump(mode="json"), ensure_ascii=False).encode("utf-8")
+
+
+def _append_archive(conv_dir: Path, lines: list[bytes]) -> None:
+    """Append retired turns to the sidecar, durably.
+
+    ``fsync``-ed before the caller republishes the live file, because until
+    this returns the live file is the only copy of these turns.
+    """
+    with (conv_dir / TRANSCRIPT_ARCHIVE_FILENAME).open("ab") as fh:
+        fh.write(b"\n".join(lines) + b"\n")
+        fh.flush()
+        os.fsync(fh.fileno())
+
+
+def _trim_transcript(conv_dir: Path) -> None:
+    """Move the oldest turns of an oversized transcript into the sidecar.
+
+    Archive first, then republish the live file, so every crash window fails
+    safe. Before the archive write: the transcript is untouched. Between the
+    two: the moved turns exist in *both* files, and a duplicate in a sidecar
+    nobody reads on the hot path is a far better outcome than a hole in
+    someone's chat. During the republish: ``atomic_write_bytes`` publishes by
+    rename, so a reader sees the whole old file or the whole new one and a
+    crash leaves the old one intact — the trim simply happens again on the
+    next append. There is no ordering in which a turn is lost.
+
+    Whole lines only, and the newest turn is kept unconditionally: a single
+    turn larger than the entire budget has to shrink the file, not empty it.
+    """
+    path = conv_dir / TRANSCRIPT_FILENAME
+    try:
+        if path.stat().st_size <= TRANSCRIPT_MAX_BYTES:
+            return
+        raw = path.read_bytes()
+    except OSError:
+        log.debug("Could not read transcript for trimming at %s", path, exc_info=True)
+        return
+
+    lines = [line for line in raw.split(b"\n") if line.strip()]
+    if not lines:
+        return
+    archived = _archived_count(lines[0])
+    if archived is not None:
+        lines.pop(0)
+    if not lines:
+        return
+
+    budget = _keep_bytes()
+    cut = len(lines) - 1
+    kept = len(lines[-1]) + 1
+    for index in range(len(lines) - 2, -1, -1):
+        size = len(lines[index]) + 1
+        if kept + size > budget:
+            break
+        kept += size
+        cut = index
+
+    dropped, keep = lines[:cut], lines[cut:]
+    if not dropped:
+        return
+
+    try:
+        _append_archive(conv_dir, dropped)
+    except OSError:
+        # Nowhere safe to park them, so nothing moves: the file stays over the
+        # bound and the next append retries the trim.
+        log.warning("Could not archive turns for %s", conv_dir, exc_info=True)
+        return
+
+    marker = _archive_marker((archived or 0) + len(dropped))
+    atomic_write_bytes(path, b"\n".join([marker, *keep]) + b"\n")
+
+
 def update_meta(user_id: int, conv_id: str, **fields) -> bool:
     """Merge fields into an existing conversation's meta.
 
@@ -530,7 +731,16 @@ def replay_context(
 
     The walk reads the transcript backwards and parses lazily, so it stops at
     the turn that overruns the budget instead of parsing the whole file first:
-    this runs on the session-spawn path, and the transcript is append-only.
+    this runs on the session-spawn path.
+
+    Only the live transcript is read, never the archive, and retention is sized
+    so that is not a compromise: ``_keep_bytes()`` holds the tail at several
+    times ``REPLAY_MAX_CHARS``, so a trim can only ever remove turns this walk
+    had already stopped short of. The replay a resumed session receives is
+    therefore byte-identical before and after a trim. Where the replay does
+    stop is stated in the output itself, by the ``REPLAY_OMITTED`` footer —
+    which has always been the honest boundary here, since the budget cuts the
+    history long before retention does.
     """
     turns = _iter_turns_reverse(_conv_dir(user_id, conv_id) / TRANSCRIPT_FILENAME)
     newest_turn = next(turns, None)
diff --git a/tests/runtime/test_transcript_retention.py b/tests/runtime/test_transcript_retention.py
new file mode 100644
index 00000000..125fc82a
--- /dev/null
+++ b/tests/runtime/test_transcript_retention.py
@@ -0,0 +1,333 @@
+"""Retention for the conversation transcript (PERF-170).
+
+``transcript.jsonl`` was append-only with no sweep: PERF-138 made reading it
+cheap, but the file itself grew for the life of the conversation. It is now
+bounded in bytes, and the overflow is *moved* to ``transcript_archive.jsonl``
+rather than deleted — the same bargain PERF-136 struck for the agent journal,
+and a stricter one here, because this file is the user's own chat.
+
+Four properties, and the last three matter more than the first: the file is
+bounded, nothing is lost, no crash window can cost a turn, and a resumed
+session is handed exactly the replay it would have been handed untrimmed.
+"""
+
+import json
+
+import pytest
+
+from condor.runtime import conversations
+from condor.runtime.conversations import (
+    ARCHIVE_MARKER_KIND,
+    REPLAY_HEADER,
+    REPLAY_OMITTED,
+    TRANSCRIPT_ARCHIVE_FILENAME,
+    TRANSCRIPT_FILENAME,
+    TurnEntry,
+    _is_archive_marker,
+    _keep_bytes,
+    append_turn,
+    delete_conversation,
+    new_conversation,
+    read_transcript,
+    replay_context,
+)
+from condor.runtime.keys import WEB
+
+USER = 42
+
+# Small enough that a handful of turns crosses the bound, and far enough apart
+# that the trim still has real work to do on each crossing.
+MAX_BYTES = 4000
+KEEP_BYTES = 1000
+REPLAY_CHARS = 200
+
+
+@pytest.fixture
+def conv_root(isolated_conversation_root):
+    """The throwaway store root (see ``conftest.py``)."""
+    return isolated_conversation_root
+
+
+@pytest.fixture
+def small_retention(monkeypatch):
+    """Shrink the whole policy so a test can cross it in a few turns.
+
+    ``REPLAY_MAX_CHARS`` comes down with it: ``_keep_bytes()`` floors the kept
+    tail at a multiple of the replay budget, so leaving the real 6000 here
+    would put the floor above ``MAX_BYTES`` and no trim would ever fire.
+    """
+    monkeypatch.setattr(conversations, "TRANSCRIPT_MAX_BYTES", MAX_BYTES)
+    monkeypatch.setattr(conversations, "TRANSCRIPT_KEEP_BYTES", KEEP_BYTES)
+    monkeypatch.setattr(conversations, "REPLAY_MAX_CHARS", REPLAY_CHARS)
+
+
+def _talk(conv_id, turns, *, body=200):
+    """Append ``turns`` user/assistant pairs of predictable, findable text."""
+    for index in range(turns):
+        append_turn(
+            USER, conv_id, TurnEntry(role="user", text=f"q{index} " + "." * body)
+        )
+        append_turn(
+            USER, conv_id, TurnEntry(role="assistant", text=f"a{index} " + "." * body)
+        )
+
+
+def _live(conv_root, conv_id):
+    return conv_root / str(USER) / conv_id / TRANSCRIPT_FILENAME
+
+
+def _archive(conv_root, conv_id):
+    return conv_root / str(USER) / conv_id / TRANSCRIPT_ARCHIVE_FILENAME
+
+
+# ── The file is bounded ──
+
+
+def test_the_live_transcript_stays_bounded_over_many_turns(conv_root, small_retention):
+    """Hundreds of turns, and the hot file never runs away."""
+    meta = new_conversation(USER, WEB)
+    sizes = []
+    for _ in range(50):
+        _talk(meta.id, 2)
+        sizes.append(_live(conv_root, meta.id).stat().st_size)
+
+    assert max(sizes) <= MAX_BYTES + 2000, f"unbounded: peaked at {max(sizes)}"
+    # And it really did grow past the bound repeatedly rather than never
+    # reaching it: the archive is where the difference went.
+    assert _archive(conv_root, meta.id).stat().st_size > 10 * MAX_BYTES
+
+
+def test_a_conversation_under_the_bound_is_never_touched(conv_root, small_retention):
+    """No archive, no marker, no rewrite for the conversations people actually have."""
+    meta = new_conversation(USER, WEB)
+    _talk(meta.id, 3, body=20)
+
+    assert not _archive(conv_root, meta.id).exists()
+    assert not any(_is_archive_marker(t) for t in read_transcript(USER, meta.id))
+    assert len(read_transcript(USER, meta.id, limit=0)) == 6
+
+
+# ── Nothing is lost ──
+
+
+def test_no_turn_is_destroyed_by_a_trim(conv_root, small_retention):
+    """Every turn ever written comes back, in order, across many trims."""
+    meta = new_conversation(USER, WEB)
+    _talk(meta.id, 40)
+
+    full = read_transcript(USER, meta.id, limit=0, include_archive=True)
+    assert [t.text.split()[0] for t in full] == [
+        label for index in range(40) for label in (f"q{index}", f"a{index}")
+    ]
+
+
+def test_the_archive_holds_exactly_what_the_live_file_gave_up(
+    conv_root, small_retention
+):
+    """live + archive == the whole history, with no turn in both and none in neither."""
+    meta = new_conversation(USER, WEB)
+    _talk(meta.id, 30)
+
+    live = [t.text for t in read_transcript(USER, meta.id, limit=0) if t.text]
+    archived = [t.text for t in conversations._read_turns(_archive(conv_root, meta.id))]
+    marker = [
+        t for t in read_transcript(USER, meta.id, limit=0) if _is_archive_marker(t)
+    ]
+
+    assert len(marker) == 1, "one marker, folded forward, never a stack of them"
+    assert set(archived).isdisjoint(set(live) - {marker[0].text})
+    assert len(archived) + len(live) - 1 == 60
+
+
+def test_the_live_file_says_how_much_it_no_longer_holds(conv_root, small_retention):
+    """The marker names the sidecar and the running total, so nothing lies."""
+    meta = new_conversation(USER, WEB)
+    _talk(meta.id, 30)
+
+    turns = read_transcript(USER, meta.id, limit=0)
+    marker = next(t for t in turns if _is_archive_marker(t))
+    archived = conversations._read_turns(_archive(conv_root, meta.id))
+
+    assert marker.kind == ARCHIVE_MARKER_KIND
+    assert TRANSCRIPT_ARCHIVE_FILENAME in marker.text
+    assert marker.text.startswith(f"{len(archived)} older turns moved to")
+    assert turns[0] is turns[0] and _is_archive_marker(turns[0]), "at the head"
+
+
+def test_the_full_read_drops_the_marker_because_nothing_is_missing(
+    conv_root, small_retention
+):
+    """``include_archive`` is the complete record, so there is no boundary to mark."""
+    meta = new_conversation(USER, WEB)
+    _talk(meta.id, 30)
+
+    assert any(_is_archive_marker(t) for t in read_transcript(USER, meta.id, limit=0))
+    for turns in (
+        read_transcript(USER, meta.id, limit=0, include_archive=True),
+        read_transcript(USER, meta.id, limit=500, include_archive=True),
+    ):
+        assert not any(_is_archive_marker(t) for t in turns)
+
+
+def test_a_bounded_tail_reaches_back_into_the_archive(conv_root, small_retention):
+    """A tail longer than the live file continues into the sidecar, in order."""
+    meta = new_conversation(USER, WEB)
+    _talk(meta.id, 30)
+
+    live_turns = len(read_transcript(USER, meta.id, limit=0))
+    deep = read_transcript(USER, meta.id, limit=live_turns + 10, include_archive=True)
+
+    # The marker is filtered before the bound is applied, so a caller asking
+    # for N turns gets N real ones rather than N-1 and a signpost.
+    assert len(deep) == live_turns + 10
+    full = read_transcript(USER, meta.id, limit=0, include_archive=True)
+    assert [t.text for t in deep] == [t.text for t in full[-len(deep) :]]
+
+
+def test_deleting_a_conversation_takes_the_archive_with_it(conv_root, small_retention):
+    """Forgetting a chat still forgets all of it — the sidecar is not a leak."""
+    meta = new_conversation(USER, WEB)
+    _talk(meta.id, 30)
+    assert _archive(conv_root, meta.id).exists()
+
+    assert delete_conversation(USER, meta.id) is True
+    assert not _archive(conv_root, meta.id).exists()
+
+
+# ── No crash window costs a turn ──
+
+
+def test_a_crash_publishing_the_trimmed_file_loses_nothing(
+    conv_root, small_retention, monkeypatch
+):
+    """The rewrite is atomic: a failed publish leaves the whole old file."""
+
+    def boom(*args, **kwargs):
+        raise OSError("crash mid-write")
+
+    monkeypatch.setattr(conversations, "atomic_write_bytes", boom)
+    meta = new_conversation(USER, WEB)
+    _talk(meta.id, 20)  # must not raise: retention never breaks a live prompt
+
+    # The trim never landed, so the live file is over the bound — and still
+    # holds every single turn. Over-large beats truncated.
+    assert _live(conv_root, meta.id).stat().st_size > MAX_BYTES
+    assert [t.text.split()[0] for t in read_transcript(USER, meta.id, limit=0)] == [
+        label for index in range(20) for label in (f"q{index}", f"a{index}")
+    ]
+
+
+def test_a_crash_writing_the_archive_leaves_the_transcript_intact(
+    conv_root, small_retention, monkeypatch
+):
+    """Nowhere safe to park the turns means nothing is dropped."""
+    monkeypatch.setattr(
+        conversations,
+        "_append_archive",
+        lambda *a, **kw: (_ for _ in ()).throw(OSError("no sidecar")),
+    )
+    meta = new_conversation(USER, WEB)
+    _talk(meta.id, 20)
+
+    assert not _archive(conv_root, meta.id).exists()
+    assert len(read_transcript(USER, meta.id, limit=0)) == 40
+
+
+def test_the_trim_is_retried_on_the_next_append(
+    conv_root, small_retention, monkeypatch
+):
+    """A window that failed is not a window that gave up."""
+    calls = {"n": 0}
+    real = conversations._append_archive
+
+    def flaky(conv_dir, lines):
+        calls["n"] += 1
+        if calls["n"] == 1:
+            raise OSError("transient")
+        return real(conv_dir, lines)
+
+    monkeypatch.setattr(conversations, "_append_archive", flaky)
+    meta = new_conversation(USER, WEB)
+    _talk(meta.id, 20)
+
+    assert calls["n"] > 1
+    assert _archive(conv_root, meta.id).exists()
+    assert len(read_transcript(USER, meta.id, limit=0, include_archive=True)) == 40
+
+
+def test_a_trim_publishes_only_whole_lines(conv_root, small_retention):
+    """Every line of both files still parses as JSON after repeated trims."""
+    meta = new_conversation(USER, WEB)
+    _talk(meta.id, 40)
+
+    for path in (_live(conv_root, meta.id), _archive(conv_root, meta.id)):
+        raw = path.read_bytes()
+        assert raw.endswith(b"\n"), f"{path.name} ends mid-line"
+        for line in raw.split(b"\n"):
+            if line.strip():
+                json.loads(line.decode("utf-8"))
+
+
+# ── The replay is unaffected ──
+
+
+def test_the_kept_tail_can_always_fill_the_replay_budget(monkeypatch):
+    """The floor holds even when the configured keep is absurdly small."""
+    monkeypatch.setattr(conversations, "TRANSCRIPT_KEEP_BYTES", 1)
+    monkeypatch.setattr(conversations, "REPLAY_MAX_CHARS", 6000)
+    assert _keep_bytes() >= 6000
+
+
+def test_replay_is_identical_with_and_without_retention(conv_root, monkeypatch):
+    """The whole point: a trim cannot change what a resumed session is handed.
+
+    Same turns, one conversation trimmed to the bone and one with retention
+    effectively off. The replay walks back from the newest turn and stops at
+    the budget, and the kept tail is always wider than that budget — so the two
+    must agree byte for byte.
+    """
+    monkeypatch.setattr(conversations, "REPLAY_MAX_CHARS", REPLAY_CHARS)
+
+    monkeypatch.setattr(conversations, "TRANSCRIPT_MAX_BYTES", 10**9)
+    untrimmed = new_conversation(USER, WEB)
+    _talk(untrimmed.id, 40)
+
+    monkeypatch.setattr(conversations, "TRANSCRIPT_MAX_BYTES", MAX_BYTES)
+    monkeypatch.setattr(conversations, "TRANSCRIPT_KEEP_BYTES", KEEP_BYTES)
+    trimmed = new_conversation(USER, WEB)
+    _talk(trimmed.id, 40)
+
+    assert _archive(conv_root, trimmed.id).exists(), "the trimmed one really trimmed"
+    assert not _archive(conv_root, untrimmed.id).exists()
+
+    expected = replay_context(USER, untrimmed.id, max_chars=REPLAY_CHARS)
+    assert replay_context(USER, trimmed.id, max_chars=REPLAY_CHARS) == expected
+    assert expected.startswith(REPLAY_HEADER)
+    assert "a39" in expected, "the newest turn survives, which is what replay is for"
+
+
+def test_replay_stays_coherent_after_a_trim(conv_root, small_retention):
+    """Header, newest turns, explicit boundary, and never over the budget."""
+    meta = new_conversation(USER, WEB)
+    _talk(meta.id, 40)
+
+    replay = replay_context(USER, meta.id, max_chars=REPLAY_CHARS)
+
+    assert replay.startswith(REPLAY_HEADER)
+    assert replay.endswith(REPLAY_OMITTED)
+    assert len(replay) <= REPLAY_CHARS
+    assert "a39" in replay
+
+
+def test_the_newest_turn_survives_a_turn_larger_than_the_whole_budget(
+    conv_root, small_retention
+):
+    """A trim has to shrink the file, never empty it."""
+    meta = new_conversation(USER, WEB)
+    _talk(meta.id, 10)
+    append_turn(USER, meta.id, TurnEntry(role="assistant", text="huge " + "z" * 50_000))
+
+    turns = read_transcript(USER, meta.id, limit=0)
+    assert turns[-1].text.startswith("huge ")
+    assert replay_context(USER, meta.id, max_chars=REPLAY_CHARS).count("huge") == 1
+    assert len(read_transcript(USER, meta.id, limit=0, include_archive=True)) == 21

From 58a4d913c944ff3f35ad6c47c93372b9e2179769 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Fri, 14 Aug 2026 18:16:37 +0300
Subject: [PATCH 091/116] (fix) SEC-176: stop offering credential add/delete to
 non-owner traders
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

SEC-153 raised exchange credential add/delete from TRADER to OWNER, but
ApiKeysSettings had no permission awareness: a shared trader still saw the
Add API Key and Delete buttons and only learned they were refused after
clicking, when a 403 came back.

The backend already serializes the answer. `ServerInfo.permission` comes
straight from `get_server_permission()` — the same function `_require_owner`
and `has_server_access` consult — so the client reads the level rather than
re-deriving the rule, and no new API surface was needed.

`useServerPermission()` joins the selected server against the `["servers"]`
query the server selector already keeps warm, so it costs a cache read. It
resolves unknown to *allowed*: a slow or failed server list degrades to the
previous behaviour instead of inventing a refusal the API never made.

This is UX, not enforcement. The backend gate remains the only thing that
secures the route; a disabled button merely stops the dashboard promising
what the API will refuse. Accordingly the failure path got louder rather
than quieter: a delete that is refused anyway (stale permission, a share
revoked mid-session) now renders the API's own detail instead of silently
doing nothing.

Gateway wallet controls are deliberately left open — those routes are not
owner-gated today, and the client should mirror the backend, not lead it.
---
 .../components/settings/ApiKeysSettings.tsx   | 22 ++++++-
 frontend/src/hooks/useServerPermission.ts     | 58 +++++++++++++++++++
 2 files changed, 77 insertions(+), 3 deletions(-)
 create mode 100644 frontend/src/hooks/useServerPermission.ts

diff --git a/frontend/src/components/settings/ApiKeysSettings.tsx b/frontend/src/components/settings/ApiKeysSettings.tsx
index 6ef641d5..b69fb06b 100644
--- a/frontend/src/components/settings/ApiKeysSettings.tsx
+++ b/frontend/src/components/settings/ApiKeysSettings.tsx
@@ -14,6 +14,7 @@ import {
 import { useEffect, useMemo, useState } from "react";
 
 import { useServer } from "@/hooks/useServer";
+import { OWNER_ONLY_HINT, useServerPermission } from "@/hooks/useServerPermission";
 import { type ConnectorInfo, type CredentialInfo, type GatewayWalletGroup, api } from "@/lib/api";
 import { ConnectHyperliquid } from "./ConnectHyperliquid";
 import { ImportGatewayWallet, type WalletChain } from "./ImportGatewayWallet";
@@ -73,6 +74,11 @@ function isCredentialField(key: string, type?: string): boolean {
 
 export function ApiKeysSettings() {
   const { server } = useServer();
+  // Credential add/delete is owner-only on the backend (SEC-153). Reading the
+  // level here does not enforce anything — the API still answers 403 — it just
+  // stops the UI from offering a trader an action that is going to be refused.
+  // Gateway wallet controls stay open: those routes are not owner-gated.
+  const { isOwner } = useServerPermission();
   const qc = useQueryClient();
   const [flow, setFlow] = useState<AddFlowState>(INITIAL_FLOW);
   const [confirmDelete, setConfirmDelete] = useState<string | null>(null);
@@ -507,7 +513,9 @@ export function ApiKeysSettings() {
           </button>
           <button
             onClick={() => setFlow({ ...INITIAL_FLOW, step: "select-type" })}
-            className="flex items-center gap-1.5 rounded-md bg-[var(--color-primary)] px-3 py-1.5 text-xs font-medium text-white transition-colors hover:bg-[var(--color-primary)]/80"
+            disabled={!isOwner}
+            title={isOwner ? undefined : OWNER_ONLY_HINT}
+            className="flex items-center gap-1.5 rounded-md bg-[var(--color-primary)] px-3 py-1.5 text-xs font-medium text-white transition-colors hover:bg-[var(--color-primary)]/80 disabled:cursor-not-allowed disabled:opacity-50 disabled:hover:bg-[var(--color-primary)]"
           >
             <Plus className="h-3.5 w-3.5" /> Add API Key
           </button>
@@ -568,8 +576,9 @@ export function ApiKeysSettings() {
                     ) : (
                       <button
                         onClick={() => setConfirmDelete(c.connector_name)}
-                        className="rounded p-1.5 text-[var(--color-text-muted)] hover:bg-[var(--color-surface-hover)] hover:text-[var(--color-red)]"
-                        title="Delete credential"
+                        disabled={!isOwner}
+                        className="rounded p-1.5 text-[var(--color-text-muted)] hover:bg-[var(--color-surface-hover)] hover:text-[var(--color-red)] disabled:cursor-not-allowed disabled:opacity-40 disabled:hover:bg-transparent disabled:hover:text-[var(--color-text-muted)]"
+                        title={isOwner ? "Delete credential" : OWNER_ONLY_HINT}
                       >
                         <Trash2 className="h-3.5 w-3.5" />
                       </button>
@@ -582,6 +591,13 @@ export function ApiKeysSettings() {
         </div>
       )}
 
+      {/* A refusal that slips past the disabled state (stale permission, a race with
+          a revoked share) still has to say something the user can act on — the API's
+          own detail, e.g. "Owner access required", rather than a silent no-op. */}
+      {deleteMut.error && (
+        <p className="text-xs text-[var(--color-red)]">{deleteMut.error.message}</p>
+      )}
+
       {/* ── Gateway wallets ── */}
       <div>
         <h3 className="mb-2 text-xs font-semibold uppercase tracking-wider text-[var(--color-text-muted)]">
diff --git a/frontend/src/hooks/useServerPermission.ts b/frontend/src/hooks/useServerPermission.ts
new file mode 100644
index 00000000..cd286bf6
--- /dev/null
+++ b/frontend/src/hooks/useServerPermission.ts
@@ -0,0 +1,58 @@
+import { useQuery } from "@tanstack/react-query";
+
+import { type ServerInfo, api } from "@/lib/api";
+import { useServer } from "./useServer";
+
+/**
+ * The caller's permission level on a server, as reported by the API.
+ *
+ * This is a *UX* signal, not an authorization decision. The backend owns
+ * enforcement — `require_server_access*` in `condor/web/auth.py` plus the
+ * per-route `_require_owner` gate in `condor/web/routes/settings.py` — and it
+ * answers 403 whatever the client believes. What this hook buys is honesty in
+ * the UI: an action the API will refuse should not be offered as if it worked.
+ *
+ * The value comes from the same `get_server_permission()` the backend gate
+ * consults (serialized on every `ServerInfo`), so the client never re-derives
+ * the rule; it only reads the answer.
+ */
+
+/** Marker returned by the API for a server the caller owns (Condor admins included). */
+const OWNER = "owner";
+
+/** Explanation shown on controls that only a server owner may use. */
+export const OWNER_ONLY_HINT =
+  "Only the server's owner can change this — you have trader access to this server.";
+
+export interface ServerPermissionState {
+  /** "owner" | "trader", or null while the server list is still unresolved. */
+  permission: string | null;
+  /**
+   * Whether owner-only controls should be offered. Unknown means *allowed*:
+   * the client's job is to predict a refusal, never to invent one, so a slow
+   * or failed server list degrades to the pre-existing behaviour and lets the
+   * backend have the final word.
+   */
+  isOwner: boolean;
+}
+
+/**
+ * Permission the current user holds on `serverName` (defaults to the selected
+ * server). Shares the `["servers"]` query with the server selector, so it costs
+ * a cache read rather than a request.
+ */
+export function useServerPermission(serverName?: string | null): ServerPermissionState {
+  const { server } = useServer();
+  const name = serverName ?? server;
+
+  const { data } = useQuery({
+    queryKey: ["servers"],
+    queryFn: api.getServers,
+    staleTime: 30_000,
+  });
+
+  const permission =
+    (data as ServerInfo[] | undefined)?.find((s) => s.name === name)?.permission ?? null;
+
+  return { permission, isOwner: permission === null || permission === OWNER };
+}

From 026570f5a9742a179181d49ceb903088817b55f4 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Fri, 14 Aug 2026 18:24:02 +0300
Subject: [PATCH 092/116] (feat) ARCH-177: an admin API for the code_run grant,
 and make it survive a save
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

SEC-151 gated /code/run on "admin or an explicit per-user code_run grant". The
grant arm was unreachable: setting it meant hand-editing config.yml. Worse, the
hand edit did not survive — _save_config whitelists the sections it writes and
user_preferences was not among them, so every set_user_preference call persisted
nothing and the next save silently erased whatever had been edited in by hand.
The escape hatch was not merely undocumented, it did not work.

So this lands the half that has to exist either way:

- config_manager owns the grant. CODE_RUN_PREFERENCE moves here beside the
  setter that drives it, and routes/code.py re-exports it so the gate and the
  thing that opens it cannot drift apart. set_code_run_grant() persists and
  audits both edges like approve_user/block_user does, and revoking deletes the
  key rather than writing False so config.yml lists only actual holders.
- user_preferences is added to the _save_config whitelist. Without it nothing
  above persists, and a grant would evaporate on the next unrelated write.
- routes/admin.py is the first admin surface on the web API: GET /admin/users
  reports every user with the grant they carry, PUT /admin/users/{id}/code-run
  moves it. Both re-read is_admin from the ConfigManager rather than trusting
  the JWT role claim, so a demotion takes effect on the next request. Granting
  to an admin is a 409, not a stored no-op that would outlive the role.

The gate itself is untouched — admins still pass on their role alone, which a
test now pins so a later change cannot narrow it by accident.

The UI half of ARCH-177 is NOT here. It needs api.* client methods and
frontend/src/lib/api.ts is dirty from concurrent work in the DEX pages, so the
item stays in todo/ with the backend recorded against it.
---
 condor/web/app.py                  |   2 +
 condor/web/routes/admin.py         | 119 ++++++++++++++++++
 condor/web/routes/code.py          |   6 +-
 config_manager.py                  |  51 ++++++++
 tests/test_code_run_grant_admin.py | 192 +++++++++++++++++++++++++++++
 5 files changed, 368 insertions(+), 2 deletions(-)
 create mode 100644 condor/web/routes/admin.py
 create mode 100644 tests/test_code_run_grant_admin.py

diff --git a/condor/web/app.py b/condor/web/app.py
index 71ae9d9f..e5ca6d62 100644
--- a/condor/web/app.py
+++ b/condor/web/app.py
@@ -11,6 +11,7 @@
 
 from condor.telemetry.taps import web_tap
 from condor.web.routes import (
+    admin,
     agents,
     archived,
     auth,
@@ -74,6 +75,7 @@ def create_app() -> FastAPI:
 
     # ── API routes ──
     app.include_router(auth.router, prefix="/api/v1")
+    app.include_router(admin.router, prefix="/api/v1")
     app.include_router(servers.router, prefix="/api/v1")
     app.include_router(portfolio.router, prefix="/api/v1")
     app.include_router(bots.router, prefix="/api/v1")
diff --git a/condor/web/routes/admin.py b/condor/web/routes/admin.py
new file mode 100644
index 00000000..3272a259
--- /dev/null
+++ b/condor/web/routes/admin.py
@@ -0,0 +1,119 @@
+"""Admin-only user administration for the web dashboard (ARCH-177).
+
+Today this carries exactly one capability, the ``code_run`` grant SEC-151
+introduced: the gate in ``routes/code.py`` is *admin or an explicit per-user
+grant*, and until now the only way to set that grant was hand-editing
+config.yml. This is where an admin sets it instead.
+
+Every route here is admin-only, checked server-side by ``_require_admin``. The
+dashboard hides the panel from non-admins, but that is cosmetic — hiding a
+control is not a gate, so each handler asks again and answers 403 whatever the
+client believes it is.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel
+
+from condor.web.auth import get_current_user
+from condor.web.models import WebUser
+from config_manager import UserRole, get_config_manager
+
+log = logging.getLogger(__name__)
+router = APIRouter(prefix="/admin", tags=["admin"])
+
+
+def _require_admin(user: WebUser) -> None:
+    """Refuse anyone who is not a Condor admin.
+
+    Mirrors the shape of the telemetry gate in ``routes/settings.py``: the role
+    is re-read from the ConfigManager rather than trusted from the JWT claim,
+    so demoting a user takes effect on their next request.
+    """
+    if not get_config_manager().is_admin(user.id):
+        raise HTTPException(
+            status_code=403,
+            detail="Only an admin can administer users",
+        )
+
+
+class AdminUser(BaseModel):
+    """A user row as the admin panel needs it."""
+
+    user_id: int
+    username: str = ""
+    role: str = ""
+    # Whether the explicit grant is set on this record. Admins are reported
+    # separately via `is_admin`: they can already run code without a grant, and
+    # showing them as "granted" would misrepresent what revoking would do.
+    code_run: bool = False
+    is_admin: bool = False
+
+
+@router.get("/users", response_model=list[AdminUser])
+async def list_users(user: WebUser = Depends(get_current_user)):
+    """Every user record, with the code_run grant each one carries."""
+    _require_admin(user)
+    cm = get_config_manager()
+    rows = []
+    for record in cm.get_all_users():
+        uid = record.get("user_id")
+        if uid is None:
+            continue
+        rows.append(
+            AdminUser(
+                user_id=uid,
+                username=record.get("username") or "",
+                role=record.get("role") or "",
+                code_run=cm.has_code_run_grant(uid),
+                is_admin=record.get("role") == UserRole.ADMIN.value,
+            )
+        )
+    rows.sort(key=lambda r: (not r.is_admin, r.username.lower(), r.user_id))
+    return rows
+
+
+class CodeRunGrantRequest(BaseModel):
+    granted: bool
+
+
+@router.put("/users/{user_id}/code-run")
+async def set_code_run_grant(
+    user_id: int,
+    body: CodeRunGrantRequest,
+    user: WebUser = Depends(get_current_user),
+):
+    """Grant or revoke ``code_run`` for one user.
+
+    The grant confers arbitrary Python execution inside the bot process — it is
+    admin-equivalent in practice — so it is admin-only, audited by
+    ``set_code_run_grant``, and takes effect on the next request without a
+    restart because the gate re-reads config.yml every time.
+
+    Granting to an admin is refused rather than silently stored: they already
+    pass the gate on the admin arm, so the grant would be a no-op record that
+    survives a demotion and quietly outlives the role that justified it.
+    """
+    _require_admin(user)
+    cm = get_config_manager()
+
+    if cm.get_user(user_id) is None:
+        raise HTTPException(status_code=404, detail=f"Unknown user {user_id}")
+    if body.granted and cm.is_admin(user_id):
+        raise HTTPException(
+            status_code=409,
+            detail="Admins can already run code; no grant is needed",
+        )
+
+    changed = cm.set_code_run_grant(user_id, body.granted, admin_id=user.id)
+    if changed:
+        log.warning(
+            "Admin %s %s code_run for user %s",
+            user.id,
+            "granted" if body.granted else "revoked",
+            user_id,
+        )
+    return {"user_id": user_id, "code_run": cm.has_code_run_grant(user_id)}
diff --git a/condor/web/routes/code.py b/condor/web/routes/code.py
index cde8ded4..7a9e50aa 100644
--- a/condor/web/routes/code.py
+++ b/condor/web/routes/code.py
@@ -25,13 +25,15 @@
 from condor.code_runner import DEFAULT_TIMEOUT, MAX_TIMEOUT, execute_code
 from condor.web.auth import check_server_access, get_current_user
 from condor.web.models import WebUser
-from config_manager import get_config_manager
+from config_manager import CODE_RUN_PREFERENCE, get_config_manager
 
 log = logging.getLogger(__name__)
 router = APIRouter(prefix="/code", tags=["code"])
 
 # The preference an admin sets on a user record to hand them the code runner.
-RUN_CODE_PREFERENCE = "code_run"
+# The spelling lives in config_manager beside the setter an admin drives it
+# from (ARCH-177); re-exported here because this is where it is enforced.
+RUN_CODE_PREFERENCE = CODE_RUN_PREFERENCE
 
 
 def _may_run_code(user_id: int) -> bool:
diff --git a/config_manager.py b/config_manager.py
index cf2dc723..38b0638c 100644
--- a/config_manager.py
+++ b/config_manager.py
@@ -39,6 +39,13 @@ class ServerPermission(str, Enum):
     ServerPermission.OWNER: 1,
 }
 
+# The user preference that hands a non-admin seat the in-process code runner
+# (SEC-151). It is stored under ``user_preferences[<id>]`` like any other
+# preference, but it is a *capability grant*: only an admin may set it, and
+# ``condor/web/routes/code.py`` reads it as the fallback arm of its gate.
+# Declared here so the gate and the thing that grants it share one spelling.
+CODE_RUN_PREFERENCE = "code_run"
+
 
 class ConfigManager:
     """
@@ -217,6 +224,10 @@ def _save_config(self):
                 "users": self._data.get("users", {}),
                 "server_access": self._data.get("server_access", {}),
                 "chat_defaults": self._data.get("chat_defaults", {}),
+                # Omitting this dropped every preference on the next save —
+                # including the code_run grant, which _load_config reads back
+                # and routes/code.py gates on (ARCH-177).
+                "user_preferences": self._data.get("user_preferences", {}),
                 "web_jwt_secret": self._data.get("web_jwt_secret"),
                 "telemetry": self._data.get("telemetry", {}),
                 "version": self._data.get("version", self.VERSION),
@@ -750,6 +761,46 @@ def delete_user_preference(self, user_id: int, key: str) -> bool:
             return True
         return False
 
+    def has_code_run_grant(self, user_id: int) -> bool:
+        """Whether this user carries the explicit ``code_run`` grant.
+
+        Says nothing about admins: being an admin is a separate arm of the gate
+        in ``condor/web/routes/code.py``. This answers only "was the capability
+        handed to them", which is what an admin UI needs to render.
+        """
+        return bool(self.get_user_preference(user_id, CODE_RUN_PREFERENCE, False))
+
+    def set_code_run_grant(self, user_id: int, granted: bool, admin_id: int) -> bool:
+        """Grant or revoke the ``code_run`` capability. Returns True if changed.
+
+        Handing this out is handing out arbitrary Python in the bot's own
+        process — every server's credentials, the web JWT secret, os.environ —
+        so it is audited on both edges like ``approve_user``/``block_user``, and
+        the caller is expected to have already checked ``is_admin(admin_id)``.
+
+        Revoking deletes the key rather than writing ``False``, so config.yml
+        keeps only the users who actually hold the grant. Either way the write
+        lands in config.yml immediately and the next request re-reads it, so a
+        grant takes effect without restarting the bot.
+        """
+        if user_id not in self._data.get("users", {}):
+            return False
+        if self.has_code_run_grant(user_id) == bool(granted):
+            return False
+
+        if granted:
+            self.set_user_preference(user_id, CODE_RUN_PREFERENCE, True)
+        else:
+            self.delete_user_preference(user_id, CODE_RUN_PREFERENCE)
+
+        self._audit(
+            "code_run_granted" if granted else "code_run_revoked",
+            "user",
+            str(user_id),
+            admin_id,
+        )
+        return True
+
     # =========================================================================
     # SERVER ACCESS CONTROL
     # =========================================================================
diff --git a/tests/test_code_run_grant_admin.py b/tests/test_code_run_grant_admin.py
new file mode 100644
index 00000000..883689da
--- /dev/null
+++ b/tests/test_code_run_grant_admin.py
@@ -0,0 +1,192 @@
+"""Who may hand out the code_run capability, and what handing it out does.
+
+The grant SEC-151 left as the non-admin escape hatch is arbitrary Python in the
+bot's own process. ARCH-177 gave it an admin API instead of a hand edit of
+config.yml, so the two things worth pinning down are: only an admin can move it,
+and moving it actually moves the gate in ``routes/code.py``.
+"""
+
+import asyncio
+
+import pytest
+from fastapi import HTTPException
+
+import config_manager as cm_module
+from condor.web.models import WebUser
+from condor.web.routes import admin as admin_routes
+from condor.web.routes import code as code_routes
+from condor.web.routes.admin import CodeRunGrantRequest, list_users, set_code_run_grant
+
+ADMIN = WebUser(id=1, username="root", role="admin")
+SEAT = WebUser(id=2, username="quant", role="user")
+OTHER = WebUser(id=3, username="intern", role="user")
+
+
+@pytest.fixture
+def cm(tmp_path, monkeypatch):
+    """A real ConfigManager on a throwaway config.yml — persistence included."""
+    monkeypatch.chdir(tmp_path)  # audit_log.yml is written relative to cwd
+    manager = cm_module.ConfigManager(config_path=str(tmp_path / "config.yml"))
+    manager._data["users"] = {
+        ADMIN.id: {"user_id": ADMIN.id, "username": "root", "role": "admin"},
+        SEAT.id: {"user_id": SEAT.id, "username": "quant", "role": "user"},
+        OTHER.id: {"user_id": OTHER.id, "username": "intern", "role": "user"},
+    }
+    manager._data["user_preferences"] = {}
+    manager._audit_log = []
+    manager._save_config()
+    for module in (cm_module, admin_routes, code_routes):
+        monkeypatch.setattr(module, "get_config_manager", lambda: manager)
+    return manager
+
+
+def _set(actor, target_id, granted):
+    return asyncio.run(
+        set_code_run_grant(target_id, CodeRunGrantRequest(granted=granted), user=actor)
+    )
+
+
+# ── only an admin may move the grant ──
+
+
+def test_a_non_admin_cannot_grant_code_run_to_anyone(cm):
+    """Hiding the panel is cosmetic; the refusal has to live on the server."""
+    with pytest.raises(HTTPException) as excinfo:
+        _set(SEAT, OTHER.id, True)
+
+    assert excinfo.value.status_code == 403
+    assert cm.has_code_run_grant(OTHER.id) is False
+
+
+def test_a_non_admin_cannot_grant_code_run_to_themselves(cm):
+    """The interesting attack is self-escalation, not granting a colleague."""
+    with pytest.raises(HTTPException) as excinfo:
+        _set(SEAT, SEAT.id, True)
+
+    assert excinfo.value.status_code == 403
+    assert cm.has_code_run_grant(SEAT.id) is False
+
+
+def test_a_non_admin_cannot_revoke_an_existing_grant(cm):
+    cm.set_code_run_grant(SEAT.id, True, admin_id=ADMIN.id)
+
+    with pytest.raises(HTTPException) as excinfo:
+        _set(OTHER, SEAT.id, False)
+
+    assert excinfo.value.status_code == 403
+    assert cm.has_code_run_grant(SEAT.id) is True
+
+
+def test_a_non_admin_cannot_even_list_the_users(cm):
+    with pytest.raises(HTTPException) as excinfo:
+        asyncio.run(list_users(user=SEAT))
+
+    assert excinfo.value.status_code == 403
+
+
+def test_the_role_is_reread_not_trusted_from_the_token(cm):
+    """A JWT minted while the caller was an admin must not outlive the role."""
+    stale = WebUser(id=SEAT.id, username="quant", role="admin")
+
+    with pytest.raises(HTTPException) as excinfo:
+        _set(stale, OTHER.id, True)
+
+    assert excinfo.value.status_code == 403
+
+
+# ── the grant reaches the gate ──
+
+
+def test_granting_opens_the_code_run_gate_for_that_user(cm):
+    assert code_routes._may_run_code(SEAT.id) is False
+
+    _set(ADMIN, SEAT.id, True)
+
+    assert code_routes._may_run_code(SEAT.id) is True
+    assert code_routes._may_run_code(OTHER.id) is False, "grant is per user"
+
+
+def test_revoking_closes_the_gate_again(cm):
+    _set(ADMIN, SEAT.id, True)
+    out = _set(ADMIN, SEAT.id, False)
+
+    assert out["code_run"] is False
+    assert code_routes._may_run_code(SEAT.id) is False
+
+
+def test_the_grant_lands_in_config_yml_so_no_restart_is_needed(cm):
+    """The gate re-reads the manager each call; a reload must agree with it."""
+    _set(ADMIN, SEAT.id, True)
+
+    reloaded = cm_module.ConfigManager(config_path=str(cm.config_path))
+    assert reloaded.has_code_run_grant(SEAT.id) is True
+
+
+def test_an_unrelated_save_does_not_drop_the_grant(cm):
+    """_save_config whitelists sections; user_preferences was missing from it."""
+    _set(ADMIN, SEAT.id, True)
+    cm._data["chat_defaults"][SEAT.id] = "prod"  # any other config write
+    cm._save_config()
+
+    reloaded = cm_module.ConfigManager(config_path=str(cm.config_path))
+    assert reloaded.has_code_run_grant(SEAT.id) is True
+
+
+def test_revoking_removes_the_key_rather_than_storing_false(cm):
+    _set(ADMIN, SEAT.id, True)
+    _set(ADMIN, SEAT.id, False)
+
+    assert code_routes.RUN_CODE_PREFERENCE not in cm.get_user_preferences(SEAT.id)
+
+
+def test_the_gate_still_passes_admins_without_any_grant(cm):
+    """ARCH-177 must not have narrowed the admin arm of the SEC-151 gate."""
+    assert cm.has_code_run_grant(ADMIN.id) is False
+    assert code_routes._may_run_code(ADMIN.id) is True
+
+
+# ── the admin surface ──
+
+
+def test_both_edges_of_the_grant_are_audited(cm):
+    _set(ADMIN, SEAT.id, True)
+    _set(ADMIN, SEAT.id, False)
+
+    entries = [e for e in cm.get_audit_log() if e["action"].startswith("code_run_")]
+    assert [e["action"] for e in entries] == ["code_run_revoked", "code_run_granted"]
+    assert {e["actor_id"] for e in entries} == {ADMIN.id}
+    assert {e["target_id"] for e in entries} == {str(SEAT.id)}
+
+
+def test_the_user_list_reports_who_holds_the_grant(cm):
+    _set(ADMIN, SEAT.id, True)
+
+    rows = {r.user_id: r for r in asyncio.run(list_users(user=ADMIN))}
+
+    assert rows[SEAT.id].code_run is True
+    assert rows[OTHER.id].code_run is False
+    assert rows[ADMIN.id].is_admin is True
+    assert rows[ADMIN.id].code_run is False, "admins pass on their role, not a grant"
+
+
+def test_granting_to_an_admin_is_refused_as_a_no_op(cm):
+    with pytest.raises(HTTPException) as excinfo:
+        _set(ADMIN, ADMIN.id, True)
+
+    assert excinfo.value.status_code == 409
+    assert cm.has_code_run_grant(ADMIN.id) is False
+
+
+def test_granting_to_an_unknown_user_is_a_404(cm):
+    with pytest.raises(HTTPException) as excinfo:
+        _set(ADMIN, 9999, True)
+
+    assert excinfo.value.status_code == 404
+
+
+def test_setting_the_grant_to_what_it_already_is_writes_no_audit_entry(cm):
+    _set(ADMIN, SEAT.id, True)
+    _set(ADMIN, SEAT.id, True)
+
+    entries = [e for e in cm.get_audit_log() if e["action"].startswith("code_run_")]
+    assert len(entries) == 1

From 91d7596122b0ba15dd9965d01293ffdccd0c809d Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Fri, 14 Aug 2026 18:29:31 +0300
Subject: [PATCH 093/116] (fix) SEC-166: gateway container, wallet and network
 mutations are owner-only

SEC-153 decided TRADER was too weak to manage exchange credentials: they are
server configuration, not a trading action. The gateway routes still sat at
TRADER while doing strictly more damage, so the codebase asserted both rules
at once. This settles it in favour of SEC-153 and documents the rule on
_require_owner, which is now the single place it is written down:

  read a server -> TRADER
  trade on a server -> TRADER
  mutate its configuration or its infrastructure -> OWNER

Raised to OWNER, by class:

  container lifecycle (start/stop/restart/pull) - start takes the image and
  port of a container run on the owner's host; stop and restart cut DEX
  connectivity and drop in-flight orders for every bot on the server,
  including the owner's. A shared trader unwedging a container is a real
  scenario, but it is a recovery action, not a workflow, and the cost of
  asking the owner is far below the cost of a trader stopping the owner's
  gateway mid-run.

  wallets (add/remove/set-default) - the same keystore class as credentials.
  An imported key is usable by everyone on the server, removing one strands
  any bot signing from that address, and set-default silently redirects every
  subsequent DEX trade to another wallet.

  networks/{id} update - carries the RPC endpoint every transaction from this
  server is broadcast through; repointing it is a server-wide change.

Left at TRADER on purpose: every gateway read - status, logs, pull-status,
wallet and network listings. A trader must still see what they are trading
against and be able to tell the owner what is broken. An over-tight gate is
also a defect.

Blast radius, from config.yml: the 3 shared traders SEC-153 already affected -
one on `local`, two on `brigado_2`. They keep all trading and all gateway
visibility, and lose start/stop/restart/pull, wallet import/removal/default
switching, and network config edits on servers they do not own. Owners and
admins are unaffected.

Tests assert the refusal and the success separately per route class, and pin
that the reads stay at TRADER.
---
 condor/web/routes/settings.py        |  38 ++++
 tests/test_web_gateway_owner_only.py | 258 +++++++++++++++++++++++++++
 2 files changed, 296 insertions(+)
 create mode 100644 tests/test_web_gateway_owner_only.py

diff --git a/condor/web/routes/settings.py b/condor/web/routes/settings.py
index 270169a7..d996f561 100644
--- a/condor/web/routes/settings.py
+++ b/condor/web/routes/settings.py
@@ -31,6 +31,22 @@
 
 
 def _require_owner(cm, user_id: int, server_name: str):
+    """Enforce the OWNER line on top of the TRADER floor every route already has.
+
+    The rule this file draws (SEC-153, extended to the gateway by SEC-166):
+
+    * **Reading** a server's state — status, logs, wallet and network listings,
+      configured connectors — needs TRADER. A shared trader has to be able to
+      see what they are trading against, and to tell the owner when it is down.
+    * **Trading** on a server needs TRADER. That is what the share is for.
+    * **Mutating a server's configuration or its infrastructure** needs OWNER.
+      Exchange credentials, the gateway container lifecycle, the private keys
+      in its keystore and the RPC endpoints it dials are all the owner's
+      machine, not a trading action — and each of them can break the owner's
+      running bots for everyone else on the server.
+
+    Admins keep the bypass they hold everywhere else in this module.
+    """
     perm = cm.get_server_permission(user_id, server_name)
     if perm != ServerPermission.OWNER and not cm.is_admin(user_id):
         raise HTTPException(status_code=403, detail="Owner access required")
@@ -177,6 +193,9 @@ async def gateway_pull(
     user: WebUser = Depends(require_server_access_query),
 ):
     cm = get_config_manager()
+    # Pulling an image rewrites what code will run on the owner's host next
+    # restart — infrastructure, not trading.
+    _require_owner(cm, user.id, server)
     client = await _get_client(cm, server)
     try:
         # Parse "image:tag" format (e.g. "hummingbot/gateway:latest")
@@ -212,6 +231,9 @@ async def gateway_start(
     user: WebUser = Depends(require_server_access_query),
 ):
     cm = get_config_manager()
+    # The caller picks the image and port of a container started on the owner's
+    # host. That is the owner's decision, not a shared trader's.
+    _require_owner(cm, user.id, server)
     client = await _get_client(cm, server)
     try:
         result = await client.gateway.start(
@@ -232,6 +254,9 @@ async def gateway_stop(
     user: WebUser = Depends(require_server_access_query),
 ):
     cm = get_config_manager()
+    # Stopping the gateway cuts DEX connectivity for every bot on the server,
+    # including the owner's. Same line delete_credential draws.
+    _require_owner(cm, user.id, server)
     client = await _get_client(cm, server)
     try:
         result = await client.gateway.stop()
@@ -247,6 +272,8 @@ async def gateway_restart(
     user: WebUser = Depends(require_server_access_query),
 ):
     cm = get_config_manager()
+    # A restart drops in-flight DEX orders for everyone on the server.
+    _require_owner(cm, user.id, server)
     client = await _get_client(cm, server)
     try:
         result = await client.gateway.restart()
@@ -318,6 +345,9 @@ async def gateway_network_update(
     user: WebUser = Depends(require_server_access_query),
 ):
     cm = get_config_manager()
+    # Network config carries the RPC endpoint every transaction from this server
+    # is signed and broadcast through — repointing it is a server-wide change.
+    _require_owner(cm, user.id, server)
     client = await _get_client(cm, server)
     try:
         result = await client.gateway.update_network_config(network_id, req.config)
@@ -369,6 +399,9 @@ async def gateway_wallet_add(
     user: WebUser = Depends(require_server_access_query),
 ):
     cm = get_config_manager()
+    # Importing a private key into the owner's gateway makes that key usable by
+    # everyone on the server. Whose keys live on the host is the owner's call.
+    _require_owner(cm, user.id, server)
     client = await _get_client(cm, server)
     # Gateway's add-wallet always promotes the new key to the chain default, so when the user
     # opted out we capture the existing default first and restore it after the import.
@@ -418,6 +451,9 @@ async def gateway_wallet_set_default(
     user: WebUser = Depends(require_server_access_query),
 ):
     cm = get_config_manager()
+    # The default wallet is the one every subsequent DEX trade signs with, so
+    # switching it silently redirects the owner's flow to another address.
+    _require_owner(cm, user.id, server)
     client = await _get_client(cm, server)
     try:
         result = await client.accounts.set_default_gateway_wallet(
@@ -444,6 +480,8 @@ async def gateway_wallet_remove(
     user: WebUser = Depends(require_server_access_query),
 ):
     cm = get_config_manager()
+    # Removing a key strands any bot trading from that address — owner only.
+    _require_owner(cm, user.id, server)
     client = await _get_client(cm, server)
     try:
         result = await client.accounts.remove_gateway_wallet(
diff --git a/tests/test_web_gateway_owner_only.py b/tests/test_web_gateway_owner_only.py
new file mode 100644
index 00000000..6b18d7c0
--- /dev/null
+++ b/tests/test_web_gateway_owner_only.py
@@ -0,0 +1,258 @@
+"""Gateway container, wallet and network mutations are owner-only (SEC-166).
+
+SEC-153 drew the line for exchange credentials: mutating a server's
+*configuration* is not a trading action, so it needs OWNER. The gateway routes
+sat at TRADER, which asserted the opposite for changes that are at least as
+consequential — a shared trader could stop the container every bot on the
+server trades DEX through, import or delete private keys in the owner's
+keystore, silently repoint the default signing wallet, or rewrite the RPC
+endpoint every transaction is broadcast to.
+
+These tests pin the three route classes separately, and pin the reads that
+deliberately *stay* at TRADER: a trader must still be able to see whether the
+gateway is up and which wallets exist, otherwise they cannot even tell the
+owner what is broken.
+"""
+
+import pytest
+from fastapi import FastAPI
+from starlette.testclient import TestClient
+
+import condor.web.routes.settings as settings_routes
+from condor.web.auth import get_current_user
+from condor.web.models import WebUser
+from config_manager import ServerPermission
+
+SERVER = "alpha"
+OWNER = WebUser(id=1, username="owner", first_name="O", role="user")
+TRADER = WebUser(id=2, username="trader", first_name="T", role="user")
+ADMIN = WebUser(id=3, username="admin", first_name="A", role="admin")
+
+CHAIN = "solana"
+ADDRESS = "So11111111111111111111111111111111111111112"
+
+
+class FakeGateway:
+    def __init__(self):
+        self.calls = []
+
+    async def start(self, cfg):
+        self.calls.append(("start", cfg))
+        return {"ok": True}
+
+    async def stop(self):
+        self.calls.append(("stop", None))
+        return {"ok": True}
+
+    async def restart(self):
+        self.calls.append(("restart", None))
+        return {"ok": True}
+
+    async def update_network_config(self, network_id, config):
+        self.calls.append(("update_network", network_id, config))
+        return {"ok": True}
+
+
+class FakeDocker:
+    def __init__(self):
+        self.pulled = []
+
+    async def pull_image(self, image_name, tag):
+        self.pulled.append((image_name, tag))
+        return {"ok": True}
+
+
+class FakeAccounts:
+    def __init__(self):
+        self.calls = []
+
+    async def list_gateway_wallets(self):
+        return [{"chain": CHAIN, "default_address": ADDRESS, "wallets": [ADDRESS]}]
+
+    async def add_gateway_wallet(self, chain, private_key):
+        self.calls.append(("add", chain))
+        return {"address": ADDRESS}
+
+    async def set_default_gateway_wallet(self, chain, address):
+        self.calls.append(("set_default", chain, address))
+        return {"ok": True}
+
+    async def remove_gateway_wallet(self, chain, address):
+        self.calls.append(("remove", chain, address))
+        return {"ok": True}
+
+
+class FakeClient:
+    def __init__(self):
+        self.gateway = FakeGateway()
+        self.docker = FakeDocker()
+        self.accounts = FakeAccounts()
+
+
+class FakeConfigManager:
+    """Owner id 1, trader id 2 shared, admin id 3 with no grant on the server."""
+
+    def __init__(self, client):
+        self._client = client
+
+    def get_server_permission(self, user_id, server_name):
+        if server_name != SERVER:
+            return None
+        if user_id == OWNER.id:
+            return ServerPermission.OWNER
+        if user_id == TRADER.id:
+            return ServerPermission.TRADER
+        return None
+
+    def has_server_access(self, user_id, server_name, min_permission=None):
+        # Admins reach every server, mirroring the real manager.
+        if self.is_admin(user_id):
+            return server_name == SERVER
+        return self.get_server_permission(user_id, server_name) is not None
+
+    def is_admin(self, user_id):
+        return user_id == ADMIN.id
+
+    async def get_client(self, server_name):
+        return self._client
+
+
+@pytest.fixture
+def env(monkeypatch):
+    client = FakeClient()
+    cm = FakeConfigManager(client)
+    monkeypatch.setattr(settings_routes, "get_config_manager", lambda: cm)
+    monkeypatch.setattr("condor.web.auth.get_config_manager", lambda: cm)
+    app = FastAPI()
+    app.include_router(settings_routes.router)
+    return app, client
+
+
+def as_user(app, user):
+    app.dependency_overrides[get_current_user] = lambda: user
+    return TestClient(app)
+
+
+P = {"server": SERVER}
+
+
+# ── The mutating calls, one per route, grouped by class ──
+
+LIFECYCLE = {
+    "pull": lambda http: http.post(
+        "/settings/gateway/pull", params=P, json={"image": "hummingbot/gateway:latest"}
+    ),
+    "start": lambda http: http.post(
+        "/settings/gateway/start",
+        params=P,
+        json={"image": "hummingbot/gateway:latest", "port": 15888},
+    ),
+    "stop": lambda http: http.post("/settings/gateway/stop", params=P),
+    "restart": lambda http: http.post("/settings/gateway/restart", params=P),
+}
+
+WALLETS = {
+    "add": lambda http: http.post(
+        "/settings/gateway/wallets",
+        params=P,
+        json={"chain": CHAIN, "private_key": "s3cret", "set_default": True},
+    ),
+    "set_default": lambda http: http.post(
+        "/settings/gateway/wallets/default",
+        params=P,
+        json={"chain": CHAIN, "address": ADDRESS},
+    ),
+    "remove": lambda http: http.delete(
+        f"/settings/gateway/wallets/{CHAIN}/{ADDRESS}", params=P
+    ),
+}
+
+NETWORKS = {
+    "update": lambda http: http.post(
+        "/settings/gateway/networks/mainnet-beta",
+        params=P,
+        json={"config": {"nodeURL": "https://evil.example/rpc"}},
+    ),
+}
+
+ALL_MUTATIONS = {**LIFECYCLE, **WALLETS, **NETWORKS}
+
+
+@pytest.mark.parametrize("name", sorted(LIFECYCLE))
+def test_trader_cannot_touch_gateway_lifecycle(env, name):
+    """start/stop/restart/pull run containers on the owner's host."""
+    app, client = env
+    resp = LIFECYCLE[name](as_user(app, TRADER))
+    assert resp.status_code == 403
+    assert resp.json()["detail"] == "Owner access required"
+    # Refused before the backend was reached.
+    assert client.gateway.calls == []
+    assert client.docker.pulled == []
+
+
+@pytest.mark.parametrize("name", sorted(WALLETS))
+def test_trader_cannot_mutate_gateway_wallets(env, name):
+    """add/remove/set-default all touch the owner's keystore."""
+    app, client = env
+    resp = WALLETS[name](as_user(app, TRADER))
+    assert resp.status_code == 403
+    assert resp.json()["detail"] == "Owner access required"
+    assert client.accounts.calls == []
+
+
+@pytest.mark.parametrize("name", sorted(NETWORKS))
+def test_trader_cannot_rewrite_network_config(env, name):
+    """The RPC endpoint every transaction is broadcast through is config."""
+    app, client = env
+    resp = NETWORKS[name](as_user(app, TRADER))
+    assert resp.status_code == 403
+    assert resp.json()["detail"] == "Owner access required"
+    assert client.gateway.calls == []
+
+
+@pytest.mark.parametrize("name", sorted(ALL_MUTATIONS))
+def test_owner_can_perform_every_gateway_mutation(env, name):
+    """The gate must not lock the owner out of their own infrastructure."""
+    app, _ = env
+    assert ALL_MUTATIONS[name](as_user(app, OWNER)).status_code == 200
+
+
+@pytest.mark.parametrize("name", sorted(ALL_MUTATIONS))
+def test_admin_keeps_the_owner_bypass(env, name):
+    """`_require_owner` lets admins through everywhere else in this module."""
+    app, _ = env
+    assert ALL_MUTATIONS[name](as_user(app, ADMIN)).status_code == 200
+
+
+def test_owner_mutations_actually_reach_the_backend(env):
+    """Guard against a gate that 200s without doing the work."""
+    app, client = env
+    http = as_user(app, OWNER)
+    for call in ALL_MUTATIONS.values():
+        assert call(http).status_code == 200
+
+    assert client.docker.pulled == [("hummingbot/gateway", "latest")]
+    kinds = [c[0] for c in client.gateway.calls]
+    assert kinds == ["start", "stop", "restart", "update_network"]
+    assert ("add", CHAIN) in client.accounts.calls
+    assert ("remove", CHAIN, ADDRESS) in client.accounts.calls
+
+
+# ── Reads stay at TRADER on purpose ──
+
+
+def test_trader_can_still_read_gateway_state(env):
+    """A trader keeps the visibility they need to trade and to report breakage."""
+    app, client = env
+    http = as_user(app, TRADER)
+
+    async def get_pull_status():
+        return {"status": "idle"}
+
+    client.docker.get_pull_status = get_pull_status
+
+    assert http.get("/settings/gateway/pull-status", params=P).status_code == 200
+
+    wallets = http.get("/settings/gateway/wallets", params=P)
+    assert wallets.status_code == 200
+    assert wallets.json()["wallets"][0]["chain"] == CHAIN

From 515534a58f00d2f208d2a7aab687b4988c414eb7 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Fri, 14 Aug 2026 18:38:01 +0300
Subject: [PATCH 094/116] (fix) SEC-164: strategy start resolves servers for
 its subject, not for a chat
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two vectors survived the SEC-149 start gate, both because the gate can only
check a server name the request actually carries.

`TickEngine._resolve_server` fell through to `get_effective_server(self.chat_id)`
when no server name was configured. `chat_id` arrives in the start body, so
naming a chat you do not own handed the run *that* chat's default server, with
no name ever reaching the route to be checked. The fix is not another check on
top: the caller-supplied identity is gone from server resolution entirely. Every
candidate is now keyed on `user_id`, the run's authenticated subject — the same
move SEC-167 made in `_respawn`, naming the caller instead of the stored owner.
The user's own default still applies, because that default is keyed by user id
on both surfaces: the web writes it with `set_chat_default_server(user.id, ...)`
and a private Telegram chat has chat id == user id.

`_get_client`'s `get_bots_client(self.chat_id)` fallback went with it. It is the
same vector one step further down: that helper ignores the chat id for server
selection and, with no `user_data` to scope it, returns the first *globally*
enabled server — precisely the servers `_resolve_server` had just declined to
hand over. A run whose subject can reach no server now gets no client, which
every caller of `_get_client` already handles.

The second vector was a name matching nothing. `has_server_access` answers True
for an admin on any string, so an unknown name cleared the gate and pinned the
loop to a name nothing backed — and the loop outlives the check, so whatever got
created under that name later became its server. The route now refuses a
body-supplied name that resolves to nothing, and `_resolve_server` re-verifies
existence and access at every resolution, which is what actually closes the
window for an *inherited* name like the `local` AgentConfig fills in. Refusing
that one at the route was never an option: it is the exact case the
accessible-servers fallback exists to serve, and it still falls through.

Refusal order is deliberate. The access check runs first, so a caller with no
access gets the same `No access` whether the server exists or not, matching how
`routes/servers.py` and `routes/settings.py` keep the two indistinguishable.
Only someone who already cleared access learns the name matched nothing.

Ten regression tests pin both vectors; seven fail against the previous code.
---
 condor/agents/engine.py                    |  53 +++-
 condor/web/routes/agents.py                |  10 +
 tests/test_agent_start_residual_vectors.py | 285 +++++++++++++++++++++
 3 files changed, 339 insertions(+), 9 deletions(-)
 create mode 100644 tests/test_agent_start_residual_vectors.py

diff --git a/condor/agents/engine.py b/condor/agents/engine.py
index a9c0d605..5be52479 100644
--- a/condor/agents/engine.py
+++ b/condor/agents/engine.py
@@ -942,15 +942,42 @@ def _agent_key(self) -> str:
         )
 
     def _resolve_server(self) -> tuple[str | None, dict | None]:
-        """Resolve the server for this agent."""
+        """Resolve the server for this run, keyed on ``user_id`` (SEC-164).
+
+        Every candidate — the configured name, the subject's own default, the
+        accessible list — is held to the same bar here: the server must exist
+        *and* ``user_id`` must be able to reach it. Two properties fall out of
+        checking it at resolution rather than only at start:
+
+        * the run never inherits identity it was handed. ``chat_id`` arrives
+          from the request body, so resolving through ``get_effective_server``
+          on *it* let a caller name a chat they do not own and pick up that
+          chat's default server, with no server name for the start gate
+          (SEC-149) to check. The subject's own default is keyed by user id
+          anyway, both on the web (``set_chat_default_server(user.id, ...)``)
+          and in a private Telegram chat, where chat id == user id.
+        * a name that matched nothing at start stays unusable. The loop is
+          long-running, so a configured ``server_name`` that resolved to
+          nothing — the ``"local"`` ``AgentConfig`` fills in, typically — must
+          not silently bind to whatever another user creates under that name
+          later.
+
+        Falls back to the subject's accessible servers, as before, so a run
+        with no server configured still works.
+        """
         from config_manager import get_config_manager, get_effective_server
 
         cm = get_config_manager()
-        server_name = self.config.get("server_name")
 
-        if not server_name:
-            server_name = get_effective_server(self.chat_id)
-        if not server_name:
+        def usable(name: str | None) -> bool:
+            return bool(name and cm.get_server(name)) and cm.has_server_access(
+                self.user_id, name
+            )
+
+        server_name = self.config.get("server_name")
+        if not usable(server_name):
+            server_name = get_effective_server(self.user_id)
+        if not usable(server_name):
             accessible = cm.get_accessible_servers(self.user_id)
             server_name = accessible[0] if accessible else None
         if not server_name:
@@ -964,10 +991,18 @@ async def _get_client(self):
         try:
             server_name, server = self._resolve_server()
             if not server:
-                from handlers.bots._shared import get_bots_client
-
-                client, _ = await get_bots_client(self.chat_id)
-                return client
+                # Nothing to fall back to: ``_resolve_server`` already tried
+                # every server this run's subject may use, so the only servers
+                # left are other people's. ``get_bots_client(self.chat_id)``
+                # used to stand here — it ignores the chat id for server
+                # selection and, with no ``user_data`` to scope it, picks the
+                # first *globally* enabled server instead (SEC-164).
+                log.warning(
+                    "Agent %s: no accessible server for user %s, no API client",
+                    self.agent_id,
+                    self.user_id,
+                )
+                return None
 
             from config_manager import get_config_manager
 
diff --git a/condor/web/routes/agents.py b/condor/web/routes/agents.py
index f7dbbbce..66753b4e 100644
--- a/condor/web/routes/agents.py
+++ b/condor/web/routes/agents.py
@@ -1752,6 +1752,16 @@ async def _start(agent, strategy, req: StartStrategyRequest, user_id: int) -> di
     asked_for_it = bool(req.config and req.config.get("server_name"))
     if server_name and (asked_for_it or cm.get_server(server_name)):
         check_server_access(user_id, server_name)
+        # A name the body asked for must also name something. An unknown one
+        # used to be waved through on the reasoning that it borrows no
+        # credentials, but ``has_server_access`` answers True for an admin on
+        # any string, and the loop it starts outlives the check: the engine
+        # would bind to whatever gets created under that name later (SEC-164).
+        # Refused only *after* the access check, so a caller with no access
+        # still gets the same "No access" a real server gives them and this
+        # route never reveals which names exist.
+        if not cm.get_server(server_name):
+            raise HTTPException(status_code=404, detail="Server not found")
 
     if req.trading_context:
         config_dict["trading_context"] = req.trading_context
diff --git a/tests/test_agent_start_residual_vectors.py b/tests/test_agent_start_residual_vectors.py
new file mode 100644
index 00000000..3514afe1
--- /dev/null
+++ b/tests/test_agent_start_residual_vectors.py
@@ -0,0 +1,285 @@
+"""The two vectors SEC-149 left behind on agent strategy start (SEC-164).
+
+SEC-149 gated ``POST /agents/{slug}/strategies/{sslug}/start`` on
+``has_server_access`` for the server the request names. Two ways to reach a
+server that name never covers:
+
+1. **A caller-supplied ``chat_id``.** With no usable ``server_name``,
+   ``TickEngine._resolve_server`` fell through to
+   ``get_effective_server(self.chat_id)``. ``chat_id`` comes straight from the
+   request body, so naming a chat you do not own handed you *that* chat's
+   default server — and since no server name ever reached the route, the gate
+   had nothing to check. The subject of the resolution is now ``user_id``, the
+   run's authenticated principal, exactly as SEC-167 made respawn name the
+   caller instead of the session's stored owner.
+
+2. **A name that matches nothing.** The gate checked a body-supplied name and
+   let it through, but ``has_server_access`` answers True for an admin on any
+   string, so an unknown name started a loop with a server name pinned that
+   nothing backed yet — and the loop outlives the check. The route now refuses
+   it, and the engine re-checks at every resolution, so a server created later
+   under that name is not adopted either.
+
+The refusal order matters: the access check runs first, so a caller with no
+access gets the same ``No access`` whether or not the server exists. Only
+someone who already cleared access learns the name matched nothing.
+"""
+
+import asyncio
+
+import pytest
+from fastapi import FastAPI
+from starlette.testclient import TestClient
+
+from condor.agents import agent as agent_module
+from condor.agents import engine as engine_module
+from condor.agents import strategy as strategy_module
+from condor.agents.agent import AgentStore
+from condor.agents.engine import TickEngine
+from condor.agents.strategy import StrategyStore
+from condor.web.auth import get_current_user
+from condor.web.models import WebUser
+from condor.web.routes import agents as routes
+
+USER = WebUser(id=555, username="u", first_name="U", role="user")
+ADMIN = WebUser(id=1, username="a", first_name="A", role="admin")
+STRANGER_ID = 777
+
+MINE = "mine-prod"
+MINE_ALT = "mine-alt"
+THEIRS = "someone-else"
+UNKNOWN = "not-a-server-yet"
+
+# Every server that exists. ``UNKNOWN`` deliberately is not one of them.
+SERVERS = {MINE, MINE_ALT, THEIRS}
+
+# The chat whose default server the attacker is trying to inherit. Its owner is
+# not USER, which is the whole point.
+VICTIM_CHAT = -100200300
+
+
+class FakeConfigManager:
+    """Mirrors the real access semantics that make both vectors reachable.
+
+    ``has_server_access`` answers True for an admin on *any* name, existing or
+    not (``get_server_permission`` returns OWNER for admins before it ever
+    looks the server up) — that is what let an unknown name through the gate.
+    """
+
+    # Read by the real ``get_effective_server``, which is what resolves a
+    # chat's default server.
+    _data = {
+        "chat_defaults": {VICTIM_CHAT: THEIRS, USER.id: MINE_ALT},
+        "servers": {name: {"name": name} for name in SERVERS},
+    }
+
+    def is_admin(self, user_id):
+        return user_id == ADMIN.id
+
+    def get_server(self, server_name):
+        return {"name": server_name} if server_name in SERVERS else None
+
+    def has_server_access(self, user_id, server_name, *a, **k):
+        if user_id == ADMIN.id:
+            return True
+        return user_id == USER.id and server_name in (MINE, MINE_ALT)
+
+    def get_accessible_servers(self, user_id):
+        if user_id == ADMIN.id:
+            return sorted(SERVERS)
+        # Ordered so that ``accessible[0]`` is *not* the user's own default:
+        # a test asserting MINE_ALT then proves the preference survived.
+        return [MINE, MINE_ALT] if user_id == USER.id else []
+
+
+@pytest.fixture
+def cm(monkeypatch):
+    monkeypatch.setattr(
+        "config_manager.get_config_manager", lambda: FakeConfigManager()
+    )
+    monkeypatch.setattr(
+        "condor.web.auth.get_config_manager", lambda: FakeConfigManager()
+    )
+    return FakeConfigManager()
+
+
+# ----------------------------------------------------------------------
+# Vector 1: the engine resolves servers for its subject, never for a chat
+# ----------------------------------------------------------------------
+
+
+class StubEngine:
+    """The two real methods under test, without ``TickEngine.__post_init__``."""
+
+    _resolve_server = TickEngine._resolve_server
+    _get_client = TickEngine._get_client
+
+    def __init__(self, *, config=None, chat_id=0, user_id=USER.id):
+        self.config = config or {}
+        self.chat_id = chat_id
+        self.user_id = user_id
+        self.agent_id = "brigado.scalp_1"
+
+
+def test_a_foreign_chat_id_does_not_inherit_that_chats_default_server(cm):
+    """The body picks the chat; it must not get to pick the credentials.
+
+    Before SEC-164 this returned ``THEIRS`` — the victim chat's default —
+    without the start gate ever seeing a server name to check.
+    """
+    name, server = StubEngine(chat_id=VICTIM_CHAT)._resolve_server()
+
+    assert name != THEIRS, "a supplied chat_id must not license its server"
+    assert name == MINE_ALT, "the subject's own default is what counts"
+    assert server == {"name": MINE_ALT}
+
+
+def test_the_subjects_own_default_server_is_still_honoured(cm):
+    """Dropping chat_id must not flatten everyone onto ``accessible[0]``."""
+    name, _ = StubEngine(chat_id=0)._resolve_server()
+
+    assert name == MINE_ALT
+
+
+def test_a_subject_with_no_default_still_falls_back_to_accessible_servers(cm):
+    """The fallback SEC-149 was careful to preserve keeps working."""
+    fake = FakeConfigManager()
+    fake._data = {"chat_defaults": {}, "servers": FakeConfigManager._data["servers"]}
+    with pytest.MonkeyPatch.context() as mp:
+        mp.setattr("config_manager.get_config_manager", lambda: fake)
+        name, _ = StubEngine(config={"server_name": "local"})._resolve_server()
+
+    assert name == MINE
+
+
+def test_a_configured_server_the_subject_cannot_reach_is_dropped(cm):
+    """The engine no longer trusts ``config['server_name']`` on its own."""
+    name, _ = StubEngine(config={"server_name": THEIRS})._resolve_server()
+
+    assert name == MINE_ALT
+
+
+def test_a_server_created_later_under_the_configured_name_is_not_adopted(cm):
+    """Vector 2, engine side: the check runs at resolution, not only at start.
+
+    ``local`` named nothing when the loop started; here it exists and belongs
+    to someone else. The already-running strategy must not pick it up.
+    """
+    servers = dict(FakeConfigManager._data["servers"])
+    servers["local"] = {"name": "local"}
+    fake = FakeConfigManager()
+    fake._data = {"chat_defaults": {}, "servers": servers}
+    fake.get_server = lambda n: servers.get(n)
+
+    with pytest.MonkeyPatch.context() as mp:
+        mp.setattr("config_manager.get_config_manager", lambda: fake)
+        name, _ = StubEngine(config={"server_name": "local"})._resolve_server()
+
+    assert name != "local", "a foreign server appearing later is not inherited"
+    assert name == MINE
+
+
+def test_a_subject_with_no_accessible_server_gets_no_client_at_all(cm, monkeypatch):
+    """Not the first globally enabled one.
+
+    ``_get_client`` used to fall back to ``get_bots_client(self.chat_id)``,
+    which ignores the chat id for server selection and, with no ``user_data``
+    to scope it, hands back the first enabled server in the config.
+    """
+    called = []
+
+    async def _spy(chat_id=None, user_data=None):
+        called.append(chat_id)
+        return object(), THEIRS
+
+    monkeypatch.setattr("handlers.bots._shared.get_bots_client", _spy)
+
+    engine = StubEngine(chat_id=VICTIM_CHAT, user_id=STRANGER_ID)
+
+    assert engine._resolve_server() == (None, None)
+    assert asyncio.run(engine._get_client()) is None
+    assert called == [], "no chat-keyed client fallback may run"
+
+
+# ----------------------------------------------------------------------
+# Vector 2: the start gate refuses a name that matches nothing
+# ----------------------------------------------------------------------
+
+
+class FakeEngine:
+    """Stands in for TickEngine: records every spawn, never touches the network."""
+
+    spawned: list[dict] = []
+
+    def __init__(self, agent, strategy, config, chat_id, user_id):
+        self.config = config
+        self.agent_id = "agent-1"
+        self.session_num = 1
+        FakeEngine.spawned.append(config)
+
+    async def start(self):
+        return None
+
+
+@pytest.fixture
+def env(tmp_path, monkeypatch, cm):
+    monkeypatch.setattr(agent_module, "_DATA_ROOT", tmp_path)
+    monkeypatch.setattr(strategy_module, "_DATA_ROOT", tmp_path)
+    monkeypatch.setattr(engine_module, "TickEngine", FakeEngine)
+    FakeEngine.spawned = []
+    AgentStore().create(name="Brigado", description="BRL market making")
+    StrategyStore().create(agent_slug="brigado", name="Scalp")
+    return tmp_path
+
+
+def _client(user: WebUser) -> TestClient:
+    app = FastAPI()
+    app.include_router(routes.router)
+    app.dependency_overrides[get_current_user] = lambda: user
+    return TestClient(app)
+
+
+def _start(user: WebUser, **config):
+    return _client(user).post(
+        "/agents/brigado/strategies/scalp/start",
+        json={"config": config} if config else {},
+    )
+
+
+def test_an_unknown_server_name_is_refused(env):
+    """An admin clears the access check on any string; existence still must hold."""
+    res = _start(ADMIN, server_name=UNKNOWN)
+
+    assert res.status_code == 404
+    assert res.json()["detail"] == "Server not found"
+    assert FakeEngine.spawned == [], "no loop starts pinned to a name nothing backs"
+
+
+def test_the_refusal_tells_a_stranger_nothing_about_which_names_exist(env):
+    """Same 403 for a real foreign server and for a name that matches nothing."""
+    unknown = _start(USER, server_name=UNKNOWN)
+    foreign = _start(USER, server_name=THEIRS)
+
+    assert unknown.status_code == foreign.status_code == 403
+    assert unknown.json()["detail"] == foreign.json()["detail"] == "No access"
+    assert FakeEngine.spawned == []
+
+
+def test_an_inherited_name_that_matches_nothing_still_falls_through(env):
+    """The ``local`` AgentConfig fills in is not a request to use ``local``.
+
+    Only a name the *body* asked for is held to existence; the inherited
+    default keeps the accessible-servers fallback SEC-149 preserved.
+    """
+    res = _start(ADMIN)
+
+    assert res.status_code == 200
+    assert len(FakeEngine.spawned) == 1
+
+
+def test_starting_on_a_server_the_caller_owns_still_works(env):
+    """Sanity: the gate is not simply refusing everyone."""
+    res = _start(USER, server_name=MINE)
+
+    assert res.status_code == 200
+    assert [c["server_name"] for c in FakeEngine.spawned] == [MINE]

From 99c426ca48f534758d964db8c8e7b4cc35020033 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Fri, 14 Aug 2026 19:04:13 +0300
Subject: [PATCH 095/116] (fix) CORR-181: a missing trade timestamp charts
 nothing, like a null one
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`_walk_trades` read the timestamp with `trade.get("timestamp", 0)`, so a row
with no `timestamp` key became `0`, and `parse_timestamp(0)` returned
`datetime.fromtimestamp(0)` — 1970-01-01, truthy, so the `if ts:` guard let it
through and charted a cumulative-PnL point at the Unix epoch. A row carrying an
explicit `timestamp: None` parsed to `None` and was skipped. Two equivalent
absences, two different chart outputs.

The series has four consumers (two plotly scatters in
`handlers/bots/archived_chart.py`, the web route, the archived analyzer
routine), and one 1970 point beside 2026 ones stretches the x-axis over 56
years and squashes the real curve into a vertical line at the right edge. The
money totals stay correct throughout, so nothing else signals the problem.

Dropping the default is the whole fix: `parse_timestamp` already short-circuits
`None` on its first branch and the existing guard already skips it. This is the
rule the file had already adopted for ordering — `_timestamp_sort_key`
(CORR-171) reads `trade.get("timestamp")` with no default and documents that a
null sorts like a missing one. Sorting was unified; the charted value was left
behind.

Running totals are unaffected: `running_pnl`, `total_fees` and `total_volume`
accumulate before the charting guard, so an undated trade still moves the curve
and the next dated point carries its contribution. Sort order is unchanged.

The characterization suite pinned the old behaviour as a wart, so its contract
moves deliberately: `_expected_timestamps` loses the same `0` default, the
`nil_missing_fields` golden series goes from three epoch points to empty, and
`nil_null_missing_and_epoch` keeps only its dated point — with `total_pnl`
99.8, `total_fees` 0.4, `total_volume` 940.0 and `pnl_by_pair` byte-identical.
No other scenario's golden changed.
---
 condor/archived_pnl.py                      |  2 +-
 tests/test_archived_pnl_characterization.py | 15 ++++++---------
 2 files changed, 7 insertions(+), 10 deletions(-)

diff --git a/condor/archived_pnl.py b/condor/archived_pnl.py
index f356d1a4..f679a5f3 100644
--- a/condor/archived_pnl.py
+++ b/condor/archived_pnl.py
@@ -324,7 +324,7 @@ def _walk_trades(trades: list[dict[str, Any]], accounting) -> dict[str, Any]:
             trade_type=trade.get("trade_type", "").upper(),  # BUY or SELL
             position=trade.get("position", "").upper(),  # OPEN, CLOSE or NIL
             fee=float(trade.get("trade_fee_in_quote", 0)),
-            timestamp=trade.get("timestamp", 0),
+            timestamp=trade.get("timestamp"),
         )
 
         total_fees += parsed.fee
diff --git a/tests/test_archived_pnl_characterization.py b/tests/test_archived_pnl_characterization.py
index bb91229e..dd45b3ab 100644
--- a/tests/test_archived_pnl_characterization.py
+++ b/tests/test_archived_pnl_characterization.py
@@ -272,11 +272,9 @@ def _trade(ts, pair, side, position, price, amount, fee):
         "total_fees": 0.0,
         "total_volume": 0.0,
         "pnl_by_pair": {},
-        "cumulative": [
-            (0.0, "Unknown"),
-            (0.0, "Unknown"),
-            (0.0, "Unknown"),
-        ],
+        # CORR-181: a missing timestamp is an absent one, like an explicit
+        # null - it charts nothing instead of a point at the Unix epoch
+        "cumulative": [],
     },
     "nil_none_timestamp": {
         "total_pnl": 0.0,
@@ -329,10 +327,9 @@ def _trade(ts, pair, side, position, price, amount, fee):
         "pnl_by_pair": {
             "SOL-USDC": 99.8,
         },
-        # the null-timestamp BUY charts no point (same as nil_none_timestamp);
-        # the missing-timestamp one still charts at epoch 0
+        # CORR-181: neither the null-timestamp BUY nor the missing-timestamp
+        # one charts a point; their PnL is carried by the next dated trade
         "cumulative": [
-            (0.0, "SOL-USDC"),
             (99.8, "SOL-USDC"),
         ],
     },
@@ -452,7 +449,7 @@ def _trade(ts, pair, side, position, price, amount, fee):
 def _expected_timestamps(trades):
     """Timestamps the cumulative series must carry, derived independently."""
     stamps = [
-        parse_timestamp(t.get("timestamp", 0))
+        parse_timestamp(t.get("timestamp"))
         for t in sorted(trades, key=_timestamp_sort_key)
     ]
     return [ts for ts in stamps if ts]

From 5e1d845b0481e7bff8b9707ec53473607328c7a8 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Fri, 14 Aug 2026 19:08:36 +0300
Subject: [PATCH 096/116] (fix) SEC-179: stop offering owner-only gateway
 mutations to traders
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

SEC-166 raised container pull/start/stop/restart, network config update and
the three wallet mutations from TRADER to OWNER, but the dashboard kept
offering them. SEC-176 had already built the mechanism (useServerPermission +
OWNER_ONLY_HINT) and deferred the gateway controls on a premise that stopped
being true thirteen minutes later.

Wire the hook into GatewaySettings (component-level for start/stop/restart and
both pulls, and in NetworkConfigEditor for Save, asking about its `server`
prop rather than the selected one) and apply the existing isOwner already in
scope in ApiKeysSettings to Add Wallet, the set-default star and Remove wallet.

Also give defaultWalletMut, deleteWalletMut, stopMut and restartMut the error
branch they never had: a refusal that outruns the disabled state now renders
the API's detail instead of a silent no-op.

Enforcement does not move — `_require_owner` stays the only gate, and unknown
permission still degrades to allowed, so a slow server list behaves as before.
---
 .../components/settings/ApiKeysSettings.tsx   | 37 ++++++++++----
 .../components/settings/GatewaySettings.tsx   | 51 ++++++++++++++-----
 2 files changed, 64 insertions(+), 24 deletions(-)

diff --git a/frontend/src/components/settings/ApiKeysSettings.tsx b/frontend/src/components/settings/ApiKeysSettings.tsx
index b69fb06b..0a03ad07 100644
--- a/frontend/src/components/settings/ApiKeysSettings.tsx
+++ b/frontend/src/components/settings/ApiKeysSettings.tsx
@@ -74,10 +74,11 @@ function isCredentialField(key: string, type?: string): boolean {
 
 export function ApiKeysSettings() {
   const { server } = useServer();
-  // Credential add/delete is owner-only on the backend (SEC-153). Reading the
-  // level here does not enforce anything — the API still answers 403 — it just
-  // stops the UI from offering a trader an action that is going to be refused.
-  // Gateway wallet controls stay open: those routes are not owner-gated.
+  // Credential add/delete is owner-only on the backend (SEC-153), and so are the
+  // Gateway wallet mutations — add, set-default and remove all call `_require_owner`
+  // since SEC-166. Reading the level here does not enforce anything — the API still
+  // answers 403 — it just stops the UI from offering a trader an action that is
+  // going to be refused.
   const { isOwner } = useServerPermission();
   const qc = useQueryClient();
   const [flow, setFlow] = useState<AddFlowState>(INITIAL_FLOW);
@@ -503,9 +504,13 @@ export function ApiKeysSettings() {
             onClick={() =>
               setFlow({ ...INITIAL_FLOW, step: "import-wallet", walletChain: "solana" })
             }
-            disabled={!gatewayRunning}
+            disabled={!gatewayRunning || !isOwner}
             title={
-              gatewayRunning ? undefined : "Gateway is not running — start it from the Gateway tab."
+              !isOwner
+                ? OWNER_ONLY_HINT
+                : gatewayRunning
+                  ? undefined
+                  : "Gateway is not running — start it from the Gateway tab."
             }
             className="flex items-center gap-1.5 rounded-md border border-[var(--color-border)] bg-[var(--color-surface)] px-3 py-1.5 text-xs font-medium text-[var(--color-text)] transition-colors hover:border-[var(--color-border-hover)] hover:bg-[var(--color-surface-hover)] disabled:cursor-not-allowed disabled:opacity-50 disabled:hover:border-[var(--color-border)] disabled:hover:bg-[var(--color-surface)]"
           >
@@ -650,9 +655,9 @@ export function ApiKeysSettings() {
                         onClick={() =>
                           defaultWalletMut.mutate({ chain: w.chain, address: w.address })
                         }
-                        disabled={defaultWalletMut.isPending}
-                        className="rounded p-1.5 text-[var(--color-text-muted)] hover:bg-[var(--color-surface-hover)] hover:text-[var(--color-primary)] disabled:opacity-50"
-                        title="Set as default wallet for this chain"
+                        disabled={defaultWalletMut.isPending || !isOwner}
+                        className="rounded p-1.5 text-[var(--color-text-muted)] hover:bg-[var(--color-surface-hover)] hover:text-[var(--color-primary)] disabled:cursor-not-allowed disabled:opacity-50"
+                        title={isOwner ? "Set as default wallet for this chain" : OWNER_ONLY_HINT}
                       >
                         <Star className="h-3.5 w-3.5" />
                       </button>
@@ -681,8 +686,9 @@ export function ApiKeysSettings() {
                     ) : (
                       <button
                         onClick={() => setConfirmDeleteWallet(walletKey)}
-                        className="rounded p-1.5 text-[var(--color-text-muted)] hover:bg-[var(--color-surface-hover)] hover:text-[var(--color-red)]"
-                        title="Remove wallet from Gateway"
+                        disabled={!isOwner}
+                        className="rounded p-1.5 text-[var(--color-text-muted)] hover:bg-[var(--color-surface-hover)] hover:text-[var(--color-red)] disabled:cursor-not-allowed disabled:opacity-40 disabled:hover:bg-transparent disabled:hover:text-[var(--color-text-muted)]"
+                        title={isOwner ? "Remove wallet from Gateway" : OWNER_ONLY_HINT}
                       >
                         <Trash2 className="h-3.5 w-3.5" />
                       </button>
@@ -693,6 +699,15 @@ export function ApiKeysSettings() {
             })}
           </div>
         )}
+        {/* Same reasoning as the credential error above: a wallet mutation the API
+            refuses (owner-only since SEC-166) must say so instead of leaving the row
+            untouched and the click unexplained. */}
+        {defaultWalletMut.error && (
+          <p className="mt-2 text-xs text-[var(--color-red)]">{defaultWalletMut.error.message}</p>
+        )}
+        {deleteWalletMut.error && (
+          <p className="mt-2 text-xs text-[var(--color-red)]">{deleteWalletMut.error.message}</p>
+        )}
       </div>
     </div>
   );
diff --git a/frontend/src/components/settings/GatewaySettings.tsx b/frontend/src/components/settings/GatewaySettings.tsx
index 5accf8a8..b6fb42bd 100644
--- a/frontend/src/components/settings/GatewaySettings.tsx
+++ b/frontend/src/components/settings/GatewaySettings.tsx
@@ -13,6 +13,7 @@ import {
 import { useEffect, useState } from "react";
 
 import { useServer } from "@/hooks/useServer";
+import { OWNER_ONLY_HINT, useServerPermission } from "@/hooks/useServerPermission";
 import { api } from "@/lib/api";
 
 const IMAGE_OPTIONS = [
@@ -53,6 +54,9 @@ const READONLY_NETWORK_KEYS = new Set([
 
 function NetworkConfigEditor({ server, networkId }: { server: string; networkId: string }) {
   const qc = useQueryClient();
+  // Updating a network config is owner-only on the backend (SEC-166); ask about
+  // *this* server rather than the selected one, since it arrives as a prop.
+  const { isOwner } = useServerPermission(server);
   const [draft, setDraft] = useState<Record<string, string>>({});
 
   const { data, isLoading, error } = useQuery({
@@ -148,8 +152,9 @@ function NetworkConfigEditor({ server, networkId }: { server: string; networkId:
       <div className="flex items-center gap-2 pt-1">
         <button
           onClick={save}
-          disabled={changed.length === 0 || saveMut.isPending}
-          className="flex items-center gap-1.5 rounded-md bg-[var(--color-primary)] px-3 py-1.5 text-xs font-medium text-white transition-colors hover:bg-[var(--color-primary)]/80 disabled:opacity-50"
+          disabled={changed.length === 0 || saveMut.isPending || !isOwner}
+          title={isOwner ? undefined : OWNER_ONLY_HINT}
+          className="flex items-center gap-1.5 rounded-md bg-[var(--color-primary)] px-3 py-1.5 text-xs font-medium text-white transition-colors hover:bg-[var(--color-primary)]/80 disabled:cursor-not-allowed disabled:opacity-50"
         >
           {saveMut.isPending ? <Loader2 className="h-3 w-3 animate-spin" /> : <Check className="h-3 w-3" />}
           Save {changed.length > 0 ? `(${changed.length})` : ""}
@@ -258,6 +263,9 @@ function GatewayNetworks({ server, running }: { server: string; running: boolean
 
 export function GatewaySettings() {
   const { server } = useServer();
+  // Container pull/start/stop/restart are owner-only on the backend (SEC-166).
+  // This only predicts the refusal — `_require_owner` is what enforces it.
+  const { isOwner } = useServerPermission();
   const qc = useQueryClient();
   const [showLogs, setShowLogs] = useState(false);
   const [showDeploy, setShowDeploy] = useState(false);
@@ -380,8 +388,9 @@ export function GatewaySettings() {
               <>
                 <button
                   onClick={() => restartMut.mutate()}
-                  disabled={restartMut.isPending}
-                  className="flex items-center gap-1.5 rounded-md border border-[var(--color-border)] px-3 py-1.5 text-xs font-medium text-[var(--color-text)] transition-colors hover:bg-[var(--color-surface-hover)] disabled:opacity-50"
+                  disabled={restartMut.isPending || !isOwner}
+                  title={isOwner ? undefined : OWNER_ONLY_HINT}
+                  className="flex items-center gap-1.5 rounded-md border border-[var(--color-border)] px-3 py-1.5 text-xs font-medium text-[var(--color-text)] transition-colors hover:bg-[var(--color-surface-hover)] disabled:cursor-not-allowed disabled:opacity-50"
                 >
                   {restartMut.isPending ? <Loader2 className="h-3 w-3 animate-spin" /> : <RefreshCw className="h-3 w-3" />}
                   Restart
@@ -390,8 +399,9 @@ export function GatewaySettings() {
                   <div className="flex items-center gap-1">
                     <button
                       onClick={() => stopMut.mutate()}
-                      disabled={stopMut.isPending}
-                      className="rounded-md bg-[var(--color-red)] px-3 py-1.5 text-xs font-medium text-white hover:bg-[var(--color-red)]/80"
+                      disabled={stopMut.isPending || !isOwner}
+                      title={isOwner ? undefined : OWNER_ONLY_HINT}
+                      className="rounded-md bg-[var(--color-red)] px-3 py-1.5 text-xs font-medium text-white hover:bg-[var(--color-red)]/80 disabled:cursor-not-allowed disabled:opacity-50"
                     >
                       {stopMut.isPending ? "Stopping..." : "Confirm Stop"}
                     </button>
@@ -405,7 +415,9 @@ export function GatewaySettings() {
                 ) : (
                   <button
                     onClick={() => setConfirmStop(true)}
-                    className="flex items-center gap-1.5 rounded-md border border-red-500/30 px-3 py-1.5 text-xs font-medium text-[var(--color-red)] transition-colors hover:bg-red-500/10"
+                    disabled={!isOwner}
+                    title={isOwner ? undefined : OWNER_ONLY_HINT}
+                    className="flex items-center gap-1.5 rounded-md border border-red-500/30 px-3 py-1.5 text-xs font-medium text-[var(--color-red)] transition-colors hover:bg-red-500/10 disabled:cursor-not-allowed disabled:opacity-50"
                   >
                     <Square className="h-3 w-3" /> Stop
                   </button>
@@ -441,6 +453,16 @@ export function GatewaySettings() {
             )}
           </div>
         )}
+
+        {/* A refusal that outruns the disabled state (stale permission, a share just
+            revoked) still has to say something: show the API's own detail rather than
+            leaving the container apparently untouched and the click unexplained. */}
+        {stopMut.error && (
+          <p className="mt-3 text-xs text-[var(--color-red)]">{stopMut.error.message}</p>
+        )}
+        {restartMut.error && (
+          <p className="mt-3 text-xs text-[var(--color-red)]">{restartMut.error.message}</p>
+        )}
       </div>
 
       {/* Pull Image */}
@@ -491,8 +513,9 @@ export function GatewaySettings() {
               {pullImage !== "custom" && (
                 <button
                   onClick={() => pullMut.mutate()}
-                  disabled={pulling}
-                  className="flex items-center gap-1.5 rounded-md bg-[var(--color-primary)] px-3 py-1.5 text-xs font-medium text-white transition-colors hover:bg-[var(--color-primary)]/80 disabled:opacity-50"
+                  disabled={pulling || !isOwner}
+                  title={isOwner ? undefined : OWNER_ONLY_HINT}
+                  className="flex items-center gap-1.5 rounded-md bg-[var(--color-primary)] px-3 py-1.5 text-xs font-medium text-white transition-colors hover:bg-[var(--color-primary)]/80 disabled:cursor-not-allowed disabled:opacity-50"
                 >
                   {pulling ? <Loader2 className="h-3 w-3 animate-spin" /> : <Download className="h-3 w-3" />}
                   Pull
@@ -510,8 +533,9 @@ export function GatewaySettings() {
                 />
                 <button
                   onClick={() => pullMut.mutate()}
-                  disabled={pulling || !pullCustomImage}
-                  className="flex items-center gap-1.5 rounded-md bg-[var(--color-primary)] px-3 py-1.5 text-xs font-medium text-white transition-colors hover:bg-[var(--color-primary)]/80 disabled:opacity-50"
+                  disabled={pulling || !pullCustomImage || !isOwner}
+                  title={isOwner ? undefined : OWNER_ONLY_HINT}
+                  className="flex items-center gap-1.5 rounded-md bg-[var(--color-primary)] px-3 py-1.5 text-xs font-medium text-white transition-colors hover:bg-[var(--color-primary)]/80 disabled:cursor-not-allowed disabled:opacity-50"
                 >
                   {pulling ? <Loader2 className="h-3 w-3 animate-spin" /> : <Download className="h-3 w-3" />}
                   Pull
@@ -617,8 +641,9 @@ export function GatewaySettings() {
 
             <button
               onClick={() => startMut.mutate()}
-              disabled={startMut.isPending || (image === "custom" && !customImage)}
-              className="flex items-center gap-1.5 rounded-md bg-[var(--color-primary)] px-4 py-1.5 text-xs font-medium text-white transition-colors hover:bg-[var(--color-primary)]/80 disabled:opacity-50"
+              disabled={startMut.isPending || (image === "custom" && !customImage) || !isOwner}
+              title={isOwner ? undefined : OWNER_ONLY_HINT}
+              className="flex items-center gap-1.5 rounded-md bg-[var(--color-primary)] px-4 py-1.5 text-xs font-medium text-white transition-colors hover:bg-[var(--color-primary)]/80 disabled:cursor-not-allowed disabled:opacity-50"
             >
               {startMut.isPending && <Loader2 className="h-3 w-3 animate-spin" />}
               Start Gateway

From d917dbda77b2ffa0ecf854dd0974db3d1fde0098 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Fri, 14 Aug 2026 19:17:46 +0300
Subject: [PATCH 097/116] (feat) ARCH-177: an admin panel control for the
 code_run grant
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

SEC-151's escape hatch — the per-user code_run grant that lets a non-admin
seat reach /code/run, and with it the MCP run_code tool — could only be set
by hand-editing config.yml. 8420d80 landed the admin API; this is the UI.

An "Admin" tab in Settings lists every user with its grant and toggles it.
The tab appears only when GET /admin/users answers: there is no is_admin
claim on the client, so the admin surface responding at all is the
discriminator. That is cosmetic — routes/admin.py re-reads the role from the
ConfigManager on every request and is the real gate.

Granting is behind a confirm that names what it confers (arbitrary Python in
the bot process: every server's credentials, the JWT secret, os.environ —
admin-equivalent in practice). Revoking takes power away, so it applies
directly.

The client lives in lib/admin-api.ts rather than lib/api.ts: apiFetch
flattens the status code into a message, and this caller needs to tell a 403
apart from a real failure to decide whether to show the tab at all.
---
 .../src/components/settings/AdminSettings.tsx | 143 ++++++++++++++++++
 frontend/src/lib/admin-api.ts                 |  77 ++++++++++
 frontend/src/pages/Settings.tsx               |  28 +++-
 3 files changed, 245 insertions(+), 3 deletions(-)
 create mode 100644 frontend/src/components/settings/AdminSettings.tsx
 create mode 100644 frontend/src/lib/admin-api.ts

diff --git a/frontend/src/components/settings/AdminSettings.tsx b/frontend/src/components/settings/AdminSettings.tsx
new file mode 100644
index 00000000..0b1f41aa
--- /dev/null
+++ b/frontend/src/components/settings/AdminSettings.tsx
@@ -0,0 +1,143 @@
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { Loader2, ShieldAlert, ShieldCheck } from "lucide-react";
+import { useState } from "react";
+
+import { ConfirmDialog } from "@/components/agent/ConfirmDialog";
+import { ADMIN_USERS_KEY, type AdminUser, adminApi } from "@/lib/admin-api";
+
+/**
+ * Admin-only user administration (ARCH-177).
+ *
+ * Carries exactly one capability today: the `code_run` grant SEC-151 added. The
+ * gate in `routes/code.py` is *admin or an explicit per-user grant*, and before
+ * this panel the only way to set that grant was hand-editing config.yml — so
+ * the escape hatch for a non-admin seat was effectively unreachable.
+ *
+ * Granting is behind a confirm that names what it confers, because it is not a
+ * scoped permission: arbitrary Python inside the bot process is admin-equivalent
+ * in practice. Revoking takes power away, so it applies directly.
+ */
+export function AdminSettings() {
+  const qc = useQueryClient();
+  const [confirmGrant, setConfirmGrant] = useState<AdminUser | null>(null);
+
+  const { data: users = [], isLoading } = useQuery({
+    queryKey: ADMIN_USERS_KEY,
+    queryFn: adminApi.getUsers,
+    retry: false,
+  });
+
+  const grantMut = useMutation({
+    mutationFn: ({ userId, granted }: { userId: number; granted: boolean }) =>
+      adminApi.setCodeRunGrant(userId, granted),
+    onSuccess: () => {
+      qc.invalidateQueries({ queryKey: ADMIN_USERS_KEY });
+      setConfirmGrant(null);
+    },
+  });
+
+  const label = (u: AdminUser) => u.username || `user ${u.user_id}`;
+
+  if (isLoading) {
+    return (
+      <div className="flex items-center justify-center py-12 text-[var(--color-text-muted)]">
+        <Loader2 className="h-5 w-5 animate-spin" />
+      </div>
+    );
+  }
+
+  return (
+    <div className="space-y-4">
+      <div className="rounded-lg border border-[var(--color-border)] bg-[var(--color-surface)] p-4">
+        <h3 className="flex items-center gap-1.5 text-sm font-semibold text-[var(--color-text)]">
+          <ShieldAlert className="h-3.5 w-3.5 text-[var(--color-red)]" />
+          Code execution
+        </h3>
+        <p className="mt-1.5 text-xs leading-relaxed text-[var(--color-text-muted)]">
+          The <code>code_run</code> grant lets a non-admin run arbitrary Python inside
+          the bot process — every server&apos;s credentials, the dashboard&apos;s JWT
+          secret and the environment. Admins already have it and cannot be granted it
+          separately. Grants and revocations are recorded in the audit log and take
+          effect immediately, with no restart.
+        </p>
+      </div>
+
+      {users.length === 0 && (
+        <p className="py-8 text-center text-sm text-[var(--color-text-muted)]">
+          No users registered.
+        </p>
+      )}
+
+      <div className="space-y-2">
+        {users.map((u) => (
+          <div
+            key={u.user_id}
+            className="flex items-center justify-between gap-3 rounded-lg border border-[var(--color-border)] bg-[var(--color-surface)] px-4 py-3"
+          >
+            <div className="min-w-0">
+              <p className="truncate text-sm font-medium text-[var(--color-text)]">
+                {label(u)}
+              </p>
+              <p className="text-xs text-[var(--color-text-muted)]">
+                {u.user_id}
+                {u.role ? ` · ${u.role}` : ""}
+              </p>
+            </div>
+
+            {u.is_admin ? (
+              <span className="flex shrink-0 items-center gap-1.5 text-xs text-[var(--color-text-muted)]">
+                <ShieldCheck className="h-3.5 w-3.5" />
+                Admin — always
+              </span>
+            ) : u.code_run ? (
+              <div className="flex shrink-0 items-center gap-2">
+                <span className="rounded-md bg-[var(--color-red)]/15 px-2 py-0.5 text-xs font-medium text-[var(--color-red)]">
+                  code_run
+                </span>
+                <button
+                  onClick={() => grantMut.mutate({ userId: u.user_id, granted: false })}
+                  disabled={grantMut.isPending}
+                  className="rounded-md px-3 py-1.5 text-xs font-medium text-[var(--color-text-muted)] transition-colors hover:bg-[var(--color-surface-hover)] hover:text-[var(--color-text)] disabled:opacity-50"
+                >
+                  Revoke
+                </button>
+              </div>
+            ) : (
+              <button
+                onClick={() => setConfirmGrant(u)}
+                className="shrink-0 rounded-md border border-[var(--color-border)] px-3 py-1.5 text-xs font-medium text-[var(--color-text-muted)] transition-colors hover:bg-[var(--color-surface-hover)] hover:text-[var(--color-text)]"
+              >
+                Grant code_run
+              </button>
+            )}
+          </div>
+        ))}
+      </div>
+
+      {grantMut.isError && (
+        <p className="text-xs text-[var(--color-red)]">
+          {(grantMut.error as Error).message}
+        </p>
+      )}
+
+      <ConfirmDialog
+        open={confirmGrant !== null}
+        title={`Grant code_run to ${confirmGrant ? label(confirmGrant) : ""}?`}
+        confirmLabel="Grant"
+        pendingLabel="Granting..."
+        isPending={grantMut.isPending}
+        isError={grantMut.isError}
+        errorText={(grantMut.error as Error | null)?.message}
+        onConfirm={() =>
+          confirmGrant && grantMut.mutate({ userId: confirmGrant.user_id, granted: true })
+        }
+        onClose={() => setConfirmGrant(null)}
+      >
+        This lets them execute arbitrary Python in the bot process: every configured
+        server&apos;s credentials, the dashboard&apos;s JWT secret and the environment
+        are readable, and the process is writable. It is admin-equivalent in practice.
+        Only grant it to someone you would make an admin.
+      </ConfirmDialog>
+    </div>
+  );
+}
diff --git a/frontend/src/lib/admin-api.ts b/frontend/src/lib/admin-api.ts
new file mode 100644
index 00000000..4d3c6073
--- /dev/null
+++ b/frontend/src/lib/admin-api.ts
@@ -0,0 +1,77 @@
+/**
+ * The admin-only user administration surface (`/api/v1/admin/*`, ARCH-177).
+ *
+ * Kept out of `lib/api.ts` on purpose. Everything in that module is callable by
+ * any logged-in seat; these two calls answer 403 to everyone but an admin, and
+ * a 403 here is not a failure — it is how the dashboard learns the current user
+ * is not an admin and hides the panel (there is no `is_admin` claim on the
+ * client today). That needs an error that carries its status code, which
+ * `apiFetch` deliberately flattens into a message, so this module does its own
+ * fetch over the shared `authHeaders`.
+ *
+ * Hiding the panel is cosmetic only. `routes/admin.py` re-reads the role from
+ * the ConfigManager on every request and is the actual gate.
+ */
+
+import { authHeaders } from "./auth-token";
+
+/** An error from an admin route, with the HTTP status preserved. */
+export class AdminApiError extends Error {
+  status: number;
+
+  constructor(status: number, message: string) {
+    super(message);
+    this.name = "AdminApiError";
+    this.status = status;
+  }
+}
+
+/** True when the failure was the admin gate refusing a non-admin. */
+export function isForbidden(error: unknown): boolean {
+  return error instanceof AdminApiError && error.status === 403;
+}
+
+async function adminFetch<T>(path: string, init?: RequestInit): Promise<T> {
+  const res = await fetch(path, {
+    ...init,
+    headers: {
+      "Content-Type": "application/json",
+      ...authHeaders(),
+      ...(init?.headers as Record<string, string>),
+    },
+  });
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({}));
+    throw new AdminApiError(res.status, err.detail || `Request failed: ${res.status}`);
+  }
+  return res.json();
+}
+
+/** A user row as the admin panel needs it — mirrors `AdminUser` in routes/admin.py. */
+export interface AdminUser {
+  user_id: number;
+  username: string;
+  role: string;
+  /**
+   * Whether the explicit `code_run` grant is set on this record. Admins are
+   * reported separately via `is_admin`: they already pass the gate on the admin
+   * arm, so they are never "granted".
+   */
+  code_run: boolean;
+  is_admin: boolean;
+}
+
+/** React Query key for the user list — shared so the tab probe and the panel dedupe. */
+export const ADMIN_USERS_KEY = ["admin-users"] as const;
+
+export const adminApi = {
+  /** Every user record with its grant. 403 for non-admins — see `isForbidden`. */
+  getUsers: () => adminFetch<AdminUser[]>("/api/v1/admin/users"),
+
+  /** Grant or revoke `code_run` for one user. Audited server-side. */
+  setCodeRunGrant: (userId: number, granted: boolean) =>
+    adminFetch<{ user_id: number; code_run: boolean }>(
+      `/api/v1/admin/users/${userId}/code-run`,
+      { method: "PUT", body: JSON.stringify({ granted }) },
+    ),
+};
diff --git a/frontend/src/pages/Settings.tsx b/frontend/src/pages/Settings.tsx
index da9a97b4..325384ea 100644
--- a/frontend/src/pages/Settings.tsx
+++ b/frontend/src/pages/Settings.tsx
@@ -1,11 +1,14 @@
+import { useQuery } from "@tanstack/react-query";
 import { LogOut } from "lucide-react";
 import { useSearchParams } from "react-router-dom";
 
+import { AdminSettings } from "@/components/settings/AdminSettings";
 import { ApiKeysSettings } from "@/components/settings/ApiKeysSettings";
 import { CustomProvidersSettings } from "@/components/settings/CustomProvidersSettings";
 import { GatewaySettings } from "@/components/settings/GatewaySettings";
 import { ServersSettings } from "@/components/settings/ServersSettings";
 import { VoiceSettings } from "@/components/settings/VoiceSettings";
+import { ADMIN_USERS_KEY, adminApi } from "@/lib/admin-api";
 import { useAuth } from "@/lib/auth";
 
 const TABS = [
@@ -16,13 +19,31 @@ const TABS = [
   { key: "voice", label: "Voice & AI" },
 ] as const;
 
-type TabKey = (typeof TABS)[number]["key"];
+/** Admin-only, appended to TABS when the user turns out to be an admin (ARCH-177). */
+const ADMIN_TAB = { key: "admin", label: "Admin" } as const;
+
+type TabKey = (typeof TABS)[number]["key"] | typeof ADMIN_TAB.key;
 
 export function Settings() {
   const [params, setParams] = useSearchParams();
-  const tab = (params.get("tab") as TabKey) || "servers";
   const { logout } = useAuth();
 
+  // There is no `is_admin` claim on the client, so the admin surface answering
+  // at all is the discriminator: `/admin/users` is 403 for everyone else. The
+  // panel reuses this query key, so opening the tab costs no second request.
+  // Hiding the tab is cosmetic — routes/admin.py re-checks the role every call.
+  const { isSuccess: isAdmin } = useQuery({
+    queryKey: ADMIN_USERS_KEY,
+    queryFn: adminApi.getUsers,
+    retry: false,
+  });
+
+  const tabs = isAdmin ? [...TABS, ADMIN_TAB] : TABS;
+  const requested = (params.get("tab") as TabKey) || "servers";
+  // A deep link to ?tab=admin from a seat that is not (or no longer) an admin
+  // falls back rather than rendering an empty page.
+  const tab = tabs.some((t) => t.key === requested) ? requested : "servers";
+
   return (
     <div className="mx-auto max-w-3xl">
       <div className="mb-4 flex items-center justify-between">
@@ -38,7 +59,7 @@ export function Settings() {
 
       {/* Tab bar */}
       <div className="mb-6 flex gap-1 rounded-lg border border-[var(--color-border)] bg-[var(--color-surface)] p-1">
-        {TABS.map((t) => (
+        {tabs.map((t) => (
           <button
             key={t.key}
             onClick={() => setParams({ tab: t.key })}
@@ -59,6 +80,7 @@ export function Settings() {
       {tab === "keys" && <ApiKeysSettings />}
       {tab === "llm" && <CustomProvidersSettings />}
       {tab === "voice" && <VoiceSettings />}
+      {tab === "admin" && <AdminSettings />}
     </div>
   );
 }

From 9a5bd0c2160920cea4dce24ac25ce0a54c2f0444 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Fri, 14 Aug 2026 19:21:55 +0300
Subject: [PATCH 098/116] (fix) SEC-180: the MCP argv and env agree on who owns
 an ownerless session

A session's owner id reached the condor MCP subprocess on two channels that
disagreed about what "no owner" means, and the channel that won carried a
placeholder. sessions.py derived the env pair with a deliberate fallback --
CONDOR_USER_ID falls back to the chat id, pinned by
tests/test_agents.py::test_extra_env_falls_back_to_chat_id -- while
binding.resolve hand-copied a different one (`spec.user_id or 0`) into the argv
pair. Since mcp_servers/condor/settings.py resolves argv first, an ownerless
spec launched with CONDOR_USER_ID=777 in its environment and --user-id 0 on its
command line ran as 0.

That id is a principal down there, not decoration: it mints the web JWT, is the
subject of has_server_access and is_admin, and roots the MemoryStore -- so such
a run wrote into a phantom user-0 store shared by every ownerless session. No
production spec-creation site can produce an ownerless spec today and user 0
fails closed at every check, so this is a divergence between a guarantee the
suite asserts and what the subprocess receives, not an escalation.

The fix is de-duplication, not refusal: an ownerless session is a shape
sessions.py supports on purpose (_resolve_conversation returns ("", "") for one,
and the budget/context/server blocks guard on `if spec.user_id:` rather than
denying), so the SEC-167 treatment would be wrong here. SessionSpec.effective_ids()
now owns the derivation and both call sites read it, leaving no `or 0` in
binding.py for the two channels to diverge on.
---
 condor/runtime/binding.py           |  8 ++++--
 condor/runtime/models.py            | 17 ++++++++++++
 condor/runtime/sessions.py          | 10 ++++----
 tests/runtime/test_agent_binding.py | 40 +++++++++++++++++++++++++++++
 4 files changed, 68 insertions(+), 7 deletions(-)

diff --git a/condor/runtime/binding.py b/condor/runtime/binding.py
index 533a90ab..c4113e46 100644
--- a/condor/runtime/binding.py
+++ b/condor/runtime/binding.py
@@ -112,9 +112,13 @@ def resolve(
     # and a specialist launched without it would read and write the CHAT's store.
     # What the slug must NOT decide down there is identity or routine scope —
     # see ``Settings.specialist_slug``.
+    # One derivation for both channels: these are the very ids sessions.py puts
+    # in CONDOR_USER_ID/CONDOR_CHAT_ID, and argv beats env in the subprocess, so
+    # a local fallback here would silently override the env one (SEC-180).
+    effective_user_id, effective_chat_id = spec.effective_ids()
     mcp_servers = build_mcp_servers_for_session(
-        spec.user_id or 0,
-        spec.chat_id or spec.user_id or 0,
+        effective_user_id,
+        effective_chat_id,
         user_data,
         server_name=effective_server if agent.server_required else None,
         agent_slug=agent.slug,
diff --git a/condor/runtime/models.py b/condor/runtime/models.py
index 0295bf1f..efa4717d 100644
--- a/condor/runtime/models.py
+++ b/condor/runtime/models.py
@@ -52,6 +52,23 @@ class SessionSpec(BaseModel):
         "a new one; a supplied id resumes that transcript.",
     )
 
+    def effective_ids(self) -> tuple[int, int]:
+        """``(user_id, chat_id)`` as the MCP subprocess must see them.
+
+        Both ids reach the subprocess twice — in its environment
+        (``CONDOR_USER_ID``/``CONDOR_CHAT_ID``) and on its argv
+        (``--user-id``/``--chat-id``, via ``binding.resolve``) — and argv wins
+        (mcp_servers/condor/settings.py). So the fallback for an ownerless or
+        chatless spec is derived here, once, and both channels read it: two
+        hand-copied ``or 0`` expressions used to disagree, and the subprocess
+        ran as the phantom user 0 that argv carried (SEC-180).
+
+        A spec with neither id is legitimately ownerless — sessions.py supports
+        that shape deliberately — and lands on 0, which fails closed everywhere.
+        """
+        chat_id = self.chat_id if self.chat_id is not None else (self.user_id or 0)
+        return self.user_id or chat_id, chat_id
+
 
 class SessionInfo(BaseModel):
     """Serializable view of a live session."""
diff --git a/condor/runtime/sessions.py b/condor/runtime/sessions.py
index b61ce48b..09d62f0c 100644
--- a/condor/runtime/sessions.py
+++ b/condor/runtime/sessions.py
@@ -390,13 +390,13 @@ async def get_or_create_session(
         await _enforce_session_budget(spec.user_id)
 
     # MCP subprocess env expects a numeric chat id; surfaces without a chat
-    # (web, mcp) fall back to the user id.
-    effective_chat_id = (
-        spec.chat_id if spec.chat_id is not None else (spec.user_id or 0)
-    )
+    # (web, mcp) fall back to the user id. The same pair goes down on argv via
+    # binding.resolve, which is what the subprocess actually reads first — so
+    # both channels take it from one derivation (SEC-180).
+    effective_user_id, effective_chat_id = spec.effective_ids()
     extra_env = {
         "CONDOR_CHAT_ID": str(effective_chat_id),
-        "CONDOR_USER_ID": str(spec.user_id or effective_chat_id),
+        "CONDOR_USER_ID": str(effective_user_id),
         # Which session the MCP subprocess belongs to. The *conversation* id does
         # not exist yet here (it is minted below, after the client is up), but the
         # key does and is stable for the subprocess's whole life — so tools that
diff --git a/tests/runtime/test_agent_binding.py b/tests/runtime/test_agent_binding.py
index 17a4aae3..8619269d 100644
--- a/tests/runtime/test_agent_binding.py
+++ b/tests/runtime/test_agent_binding.py
@@ -118,6 +118,46 @@ def fake_session_servers(user_id, chat_id, user_data=None, **kw):
     assert captured["args"][0] == 42
 
 
+def test_ownerless_session_argv_matches_the_env_fallback(monkeypatch):
+    """An ownerless spec reaches the subprocess as the chat id, never as 0.
+
+    The id travels on two channels — ``CONDOR_USER_ID`` in the env (sessions.py)
+    and ``--user-id`` on argv (here) — and argv is resolved first
+    (mcp_servers/condor/settings.py), so an ``or 0`` fallback of our own would
+    override the chat-id fallback the env channel computes and pinned by
+    ``tests/test_agents.py::test_extra_env_falls_back_to_chat_id``. Down there
+    the value is a principal: it mints the web JWT, subjects the server-access
+    and admin checks, and roots the memory store — user 0 would be a phantom
+    store shared by every ownerless session (SEC-180).
+    """
+    import config_manager
+
+    class _NoServers:
+        def get_accessible_servers(self, user_id):
+            return []
+
+        def get_server(self, name):
+            return None
+
+    monkeypatch.setattr(config_manager, "get_config_manager", lambda: _NoServers())
+    monkeypatch.setattr(config_manager, "get_effective_server", lambda *a, **k: None)
+
+    def argv_of(spec):
+        bound = binding.resolve(spec)
+        condor = next(s for s in bound.mcp_servers if s["name"] == "condor")
+        return condor["args"]
+
+    args = argv_of(_spec(agent_key="claude-code", user_id=None, chat_id=777))
+    assert args[args.index("--user-id") + 1] == "777"
+    assert args[args.index("--chat-id") + 1] == "777"
+    assert args[args.index("--user-id") + 1] != "0"
+
+    # And the owned case is untouched: the explicit ids pass straight through.
+    args = argv_of(_spec(agent_key="claude-code", user_id=42, chat_id=555))
+    assert args[args.index("--user-id") + 1] == "42"
+    assert args[args.index("--chat-id") + 1] == "555"
+
+
 def test_a_missing_default_record_still_starts_the_chat(monkeypatch, tmp_path):
     """An unreadable agents/condor/AGENT.md degrades; it does not fail closed."""
     monkeypatch.setattr(agent_module, "_DATA_ROOT", tmp_path)

From 3faf2116d8b5c12b92bc4f0887cb9341cc0b1ece Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Fri, 14 Aug 2026 19:30:33 +0300
Subject: [PATCH 099/116] (fix) SEC-178: a session's server is held to the
 caller's reach, not to a chat id

POST /api/v1/sessions takes a whole SessionSpec off the wire. The route forced
spec.user_id to the caller and validated nothing else, so spec.chat_id arrived
untouched and became the key for server resolution -- twice, with no access
check on the result. get_effective_server reads cm._data["chat_defaults"], a
global map keyed by chat id, so naming a chat you do not own returned that
chat's default server. The scoped candidate (get_accessible_servers) only ran
when that lookup found nothing, and a web-only account always falls through to
it: the dashboard stores its default as set_chat_default_server(user.id, name)
and never writes the user_data active_server that would win first.

The symptom is credential handover, not a wrong label. _shared.py looks the
resolved name's server up and puts HUMMINGBOT_API_USERNAME/PASSWORD into the
spawned mcp-hummingbot subprocess's env, so an authenticated user with no grant
on server X posted {"chat_id": <victim>} and got a live session trading on X.

This is the vector SEC-164 removed from TickEngine._resolve_server; the
session-spawn path was never swept (grep has_server_access condor/runtime/
returned nothing). The same predicate now guards both sites -- every candidate,
pinned name and chat default and fallback alike, must exist *and* be reachable
by the run's own principal, which sessions.py reads from the SessionSpec.
effective_ids() that SEC-180 made the single source of that derivation. In the
builder the gate is the last thing between a name and its credentials, so no
candidate path reaches cm.get_server() unchecked.

chat_id stays in resolution on purpose: handlers/config/servers.py writes
set_chat_default_server(chat_id, ...) for Telegram groups, so a group's default
is legitimately keyed by chat, and the access check preserves that case while
closing the escalation -- a member who can reach the group's server still gets
it. The route additionally gates a pinned spec.server_name with the shared
check_server_access, mirroring _respawn, and is pinned in BODY_SITES.
---
 condor/runtime/sessions.py                 |  30 ++-
 condor/web/routes/sessions.py              |   9 +
 handlers/agents/_shared.py                 |  30 ++-
 tests/test_mcp_argv_secrets.py             |   3 +
 tests/test_session_model_switch.py         |   5 +
 tests/test_session_server_access.py        | 296 +++++++++++++++++++++
 tests/test_web_server_access_dependency.py |   1 +
 7 files changed, 360 insertions(+), 14 deletions(-)
 create mode 100644 tests/test_session_server_access.py

diff --git a/condor/runtime/sessions.py b/condor/runtime/sessions.py
index 09d62f0c..d0a92d92 100644
--- a/condor/runtime/sessions.py
+++ b/condor/runtime/sessions.py
@@ -510,16 +510,30 @@ async def get_or_create_session(
                 platform=spec.platform,
                 server_name=spec.server_name,
             )
-        # Resolve the server name that was actually used for this session
-        resolved_server = spec.server_name
-        if not resolved_server and spec.user_id:
-            from config_manager import get_config_manager, get_effective_server
+        # Resolve the server name that was actually used for this session. The
+        # chat default is the ambient answer, but ``chat_defaults`` is a global
+        # map keyed by chat id and ``spec`` is an unvalidated request body on
+        # the web, so naming someone else's chat would otherwise resolve their
+        # server here (SEC-178). Every candidate is therefore held to existence
+        # *and* reach, subjected on the run's own principal — the same id the
+        # MCP toolset is built for, so the label and the credentials downstream
+        # can never disagree about who this session belongs to.
+        from config_manager import get_config_manager, get_effective_server
+
+        cm = get_config_manager()
+        subject_id, _ = spec.effective_ids()
+
+        def usable(name: str | None) -> bool:
+            return bool(name and cm.get_server(name)) and cm.has_server_access(
+                subject_id, name
+            )
 
+        resolved_server = spec.server_name
+        if not usable(resolved_server):
             resolved_server = get_effective_server(spec.chat_id, user_data)
-            if not resolved_server:
-                cm = get_config_manager()
-                accessible = cm.get_accessible_servers(spec.user_id)
-                resolved_server = accessible[0] if accessible else None
+        if not usable(resolved_server):
+            accessible = cm.get_accessible_servers(subject_id)
+            resolved_server = accessible[0] if accessible else None
 
         # The durable conversation behind this session. An empty id mints a new
         # one; a supplied id replays that transcript's tail into the opening
diff --git a/condor/web/routes/sessions.py b/condor/web/routes/sessions.py
index 9dbfa255..d2a48460 100644
--- a/condor/web/routes/sessions.py
+++ b/condor/web/routes/sessions.py
@@ -146,6 +146,15 @@ async def create_session(
     elif spec.user_id != user.id and not cm.is_admin(user.id):
         raise HTTPException(status_code=403, detail="Cannot create for another user")
 
+    # The session's toolset is built with this server's API credentials, so gate
+    # the pinned name exactly like ``_respawn`` does. The subject is the
+    # *caller*, never ``spec.user_id`` (SEC-167): an admin creating a session
+    # for someone else is held to their own reach, not licensed by the owner's.
+    # The rest of the spec is not a licence either — ``spec.chat_id`` reaches
+    # server resolution too, and is checked where it lands (SEC-178).
+    if spec.server_name:
+        check_server_access(user.id, spec.server_name)
+
     from condor.preferences import load_user_data_for
 
     try:
diff --git a/handlers/agents/_shared.py b/handlers/agents/_shared.py
index de5035bc..d51a29f4 100644
--- a/handlers/agents/_shared.py
+++ b/handlers/agents/_shared.py
@@ -535,7 +535,9 @@ def build_mcp_servers_for_session(
 
     ``server_name`` pins the run to that Condor server (an Agent with
     ``server_required``); when omitted, the chat's ambient server is resolved
-    from the user's preferences, then from the first accessible server.
+    from the user's preferences, then from the first accessible server. Each
+    candidate must exist *and* be reachable by ``user_id`` — a name this user
+    has no grant on resolves to the next candidate, never to its credentials.
 
     ``agent_slug`` scopes the condor MCP tools' memory/skills to that Agent's
     own stores (``agents/{slug}/``). Without it the tools target the chat
@@ -551,12 +553,28 @@ def build_mcp_servers_for_session(
 
     cm = get_config_manager()
 
-    # Resolve which hummingbot server to use (explicit override > user preferences)
-    if not server_name:
-        server_name = get_effective_server(chat_id, user_data)
-    if not server_name:
+    # Resolve which hummingbot server to use (explicit override > user
+    # preferences). Every candidate is held to existence *and* reach, because
+    # the name that comes out of here decides whose API credentials go into the
+    # subprocess env below. ``chat_id`` is not a principal — ``chat_defaults``
+    # is a global map keyed by chat, so a caller who can name someone else's
+    # chat could name their server too (SEC-178, the SEC-164 shape). The subject
+    # is always ``user_id``, the authenticated owner of the run; the same
+    # predicate guards TickEngine._resolve_server.
+    def usable(name: str | None) -> bool:
+        return bool(name and cm.get_server(name)) and cm.has_server_access(
+            user_id, name
+        )
+
+    def candidates():
+        # Lazy on purpose: resolving the chat default writes back into
+        # ``user_data``, so it must not run when a pin already answered.
+        yield server_name
+        yield get_effective_server(chat_id, user_data)
         accessible = cm.get_accessible_servers(user_id)
-        server_name = accessible[0] if accessible else None
+        yield accessible[0] if accessible else None
+
+    server_name = next((name for name in candidates() if usable(name)), None)
 
     # Condor MCP -- runs as stdio subprocess, tools work locally without TCP bridge
     # Pass resolved server_name so start_agent uses the correct server
diff --git a/tests/test_mcp_argv_secrets.py b/tests/test_mcp_argv_secrets.py
index bae11d2f..c21ed845 100644
--- a/tests/test_mcp_argv_secrets.py
+++ b/tests/test_mcp_argv_secrets.py
@@ -25,6 +25,9 @@ class _OneServer:
         def get_accessible_servers(self, user_id):
             return ["prod"]
 
+        def has_server_access(self, user_id, name, *a, **kw):
+            return True
+
         def get_server(self, name):
             return {
                 "host": "10.0.0.5",
diff --git a/tests/test_session_model_switch.py b/tests/test_session_model_switch.py
index a4362bbd..4401369e 100644
--- a/tests/test_session_model_switch.py
+++ b/tests/test_session_model_switch.py
@@ -83,6 +83,11 @@ def get_accessible_servers(self, user_id):
     def has_server_access(self, user_id, server_name, *a, **k):
         return server_name in {"local", "prod"}
 
+    # Resolution holds every candidate to existence *and* reach (SEC-178), so
+    # the stub has to answer both halves of the predicate.
+    def get_server(self, name):
+        return {"host": "h", "port": 8000} if name in {"local", "prod"} else None
+
 
 @pytest.fixture
 def env(tmp_path, monkeypatch):
diff --git a/tests/test_session_server_access.py b/tests/test_session_server_access.py
new file mode 100644
index 00000000..a8ab579f
--- /dev/null
+++ b/tests/test_session_server_access.py
@@ -0,0 +1,296 @@
+"""SEC-178: a caller-supplied chat id must not resolve someone else's server.
+
+``POST /api/v1/sessions`` takes a whole ``SessionSpec`` off the wire. The route
+forces ``spec.user_id`` to the caller, but ``spec.chat_id`` arrived untouched
+and became the key for server resolution — and ``chat_defaults`` is a *global*
+map keyed by chat id (config_manager.get_effective_server), so naming a chat you
+do not own returned that chat's default server.
+
+The name that comes out of that resolution is not a label: ``_shared.py`` looks
+its credentials up and puts ``HUMMINGBOT_API_USERNAME``/``PASSWORD`` into the
+spawned mcp-hummingbot subprocess's environment. So the bar is the one SEC-164
+already set for ``TickEngine._resolve_server``: every candidate — the pinned
+name, the chat default, the accessible fallback — must exist *and* be reachable
+by the run's own principal.
+
+What must NOT regress: a Telegram group chat's default is legitimately keyed by
+chat id (``handlers/config/servers.py`` writes ``set_chat_default_server``), so
+a member who *can* reach that server still resolves it.
+"""
+
+import asyncio
+
+import pytest
+
+import config_manager
+from condor.runtime import SessionKey, SessionSpec
+from condor.runtime import client as runtime
+from condor.runtime import sessions as session_module
+
+ATTACKER = 42
+VICTIM_CHAT = 999
+GROUP_CHAT = -100777
+VICTIM_SERVER = "victim-prod"
+OWN_SERVER = "mine"
+
+SERVERS = {
+    VICTIM_SERVER: {
+        "host": "10.0.0.9",
+        "port": 8000,
+        "username": "victim-user",
+        "password": "victim-p4ssword",
+    },
+    OWN_SERVER: {
+        "host": "127.0.0.1",
+        "port": 8000,
+        "username": "my-user",
+        "password": "my-p4ssword",
+    },
+}
+
+# The global map the attack reads: the victim's chat defaults to their server,
+# the group chat defaults to one the attacker legitimately reaches.
+CHAT_DEFAULTS = {VICTIM_CHAT: VICTIM_SERVER, GROUP_CHAT: OWN_SERVER}
+
+
+class _Cm:
+    """Both servers exist; ``grants`` says which ones the subject may use."""
+
+    def __init__(self, grants: dict[int, list[str]], accessible=None):
+        self.grants = grants
+        # Overridable so the fallback candidate can be made over-broad on
+        # purpose — the gate must hold even if this list ever lies.
+        self._accessible = accessible
+
+    def get_server(self, name):
+        return SERVERS.get(name)
+
+    def has_server_access(self, user_id, name, *a, **kw):
+        return name in self.grants.get(user_id, [])
+
+    def get_accessible_servers(self, user_id):
+        if self._accessible is not None:
+            return list(self._accessible)
+        return list(self.grants.get(user_id, []))
+
+    def is_admin(self, user_id):
+        return False
+
+
+@pytest.fixture
+def config(monkeypatch):
+    """Install a stub ConfigManager + the global chat-defaults lookup."""
+
+    def install(grants, accessible=None):
+        cm = _Cm(grants, accessible)
+        monkeypatch.setattr(config_manager, "get_config_manager", lambda: cm)
+        # auth.py binds the getter at import time, so the web guard needs its
+        # own patch to see the same stub.
+        monkeypatch.setattr(
+            "condor.web.auth.get_config_manager", lambda: cm, raising=False
+        )
+        monkeypatch.setattr(
+            config_manager,
+            "get_effective_server",
+            lambda chat_id, user_data=None: CHAT_DEFAULTS.get(chat_id),
+        )
+        return cm
+
+    return install
+
+
+def _build(user_id, chat_id, **kwargs):
+    from handlers.agents._shared import build_mcp_servers_for_session
+
+    return build_mcp_servers_for_session(user_id, chat_id, **kwargs)
+
+
+def _hummingbot(servers):
+    return next((s for s in servers if s["name"] == "mcp-hummingbot"), None)
+
+
+def _env_of(server):
+    return {e["name"]: e["value"] for e in server.get("env", [])}
+
+
+def _leaks_victim(servers) -> bool:
+    """True if the victim's credentials reached the spawn config, anywhere."""
+    blob = repr(servers)
+    return any(
+        SERVERS[VICTIM_SERVER][field] in blob for field in ("username", "password")
+    )
+
+
+# ── The credential handover: no grant, no mcp-hummingbot ──
+
+
+def test_pinned_server_without_a_grant_never_yields_its_credentials(config):
+    """Candidate 1: the explicitly pinned name."""
+    config({ATTACKER: []})
+
+    servers = _build(ATTACKER, ATTACKER, server_name=VICTIM_SERVER)
+
+    assert _hummingbot(servers) is None
+    assert not _leaks_victim(servers)
+
+
+def test_foreign_chat_default_never_yields_its_credentials(config):
+    """Candidate 2: the chat default — this is the SEC-178 attack itself.
+
+    The attacker names the victim's chat id. ``chat_defaults[999]`` is the
+    victim's server, and before the fix its username/password went straight into
+    the subprocess env.
+    """
+    config({ATTACKER: []})
+
+    servers = _build(ATTACKER, VICTIM_CHAT)
+
+    assert _hummingbot(servers) is None, "victim's server was handed to the subprocess"
+    assert not _leaks_victim(servers)
+    # The condor MCP server is still spawned: a serverless session is a valid
+    # outcome, refusing to resolve is not the same as refusing to run.
+    assert [s["name"] for s in servers] == ["condor"]
+
+
+def test_fallback_candidate_is_held_to_the_same_bar(config):
+    """Candidate 3: the accessible fallback, made over-broad on purpose.
+
+    ``get_accessible_servers`` is scoped by construction, so this pins the gate
+    rather than the list: whatever name comes out of resolution passed
+    ``has_server_access``, with no path around it.
+    """
+    config({ATTACKER: []}, accessible=[VICTIM_SERVER])
+
+    servers = _build(ATTACKER, ATTACKER)
+
+    assert _hummingbot(servers) is None
+    assert not _leaks_victim(servers)
+
+
+def test_a_granted_server_still_spawns_with_its_credentials(config):
+    """The gate denies, it does not break the ordinary path."""
+    config({ATTACKER: [OWN_SERVER]})
+
+    servers = _build(ATTACKER, ATTACKER, server_name=OWN_SERVER)
+
+    env = _env_of(_hummingbot(servers))
+    assert env["HUMMINGBOT_API_USERNAME"] == SERVERS[OWN_SERVER]["username"]
+    assert env["HUMMINGBOT_API_PASSWORD"] == SERVERS[OWN_SERVER]["password"]
+
+
+def test_group_chat_default_is_not_regressed(config):
+    """A member who *can* reach the group's default still resolves it.
+
+    The fix must not do what engine.py did and drop ``chat_id`` from
+    resolution: a Telegram group's default server is legitimately keyed by chat
+    id, and every member of it is entitled to that server.
+    """
+    config({ATTACKER: [OWN_SERVER]})
+
+    servers = _build(ATTACKER, GROUP_CHAT)
+
+    hummingbot = _hummingbot(servers)
+    assert hummingbot is not None
+    assert OWN_SERVER in hummingbot["args"]
+    assert _env_of(hummingbot)["HUMMINGBOT_API_PASSWORD"] == (
+        SERVERS[OWN_SERVER]["password"]
+    )
+
+
+# ── The session the spawn is recorded as ──
+
+
+class _FakeClient:
+    """Stands in for the ACP subprocess."""
+
+    def __init__(self, **kwargs):
+        self.alive = True
+        self.kwargs = kwargs
+
+    async def start(self):
+        pass
+
+    async def stop(self):
+        self.alive = False
+
+    async def prompt(self, text):
+        return ""
+
+
+@pytest.fixture
+def registry(monkeypatch):
+    monkeypatch.setattr(session_module, "_sessions", {})
+    monkeypatch.setattr(session_module, "ACPClient", _FakeClient)
+    monkeypatch.setattr(session_module, "PydanticAIClient", _FakeClient)
+    monkeypatch.setattr(session_module, "build_initial_context", lambda *a, **k: "")
+    monkeypatch.setattr(
+        "handlers.agents._shared.build_mcp_servers_for_session", lambda *a, **k: []
+    )
+    return session_module
+
+
+def test_session_does_not_record_a_server_the_owner_cannot_reach(config, registry):
+    """The spec's chat id is not a licence for the session's own server name."""
+    config({ATTACKER: []})
+
+    info = asyncio.run(
+        runtime.create_session(
+            SessionSpec(
+                key=str(SessionKey.web(ATTACKER, "s1")),
+                agent_key="claude-code",
+                user_id=ATTACKER,
+                chat_id=VICTIM_CHAT,
+                platform="web",
+                lazy_context=True,
+            )
+        )
+    )
+
+    assert info.server_name != VICTIM_SERVER
+    assert not info.server_name
+
+
+def test_session_keeps_a_reachable_chat_default(config, registry):
+    """Same call, with the grant in place, still resolves the chat's server."""
+    config({ATTACKER: [OWN_SERVER]})
+
+    info = asyncio.run(
+        runtime.create_session(
+            SessionSpec(
+                key=str(SessionKey.telegram(GROUP_CHAT)),
+                agent_key="claude-code",
+                user_id=ATTACKER,
+                chat_id=GROUP_CHAT,
+                lazy_context=True,
+            )
+        )
+    )
+
+    assert info.server_name == OWN_SERVER
+
+
+# ── The route ──
+
+
+def test_route_refuses_a_pinned_server_the_caller_cannot_reach(config):
+    """``create_session`` gates the body's server name like ``_respawn`` does."""
+    from fastapi import HTTPException
+
+    from condor.web.models import WebUser
+    from condor.web.routes import sessions as routes
+
+    config({ATTACKER: []})
+
+    spec = SessionSpec(
+        key=str(SessionKey.web(ATTACKER, "s1")),
+        agent_key="claude-code",
+        user_id=ATTACKER,
+        server_name=VICTIM_SERVER,
+        platform="web",
+    )
+    user = WebUser(id=ATTACKER, username="a", first_name="A", role="user")
+
+    with pytest.raises(HTTPException) as exc:
+        asyncio.run(routes.create_session(spec, user=user))
+
+    assert exc.value.status_code == 403
diff --git a/tests/test_web_server_access_dependency.py b/tests/test_web_server_access_dependency.py
index 2e68f076..015870d4 100644
--- a/tests/test_web_server_access_dependency.py
+++ b/tests/test_web_server_access_dependency.py
@@ -83,6 +83,7 @@
     ("condor.web.routes.routines", "schedule_routine_v2"),
     ("condor.web.routes.code", "run_code"),
     ("condor.web.routes.sessions", "_respawn"),
+    ("condor.web.routes.sessions", "create_session"),
     ("condor.web.routes.agents", "update_agent_config"),
     ("condor.web.routes.agents", "consult_agent"),
     ("condor.web.routes.agents", "delegate_agent"),

From ab32d6fed5c44881893e0f5da6e43fe881333448 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Fri, 14 Aug 2026 19:38:22 +0300
Subject: [PATCH 100/116] (fix) CORR-182: routine jobs resolve their instance
 by owner, not by chat

Instances are written through _get_instances(context) -> context.user_data,
which PTB keys by effective_user.id, but every job path read them back with
application.user_data[job.data["chat_id"]]. In a private chat the two ids
coincide so the bug hid; in a group the chat id is negative and the bucket
does not exist, so a group-started interval routine never executed even once
(the callback fails closed and the repeating job is never removed), one-shot
and daily runs left a ghost stuck at status "running" in the store, and a
continuous routine got a junk bucket under the negative chat id plus an
empty user_data.

Carry the owner in job_data the way active_server already is, and resolve the
bucket through _owner_data(application, owner_id, chat_id). owner_id falls
back to chat_id, so private chats and jobs persisted before this change are
byte-identical; restore_scheduled_jobs stamps the owner from the bucket key
it iterates, so already-persisted instances are adopted rather than orphaned.
chat_id is untouched: it stays the delivery address and the job-name key.
---
 handlers/routines/__init__.py         |  96 ++++++--
 tests/test_routine_group_job_owner.py | 316 ++++++++++++++++++++++++++
 2 files changed, 395 insertions(+), 17 deletions(-)
 create mode 100644 tests/test_routine_group_job_owner.py

diff --git a/handlers/routines/__init__.py b/handlers/routines/__init__.py
index 0521ef93..41609f31 100644
--- a/handlers/routines/__init__.py
+++ b/handlers/routines/__init__.py
@@ -72,6 +72,22 @@ def _get_instances(context: ContextTypes.DEFAULT_TYPE) -> dict:
     return context.user_data["routine_instances"]
 
 
+def _owner_data(application, owner_id: int | None, chat_id: int) -> dict:
+    """The starter's ``user_data`` bucket, as seen from a job or a task.
+
+    PTB keys ``user_data`` by ``update.effective_user.id``, which is what
+    ``_get_instances`` writes through — so a job must look itself up by the
+    owner stamped at creation, never by ``chat_id``. In a private chat the two
+    ids coincide; in a group the chat id is negative and its bucket does not
+    exist at all.
+
+    ``owner_id`` falls back to ``chat_id`` so private chats and jobs persisted
+    before the owner was carried in ``job_data`` resolve exactly as before —
+    the same graceful degradation ``_sync_instance_to_store`` applies.
+    """
+    return application.user_data.get(owner_id if owner_id is not None else chat_id, {})
+
+
 def _get_draft(context: ContextTypes.DEFAULT_TYPE, routine_name: str) -> dict:
     """Get draft config for a routine, initializing from defaults if needed."""
     drafts = _get_drafts(context)
@@ -272,8 +288,13 @@ async def _execute_routine(
     config_dict: dict,
     chat_id: int,
     active_server: str | None = None,
+    owner_id: int | None = None,
 ) -> tuple[str, float, str | None]:
-    """Execute a routine and return (result, duration, report_id)."""
+    """Execute a routine and return (result, duration, report_id).
+
+    ``chat_id`` is where the result is delivered; ``owner_id`` is whose
+    ``user_data`` (and therefore whose preferences) the routine runs against.
+    """
     routine = get_routine(routine_name)
     if not routine:
         return "Routine not found", 0, None
@@ -283,7 +304,7 @@ async def _execute_routine(
     # Prepare context for routine
     context._chat_id = chat_id
     context._instance_id = instance_id
-    user_data = context.application.user_data.get(chat_id, {})
+    user_data = _owner_data(context.application, owner_id, chat_id)
     # Inject the active server captured at creation time so routines
     # in group chats connect to the correct server.
     if active_server and not user_data.get("preferences", {}).get("general", {}).get(
@@ -354,22 +375,31 @@ async def _run_continuous_routine(
     config_dict: dict,
     chat_id: int,
     active_server: str | None = None,
+    owner_id: int | None = None,
 ) -> None:
-    """Run a continuous routine as an asyncio task."""
+    """Run a continuous routine as an asyncio task.
+
+    ``chat_id`` addresses the messages; ``owner_id`` keys the ``user_data`` the
+    routine reads and the instance bucket cleaned up when the task ends.
+    """
     routine = get_routine(routine_name)
     if not routine:
         logger.error(f"Routine {routine_name} not found")
         return
 
+    owner_key = owner_id if owner_id is not None else chat_id
+
     # Create a mock context for the routine
     class MockContext:
         def __init__(self):
             self._chat_id = chat_id
             self._instance_id = instance_id
-            # Ensure user_data dict exists in application
-            if chat_id not in application.user_data:
-                application.user_data[chat_id] = {}
-            self._user_data = application.user_data[chat_id]
+            # Ensure user_data dict exists in application. Keyed by the owner:
+            # fabricating one for a (negative) group chat id would both persist
+            # junk and hand the routine an empty bucket.
+            if owner_key not in application.user_data:
+                application.user_data[owner_key] = {}
+            self._user_data = application.user_data[owner_key]
             # Inject active server so group chats connect to the correct server
             if active_server and not self._user_data.get("preferences", {}).get(
                 "general", {}
@@ -398,7 +428,7 @@ def user_data(self):
         logger.error(f"Continuous routine {routine_name}[{instance_id}] error: {e}")
 
     # Clean up instance when task ends
-    instances = application.user_data.get(chat_id, {}).get("routine_instances", {})
+    instances = _owner_data(application, owner_id, chat_id).get("routine_instances", {})
     if instance_id in instances:
         del instances[instance_id]
     try:
@@ -414,9 +444,10 @@ async def _interval_job_callback(context: CallbackContext) -> None:
     routine_name = data["routine_name"]
     config_dict = data["config_dict"]
     chat_id = data["chat_id"]
+    owner_id = data.get("user_id")
 
     # Check if instance still exists (may have been stopped)
-    instances = context.application.user_data.get(chat_id, {}).get(
+    instances = _owner_data(context.application, owner_id, chat_id).get(
         "routine_instances", {}
     )
     if instance_id not in instances:
@@ -430,10 +461,11 @@ async def _interval_job_callback(context: CallbackContext) -> None:
         config_dict,
         chat_id,
         active_server=data.get("active_server"),
+        owner_id=owner_id,
     )
 
     # Re-check instance exists after execution (may have been stopped during run)
-    instances = context.application.user_data.get(chat_id, {}).get(
+    instances = _owner_data(context.application, owner_id, chat_id).get(
         "routine_instances", {}
     )
     if instance_id not in instances:
@@ -494,6 +526,7 @@ async def _oneshot_job_callback(context: CallbackContext) -> None:
     chat_id = data["chat_id"]
     msg_id = data.get("msg_id")
     background = data.get("background", False)
+    owner_id = data.get("user_id")
 
     result, duration, report_id = await _execute_routine(
         context,
@@ -502,10 +535,11 @@ async def _oneshot_job_callback(context: CallbackContext) -> None:
         config_dict,
         chat_id,
         active_server=data.get("active_server"),
+        owner_id=owner_id,
     )
 
     # Remove one-shot instance after completion
-    instances = context.application.user_data.get(chat_id, {}).get(
+    instances = _owner_data(context.application, owner_id, chat_id).get(
         "routine_instances", {}
     )
     if instance_id in instances:
@@ -547,7 +581,14 @@ async def _oneshot_job_callback(context: CallbackContext) -> None:
     elif msg_id:
         # Update the detail view
         await _refresh_detail_msg(
-            context, chat_id, msg_id, routine_name, result, duration, report_id
+            context,
+            chat_id,
+            msg_id,
+            routine_name,
+            result,
+            duration,
+            report_id,
+            owner_id=owner_id,
         )
 
 
@@ -558,6 +599,7 @@ async def _daily_job_callback(context: CallbackContext) -> None:
     routine_name = data["routine_name"]
     config_dict = data["config_dict"]
     chat_id = data["chat_id"]
+    owner_id = data.get("user_id")
 
     result, duration, report_id = await _execute_routine(
         context,
@@ -566,10 +608,11 @@ async def _daily_job_callback(context: CallbackContext) -> None:
         config_dict,
         chat_id,
         active_server=data.get("active_server"),
+        owner_id=owner_id,
     )
 
     # Update instance state
-    instances = context.application.user_data.get(chat_id, {}).get(
+    instances = _owner_data(context.application, owner_id, chat_id).get(
         "routine_instances", {}
     )
     if instance_id in instances:
@@ -669,6 +712,9 @@ def _create_scheduled_instance(
         "routine_name": routine_name,
         "config_dict": config_dict.copy(),  # Copy to isolate from draft changes
         "chat_id": chat_id,
+        # Carried for the same reason as active_server: the tick has no update
+        # to derive it from, and user_data is keyed by user_id, not chat_id.
+        "user_id": user_id,
         "msg_id": msg_id,
         "background": background,
         "active_server": active_server,
@@ -764,6 +810,7 @@ def _create_continuous_instance(
             frozen_config,
             chat_id,
             active_server=active_server,
+            owner_id=user_id,
         )
     )
     _continuous_tasks[instance_id] = task
@@ -1195,13 +1242,18 @@ async def _refresh_detail_msg(
     result: str | None = None,
     duration: float | None = None,
     report_id: str | None = None,
+    owner_id: int | None = None,
 ) -> None:
-    """Refresh the routine detail message after execution."""
+    """Refresh the routine detail message after execution.
+
+    Drafts and instances belong to ``owner_id``; ``chat_id`` only says where the
+    message lives.
+    """
     routine = get_routine(routine_name)
     if not routine:
         return
 
-    user_data = context.application.user_data.get(chat_id, {})
+    user_data = _owner_data(context.application, owner_id, chat_id)
     drafts = user_data.get("routine_drafts", {})
     draft = drafts.get(routine_name, {})
 
@@ -1561,7 +1613,9 @@ async def _process_config(
     msg_id = context.user_data.get("routines_msg_id")
     chat_id = context.user_data.get("routines_chat_id")
     if msg_id and chat_id:
-        await _refresh_detail_msg(context, chat_id, msg_id, routine_name)
+        await _refresh_detail_msg(
+            context, chat_id, msg_id, routine_name, owner_id=_starter_id(update)
+        )
 
 
 async def _process_daily_time(
@@ -1622,7 +1676,9 @@ async def _process_daily_time(
     # Refresh detail
     msg_id = context.user_data.get("routines_msg_id")
     if msg_id:
-        await _refresh_detail_msg(context, chat_id, msg_id, routine_name)
+        await _refresh_detail_msg(
+            context, chat_id, msg_id, routine_name, owner_id=_starter_id(update)
+        )
 
 
 # =============================================================================
@@ -1809,6 +1865,10 @@ async def restore_scheduled_jobs(application) -> int:
             if not inst.get("user_id"):
                 inst["user_id"] = chat_id
 
+            # The bucket this instance was found in is its owner, so this is
+            # the key every restored job must read itself back through.
+            owner_id = inst.get("user_id") or chat_id
+
             routine_name = inst.get("routine_name")
             config_dict = inst.get("config", {})
             schedule = inst.get("schedule", {})
@@ -1848,6 +1908,7 @@ async def restore_scheduled_jobs(application) -> int:
                             config_dict,
                             chat_id,
                             active_server=_active_server,
+                            owner_id=owner_id,
                         )
                     )
                     _continuous_tasks[instance_id] = task
@@ -1870,6 +1931,7 @@ async def restore_scheduled_jobs(application) -> int:
                 "routine_name": routine_name,
                 "config_dict": config_dict,
                 "chat_id": chat_id,
+                "user_id": owner_id,
                 "active_server": _active_server,
             }
 
diff --git a/tests/test_routine_group_job_owner.py b/tests/test_routine_group_job_owner.py
new file mode 100644
index 00000000..b785d97a
--- /dev/null
+++ b/tests/test_routine_group_job_owner.py
@@ -0,0 +1,316 @@
+"""A routine started from a group belongs to the person, not to the room.
+
+Instances are written through ``_get_instances(context)`` -> ``context.user_data``,
+and PTB keys ``user_data`` by ``update.effective_user.id``. Every job path used to
+read it back with ``application.user_data[job.data["chat_id"]]``. In a private chat
+the two ids coincide, so the bug hides; in a group the chat id is negative, the
+bucket is simply absent, and the interval callback fails closed — the routine never
+runs once, forever, while the repeating job stays alive.
+"""
+
+import asyncio
+from types import SimpleNamespace
+
+import pytest
+from pydantic import BaseModel
+
+import handlers.routines as hr
+
+GROUP_ID = -1001234
+OWNER_ID = 7
+
+
+class Config(BaseModel):
+    pass
+
+
+class FakeBot:
+    def __init__(self):
+        self.sent = []
+
+    async def send_message(self, chat_id, text, **kwargs):
+        self.sent.append((chat_id, text))
+        return SimpleNamespace(message_id=1)
+
+    async def edit_message_text(self, **kwargs):
+        self.sent.append((kwargs.get("chat_id"), kwargs.get("text")))
+        return SimpleNamespace(message_id=1)
+
+
+class FakeStore:
+    def __init__(self):
+        self.removed = []
+
+    def remove_instance(self, instance_id):
+        self.removed.append(instance_id)
+
+
+def _routine():
+    return SimpleNamespace(
+        name="probe",
+        description="Probe routine",
+        is_continuous=False,
+        get_fields=lambda: {},
+        get_default_config=lambda: Config(),
+    )
+
+
+@pytest.fixture
+def store(monkeypatch):
+    s = FakeStore()
+    monkeypatch.setattr(hr, "get_routine_store", lambda: s)
+    return s
+
+
+@pytest.fixture
+def synced(monkeypatch):
+    calls = []
+    monkeypatch.setattr(
+        hr, "_sync_instance_to_store", lambda iid, meta: calls.append((iid, meta))
+    )
+    return calls
+
+
+@pytest.fixture
+def executed(monkeypatch):
+    """Records every ``_execute_routine`` call instead of running a routine."""
+    calls = []
+
+    async def _execute(context, instance_id, routine_name, config_dict, chat_id, **kw):
+        calls.append({"chat_id": chat_id, **kw})
+        return "ok", 1.5, None
+
+    monkeypatch.setattr(hr, "_execute_routine", _execute)
+    monkeypatch.setattr(hr, "get_routine", lambda name: _routine())
+    return calls
+
+
+def _instances():
+    return {
+        "i1": {
+            "routine_name": "probe",
+            "status": "running",
+            "user_id": OWNER_ID,
+            "schedule": {"type": "interval", "interval_sec": 60},
+        }
+    }
+
+
+def _ctx(instances, *, user_id=OWNER_ID, chat_id=GROUP_ID, extra=None):
+    """A job context shaped like a group run: instance in the owner's bucket."""
+    data = {
+        "instance_id": "i1",
+        "routine_name": "probe",
+        "config_dict": {},
+        "chat_id": chat_id,
+        "background": True,
+    }
+    if user_id is not None:
+        data["user_id"] = user_id
+    data.update(extra or {})
+    return SimpleNamespace(
+        bot=FakeBot(),
+        application=SimpleNamespace(
+            user_data={OWNER_ID: {"routine_instances": instances}}
+        ),
+        job=SimpleNamespace(data=data),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Interval: the load-bearing case — today it returns before executing anything.
+# ---------------------------------------------------------------------------
+
+
+def test_interval_job_from_a_group_actually_runs(executed, synced):
+    instances = _instances()
+    ctx = _ctx(instances)
+
+    asyncio.run(hr._interval_job_callback(ctx))
+
+    assert executed, "the routine never executed for a group-started interval job"
+    assert instances["i1"]["run_count"] == 1
+    assert instances["i1"]["last_run_at"] is not None
+    assert instances["i1"]["last_result"] == "ok"
+
+
+def test_interval_job_delivers_to_the_group_not_the_owner(executed, synced):
+    ctx = _ctx(_instances())
+
+    asyncio.run(hr._interval_job_callback(ctx))
+
+    assert [c for c, _ in ctx.bot.sent] == [GROUP_ID]
+
+
+def test_execute_receives_the_owner_id(executed, synced):
+    ctx = _ctx(_instances())
+
+    asyncio.run(hr._interval_job_callback(ctx))
+
+    assert executed[0]["owner_id"] == OWNER_ID
+    assert executed[0]["chat_id"] == GROUP_ID
+
+
+# ---------------------------------------------------------------------------
+# One-shot and daily: they run, but their bookkeeping used to be skipped,
+# leaving a ghost stuck at status "running" in the store forever.
+# ---------------------------------------------------------------------------
+
+
+def test_oneshot_job_from_a_group_clears_the_instance(executed, store):
+    instances = _instances()
+    ctx = _ctx(instances)
+
+    asyncio.run(hr._oneshot_job_callback(ctx))
+
+    assert "i1" not in instances
+    assert store.removed == ["i1"]
+
+
+def test_daily_job_from_a_group_updates_and_syncs(executed, synced):
+    instances = _instances()
+    ctx = _ctx(instances)
+
+    asyncio.run(hr._daily_job_callback(ctx))
+
+    assert instances["i1"]["run_count"] == 1
+    assert [iid for iid, _ in synced] == ["i1"]
+
+
+# ---------------------------------------------------------------------------
+# Private chats and jobs persisted before the owner was carried must not move.
+# ---------------------------------------------------------------------------
+
+
+def test_legacy_job_without_user_id_still_resolves_by_chat_id(executed, synced):
+    """Pre-change job data carries no ``user_id``; in the private chats it was
+    created in, ``chat_id`` is the right bucket key and must keep working."""
+    instances = _instances()
+    ctx = _ctx(instances, user_id=None, chat_id=OWNER_ID)
+
+    asyncio.run(hr._interval_job_callback(ctx))
+
+    assert instances["i1"]["run_count"] == 1
+    assert executed[0]["owner_id"] in (None, OWNER_ID)
+
+
+def test_a_stopped_instance_is_still_skipped(executed, synced):
+    ctx = _ctx({})
+
+    asyncio.run(hr._interval_job_callback(ctx))
+
+    assert not executed, "a removed instance must not be executed"
+
+
+# ---------------------------------------------------------------------------
+# Continuous routines: no junk bucket under the negative chat id, and the
+# instance is cleaned out of the starter's real bucket when the task ends.
+# ---------------------------------------------------------------------------
+
+
+def test_continuous_routine_uses_the_owner_bucket(monkeypatch, store):
+    seen = {}
+
+    async def _run(config, context):
+        seen["user_data"] = context.user_data
+        return "done"
+
+    monkeypatch.setattr(
+        hr,
+        "get_routine",
+        lambda name: SimpleNamespace(
+            name="probe",
+            is_continuous=True,
+            config_class=Config,
+            run_fn=_run,
+        ),
+    )
+
+    instances = _instances()
+    owner_bucket = {"routine_instances": instances, "preferences": {}}
+    application = SimpleNamespace(user_data={OWNER_ID: owner_bucket}, bot=FakeBot())
+
+    asyncio.run(
+        hr._run_continuous_routine(
+            application,
+            "i1",
+            "probe",
+            {},
+            GROUP_ID,
+            owner_id=OWNER_ID,
+        )
+    )
+
+    assert seen["user_data"] is owner_bucket
+    assert (
+        GROUP_ID not in application.user_data
+    ), "a junk bucket was created for the chat"
+    assert "i1" not in instances, "the finished instance was left as a zombie"
+    assert store.removed == ["i1"]
+
+
+def test_continuous_routine_without_owner_falls_back_to_chat(monkeypatch, store):
+    """Private-chat behaviour (and any caller that hasn't been threaded) is
+    unchanged: the chat id is still the bucket key."""
+    seen = {}
+
+    async def _run(config, context):
+        seen["user_data"] = context.user_data
+        return "done"
+
+    monkeypatch.setattr(
+        hr,
+        "get_routine",
+        lambda name: SimpleNamespace(
+            name="probe",
+            is_continuous=True,
+            config_class=Config,
+            run_fn=_run,
+        ),
+    )
+
+    instances = _instances()
+    bucket = {"routine_instances": instances}
+    application = SimpleNamespace(user_data={OWNER_ID: bucket}, bot=FakeBot())
+
+    asyncio.run(hr._run_continuous_routine(application, "i1", "probe", {}, OWNER_ID))
+
+    assert seen["user_data"] is bucket
+    assert "i1" not in instances
+
+
+# ---------------------------------------------------------------------------
+# The detail message must read the starter's drafts, not the room's.
+# ---------------------------------------------------------------------------
+
+
+def test_detail_refresh_reads_the_owner_drafts(monkeypatch):
+    monkeypatch.setattr(
+        hr,
+        "get_routine",
+        lambda name: SimpleNamespace(
+            name="probe",
+            description="Probe routine",
+            is_continuous=False,
+            get_fields=lambda: {"pair": {"default": "BTC-USDT"}},
+            get_default_config=lambda: Config(),
+        ),
+    )
+
+    ctx = SimpleNamespace(
+        bot=FakeBot(),
+        application=SimpleNamespace(
+            user_data={
+                OWNER_ID: {
+                    "routine_drafts": {"probe": {"pair": "SOL-USDC"}},
+                    "routine_instances": _instances(),
+                }
+            }
+        ),
+    )
+
+    asyncio.run(hr._refresh_detail_msg(ctx, GROUP_ID, 99, "probe", owner_id=OWNER_ID))
+
+    _, text = ctx.bot.sent[0]
+    assert "pair=SOL-USDC" in text
+    assert "1 running" in text

From 3348e1e9e6a6691c3376f32c6eb4ee3e5d5e99ba Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Mon, 17 Aug 2026 14:09:47 +0300
Subject: [PATCH 101/116] (fix) every GeckoTerminal caller draws on the shared
 budget

The rate gate, circuit breaker and single-flight already lived in
pool_data, but only the dashboard's pool paths went through them. The
Telegram gecko browser, the gateway token importer, the MCP tools and
four routines each built their own GeckoTerminalAsyncClient or hand-rolled
an api.geckoterminal.com URL, so their requests were invisible to the
accounting and spent the same per-IP quota without ever being paced.

Two bugs at once, since none of those call sites closed their client: a
leaked httpx pool per invocation on top of the unmetered request.

Route them all through gecko_call, and through gecko_request where
geckoterminal_py exposes no method for the path. test_gecko_throttle
holds the line with two guard tests: nobody constructs a second client,
and nobody hand-builds a raw URL.
---
 .../smart_money_flow/routines/onchain_flow.py |  22 +-
 .../routines/lp_scanner.py                    |  40 +-
 handlers/config/gateway/tokens.py             |   8 +-
 handlers/dex/geckoterminal.py                 | 100 ++---
 handlers/dex/pools.py                         |   9 +-
 .../hummingbot_api/tools/geckoterminal.py     | 379 +++++++++---------
 routines/mcap_comparison.py                   |  21 +-
 routines/solana_pool_scanner.py               |  39 +-
 tests/test_gecko_throttle.py                  | 277 +++++++++++++
 9 files changed, 583 insertions(+), 312 deletions(-)
 create mode 100644 tests/test_gecko_throttle.py

diff --git a/agents/smart_money_flow/routines/onchain_flow.py b/agents/smart_money_flow/routines/onchain_flow.py
index 99f7eb28..28318c88 100644
--- a/agents/smart_money_flow/routines/onchain_flow.py
+++ b/agents/smart_money_flow/routines/onchain_flow.py
@@ -32,7 +32,6 @@
 
 # Keyless endpoints (CoinGecko + GeckoTerminal free tier, public Solana RPC).
 CG = "https://api.coingecko.com/api/v3"
-GECKO = "https://api.geckoterminal.com/api/v2"
 XRPL_NODES = [
     "https://xrplcluster.com/",
     "https://s1.ripple.com:51234",
@@ -90,6 +89,22 @@ async def _get_json(url: str, timeout: float = 12) -> "dict | list | None":
         return None
 
 
+async def _gecko_json(path: str, params: dict | None = None) -> "dict | None":
+    """A GeckoTerminal call on the process-wide budget.
+
+    Separate from ``_get_json`` because only this host is rate-limited per IP and
+    shared with the dashboard; CoinGecko keeps the plain fetcher. Returns None on
+    any failure, like its sibling — a tick must never raise.
+    """
+    from handlers.dex.pool_data import gecko_request
+
+    try:
+        return await gecko_request("GET", path, params=params)
+    except Exception as exc:  # never raise into a tick
+        logger.warning("flow: gecko %s failed: %s", path, type(exc).__name__)
+        return None
+
+
 def _clamp(x: float, lo: float = -1.0, hi: float = 1.0) -> float:
     return max(lo, min(hi, x))
 
@@ -133,8 +148,9 @@ async def fetch_solana_pulse(top_n: int = 10) -> dict | None:
     read. Solana carries materially deeper on-chain liquidity than XRPL, so it is
     the DEFAULT on-chain signal source.
     """
-    data = await _get_json(
-        f"{GECKO}/networks/solana/tokens/{SOL_MINT}/pools?page=1&include=base_token,dex"
+    data = await _gecko_json(
+        f"networks/solana/tokens/{SOL_MINT}/pools",
+        {"page": 1, "include": "base_token,dex"},
     )
     if not data:
         return None
diff --git a/agents/solana_dex_lp_expert/routines/lp_scanner.py b/agents/solana_dex_lp_expert/routines/lp_scanner.py
index 2a8ff926..2c814abe 100644
--- a/agents/solana_dex_lp_expert/routines/lp_scanner.py
+++ b/agents/solana_dex_lp_expert/routines/lp_scanner.py
@@ -20,7 +20,6 @@
 import logging
 import re
 
-import aiohttp
 from pydantic import BaseModel, Field, field_validator
 from telegram.ext import ContextTypes
 
@@ -31,7 +30,6 @@
 
 CATEGORY = "Analysis"
 
-GECKO_BASE = "https://api.geckoterminal.com/api/v2"
 GECKO_NETWORK = "solana"  # GeckoTerminal network id
 CLMM_NETWORK = "solana-mainnet-beta"  # hummingbot-api CLMM network id
 _WINDOW_TO_FIELD = {"1h": "volume_1h", "6h": "volume_6h", "24h": "volume_24h"}
@@ -73,17 +71,16 @@ def _coerce_list(cls, v):
         return v
 
 
-async def _gecko_get(
-    session: aiohttp.ClientSession, path: str, params: dict | None = None
-) -> dict:
-    url = f"{GECKO_BASE}/{path}"
-    headers = {"Accept": "application/json;version=20230302"}
-    async with session.get(
-        url, headers=headers, params=params, timeout=aiohttp.ClientTimeout(total=25)
-    ) as resp:
-        if resp.status != 200:
-            raise RuntimeError(f"GeckoTerminal {path} -> HTTP {resp.status}")
-        return await resp.json()
+async def _gecko_get(path: str, params: dict | None = None) -> dict:
+    """One GeckoTerminal call on the process-wide budget.
+
+    Goes through ``pool_data`` rather than opening a session here: gecko's free
+    tier is ~30 requests/minute per IP, shared with the dashboard and every other
+    routine, and a scanner that fans out per venue is exactly what exhausts it.
+    """
+    from handlers.dex.pool_data import gecko_request
+
+    return await gecko_request("GET", path, params=params)
 
 
 def _num(v, default=0.0) -> float:
@@ -110,17 +107,12 @@ async def run(config: Config, context: ContextTypes.DEFAULT_TYPE) -> str:
     # 1. Source candidates from GeckoTerminal: global trending + top-per-venue.
     raw: list[dict] = []
     try:
-        async with aiohttp.ClientSession() as session:
-            tasks = [_gecko_get(session, f"networks/{GECKO_NETWORK}/trending_pools")]
-            for v in venues:
-                tasks.append(
-                    _gecko_get(
-                        session,
-                        f"networks/{GECKO_NETWORK}/dexes/{v}/pools",
-                        {"page": 1},
-                    )
-                )
-            results = await asyncio.gather(*tasks, return_exceptions=True)
+        tasks = [_gecko_get(f"networks/{GECKO_NETWORK}/trending_pools")]
+        for v in venues:
+            tasks.append(
+                _gecko_get(f"networks/{GECKO_NETWORK}/dexes/{v}/pools", {"page": 1})
+            )
+        results = await asyncio.gather(*tasks, return_exceptions=True)
         for r in results:
             if isinstance(r, Exception):
                 logger.warning(f"lp_scanner: gecko source failed: {r}")
diff --git a/handlers/config/gateway/tokens.py b/handlers/config/gateway/tokens.py
index e95d4264..3001044d 100644
--- a/handlers/config/gateway/tokens.py
+++ b/handlers/config/gateway/tokens.py
@@ -2,10 +2,11 @@
 Gateway token management functions
 """
 
-from geckoterminal_py import GeckoTerminalAsyncClient
 from telegram import InlineKeyboardButton, InlineKeyboardMarkup, Update
 from telegram.ext import ContextTypes
 
+from handlers.dex.pool_data import gecko_call
+
 from ..user_preferences import get_active_server
 from ._shared import (
     escape_markdown_v2,
@@ -851,9 +852,8 @@ async def handle_token_input(
                             parse_mode="MarkdownV2",
                         )
 
-                    gecko_client = GeckoTerminalAsyncClient()
-                    result = await gecko_client.get_specific_token_on_network(
-                        gecko_network, address
+                    result = await gecko_call(
+                        "get_specific_token_on_network", gecko_network, address
                     )
 
                     # Extract token data
diff --git a/handlers/dex/geckoterminal.py b/handlers/dex/geckoterminal.py
index b6bfc43b..f3deeb21 100644
--- a/handlers/dex/geckoterminal.py
+++ b/handlers/dex/geckoterminal.py
@@ -14,7 +14,6 @@
 import logging
 from datetime import datetime
 
-from geckoterminal_py import GeckoTerminalAsyncClient
 from telegram import InlineKeyboardButton, InlineKeyboardMarkup, Update
 from telegram.ext import ContextTypes
 
@@ -22,7 +21,13 @@
 
 from ._shared import cached_call
 from .pool_data import GECKO_TO_GATEWAY_NETWORK as _GECKO_TO_GATEWAY_NETWORK
-from .pool_data import can_fetch_liquidity, fetch_liquidity_bins, get_connector_for_dex
+from .pool_data import (
+    can_fetch_liquidity,
+    fetch_liquidity_bins,
+    gecko_call,
+    gecko_request,
+    get_connector_for_dex,
+)
 from .visualizations import (
     generate_combined_chart,
     generate_liquidity_chart,
@@ -856,11 +861,10 @@ async def show_trending_pools(
         cache_key = f"gecko_trending_{network or 'all'}"
 
         async def fetch_trending():
-            client = GeckoTerminalAsyncClient()
             if network and network != "all":
-                result = await client.get_trending_pools_by_network(network)
+                result = await gecko_call("get_trending_pools_by_network", network)
             else:
-                result = await client.get_trending_pools()
+                result = await gecko_call("get_trending_pools")
             logger.info(f"GeckoTerminal trending response type: {type(result)}")
             return _extract_pools_from_response(result, 10)
 
@@ -992,8 +996,7 @@ async def show_top_pools(
         cache_key = f"gecko_top_{network}"
 
         async def fetch_top():
-            client = GeckoTerminalAsyncClient()
-            result = await client.get_top_pools_by_network(network)
+            result = await gecko_call("get_top_pools_by_network", network)
             return _extract_pools_from_response(result, 10)
 
         pools = await cached_call(
@@ -1129,11 +1132,10 @@ async def show_new_pools(
         cache_key = f"gecko_new_{network or 'all'}"
 
         async def fetch_new():
-            client = GeckoTerminalAsyncClient()
             if network and network != "all":
-                result = await client.get_new_pools_by_network(network)
+                result = await gecko_call("get_new_pools_by_network", network)
             else:
-                result = await client.get_new_pools_all_networks()
+                result = await gecko_call("get_new_pools_all_networks")
             return _extract_pools_from_response(result, 10)
 
         pools = await cached_call(
@@ -1221,8 +1223,7 @@ async def handle_gecko_networks(
         cache_key = "gecko_networks"
 
         async def fetch_networks():
-            client = GeckoTerminalAsyncClient()
-            result = await client.get_networks()
+            result = await gecko_call("get_networks")
             return _extract_pools_from_response(result, 100)
 
         networks = await cached_call(
@@ -1403,9 +1404,8 @@ async def process_gecko_search(
         token_address = user_input.strip()
 
         # Use the selected network directly
-        client = GeckoTerminalAsyncClient()
-        result = await client.get_top_pools_by_network_token(
-            selected_network, token_address
+        result = await gecko_call(
+            "get_top_pools_by_network_token", selected_network, token_address
         )
         pools = _extract_pools_from_response(result, 10)
 
@@ -1565,8 +1565,7 @@ async def _show_pool_chart(
         network = pool_data["network"]
         address = pool_data["address"]
 
-        client = GeckoTerminalAsyncClient()
-        result = await client.get_ohlcv(network, address, timeframe)
+        result = await gecko_call("get_ohlcv", network, address, timeframe)
 
         logger.info(f"OHLCV raw response type: {type(result)}")
 
@@ -2075,8 +2074,7 @@ async def show_ohlcv_chart(
         network = pool_data["network"]
         address = pool_data["address"]
 
-        client = GeckoTerminalAsyncClient()
-        result = await client.get_ohlcv(network, address, timeframe)
+        result = await gecko_call("get_ohlcv", network, address, timeframe)
 
         logger.info(f"OHLCV raw response type: {type(result)}")
 
@@ -2424,8 +2422,7 @@ async def show_gecko_combined(
         connector = get_connector_for_dex(dex_id)
 
         # Fetch OHLCV data
-        client = GeckoTerminalAsyncClient()
-        ohlcv_result = await client.get_ohlcv(network, address, timeframe)
+        ohlcv_result = await gecko_call("get_ohlcv", network, address, timeframe)
 
         # Parse OHLCV response
         ohlcv_data = []
@@ -2603,8 +2600,7 @@ async def show_recent_trades(
         network = pool_data["network"]
         address = pool_data["address"]
 
-        client = GeckoTerminalAsyncClient()
-        result = await client.get_trades(network, address, 20)
+        result = await gecko_call("get_trades", network, address, 20)
 
         logger.info(f"Trades raw response type: {type(result)}")
 
@@ -2845,8 +2841,9 @@ async def handle_gecko_token_info(
     )
 
     try:
-        client = GeckoTerminalAsyncClient()
-        result = await client.get_specific_token_on_network(network, token_address)
+        result = await gecko_call(
+            "get_specific_token_on_network", network, token_address
+        )
 
         # Extract token data
         token_data = {}
@@ -3034,9 +3031,8 @@ async def handle_gecko_token_search(
     await query.answer("Searching pools...")
 
     try:
-        client = GeckoTerminalAsyncClient()
-        result = await client.get_top_pools_by_network_token(
-            network, token_info.get("address", "")
+        result = await gecko_call(
+            "get_top_pools_by_network_token", network, token_info.get("address", "")
         )
         pools = _extract_pools_from_response(result, 10)
 
@@ -3587,9 +3583,6 @@ async def handle_gecko_add_tokens(
     update: Update, context: ContextTypes.DEFAULT_TYPE
 ) -> None:
     """Add pool tokens to Gateway configuration"""
-    import httpx
-    from geckoterminal_py import GeckoTerminalAsyncClient
-
     from config_manager import get_config_manager
 
     query = update.callback_query
@@ -3609,28 +3602,23 @@ async def handle_gecko_add_tokens(
     if not base_addr and not quote_addr and pool_address:
         await query.answer("Fetching token info...")
         try:
-            # Use direct API call since geckoterminal_py doesn't have get_pool method
-            url = f"https://api.geckoterminal.com/api/v2/networks/{gecko_network}/pools/{pool_address}"
-            async with httpx.AsyncClient() as client:
-                response = await client.get(
-                    url, params={"include": "base_token,quote_token"}
-                )
-                if response.status_code == 200:
-                    result = response.json()
-                    data = result.get("data", {})
-                    relationships = data.get("relationships", {})
-                    base_token_id = (
-                        relationships.get("base_token", {})
-                        .get("data", {})
-                        .get("id", "")
-                    )
-                    quote_token_id = (
-                        relationships.get("quote_token", {})
-                        .get("data", {})
-                        .get("id", "")
-                    )
-                    base_addr = _parse_token_address_from_id(base_token_id)
-                    quote_addr = _parse_token_address_from_id(quote_token_id)
+            # A raw path because geckoterminal_py exposes no get_pool, but still
+            # through gecko_request so it draws on the same shared budget.
+            result = await gecko_request(
+                "GET",
+                f"networks/{gecko_network}/pools/{pool_address}",
+                params={"include": "base_token,quote_token"},
+            )
+            data = result.get("data", {})
+            relationships = data.get("relationships", {})
+            base_token_id = (
+                relationships.get("base_token", {}).get("data", {}).get("id", "")
+            )
+            quote_token_id = (
+                relationships.get("quote_token", {}).get("data", {}).get("id", "")
+            )
+            base_addr = _parse_token_address_from_id(base_token_id)
+            quote_addr = _parse_token_address_from_id(quote_token_id)
         except Exception as e:
             logger.warning(f"Failed to fetch pool info for tokens: {e}")
 
@@ -3638,8 +3626,6 @@ async def handle_gecko_add_tokens(
         await query.answer("No token addresses available", show_alert=True)
         return
 
-    gecko_client = GeckoTerminalAsyncClient()
-
     # Map GeckoTerminal network to Gateway network
     network_mapping = {
         "solana": "solana-mainnet-beta",
@@ -3672,8 +3658,8 @@ async def add_token_to_gateway(token_address: str) -> str:
         """Fetch token info and add to gateway. Returns symbol or error indicator."""
         try:
             # Fetch from GeckoTerminal
-            result = await gecko_client.get_specific_token_on_network(
-                gecko_network, token_address
+            result = await gecko_call(
+                "get_specific_token_on_network", gecko_network, token_address
             )
 
             token_data = {}
diff --git a/handlers/dex/pools.py b/handlers/dex/pools.py
index ccb2e1e5..770fbe5e 100644
--- a/handlers/dex/pools.py
+++ b/handlers/dex/pools.py
@@ -26,7 +26,7 @@
 )
 
 from ._shared import DEFAULT_CACHE_TTL, get_cached, invalidate_cache, set_cached
-from .pool_data import fetch_liquidity_bins, fetch_ohlcv, get_gecko_network
+from .pool_data import fetch_liquidity_bins, fetch_ohlcv, gecko_call, get_gecko_network
 from .visualizations import (
     generate_aggregated_liquidity_chart,
     generate_combined_chart,
@@ -1768,8 +1768,6 @@ async def handle_add_to_gateway(
     Fetches token details from GeckoTerminal and adds both base and quote tokens
     to the Gateway configuration for the network.
     """
-    from geckoterminal_py import GeckoTerminalAsyncClient
-
     from config_manager import get_config_manager
 
     query = update.callback_query
@@ -1821,14 +1819,13 @@ async def handle_add_to_gateway(
 
     added_tokens = []
     errors = []
-    gecko_client = GeckoTerminalAsyncClient()
 
     async def add_token_to_gateway(token_address: str) -> bool:
         """Fetch token info and add to gateway"""
         try:
             # Fetch from GeckoTerminal
-            result = await gecko_client.get_specific_token_on_network(
-                gecko_network, token_address
+            result = await gecko_call(
+                "get_specific_token_on_network", gecko_network, token_address
             )
 
             if isinstance(result, dict):
diff --git a/mcp_servers/hummingbot_api/tools/geckoterminal.py b/mcp_servers/hummingbot_api/tools/geckoterminal.py
index 05bb675c..c084ef31 100644
--- a/mcp_servers/hummingbot_api/tools/geckoterminal.py
+++ b/mcp_servers/hummingbot_api/tools/geckoterminal.py
@@ -22,7 +22,6 @@
 
 logger = logging.getLogger("hummingbot-mcp")
 
-BASE_URL = "https://api.geckoterminal.com/api/v2"
 
 OHLCV_TIMEFRAMES = ["1m", "5m", "15m", "1h", "4h", "12h", "1d"]
 
@@ -265,196 +264,198 @@ async def explore_geckoterminal(
     trade_volume_filter: float | None = None,
 ) -> dict[str, Any]:
     """Execute a GeckoTerminal API action and return formatted results."""
-    import aiohttp
-
-    async with aiohttp.ClientSession() as session:
-
-        async def _get(path: str, params: dict | None = None) -> dict:
-            url = f"{BASE_URL}/{path}"
-            headers = {"Accept": "application/json;version=20230302"}
-            async with session.get(url, headers=headers, params=params) as resp:
-                resp.raise_for_status()
-                return await resp.json()
-
-        # ── Networks ─────────────────────────────────────────────────
-        if action == "networks":
-            data = await _get("networks")
-            networks = _extract_networks(data)
-            return {
-                "formatted_output": f"Available Networks ({len(networks)}):\n\n{format_networks_table(networks)}"
-            }
-
-        # ── DEXes by network ─────────────────────────────────────────
-        elif action == "dexes":
-            if not network:
-                raise ToolError("'network' is required for action='dexes'")
-            data = await _get(f"networks/{network}/dexes")
-            dexes = _extract_dexes(data)
-            return {
-                "formatted_output": f"DEXes on {network} ({len(dexes)}):\n\n{format_dexes_table(dexes)}"
-            }
-
-        # ── Trending pools ───────────────────────────────────────────
-        elif action == "trending_pools":
-            if network:
-                data = await _get(f"networks/{network}/trending_pools")
-                title = f"Trending Pools on {network}"
-            else:
-                data = await _get("networks/trending_pools")
-                title = "Trending Pools (All Networks)"
-            pools = _extract_pools(data)
-            return {
-                "formatted_output": f"{title} ({len(pools)}):\n\n{format_pools_table(pools)}"
-            }
-
-        # ── Top pools ────────────────────────────────────────────────
-        elif action == "top_pools":
-            if not network:
-                raise ToolError("'network' is required for action='top_pools'")
-            if dex_id:
-                data = await _get(f"networks/{network}/dexes/{dex_id}/pools")
-                title = f"Top Pools on {network} / {dex_id}"
-            else:
-                data = await _get(f"networks/{network}/pools")
-                title = f"Top Pools on {network}"
-            pools = _extract_pools(data)
-            return {
-                "formatted_output": f"{title} ({len(pools)}):\n\n{format_pools_table(pools)}"
-            }
-
-        # ── New pools ────────────────────────────────────────────────
-        elif action == "new_pools":
-            if network:
-                data = await _get(f"networks/{network}/new_pools")
-                title = f"New Pools on {network}"
-            else:
-                data = await _get("networks/new_pools")
-                title = "New Pools (All Networks)"
-            pools = _extract_pools(data)
-            return {
-                "formatted_output": f"{title} ({len(pools)}):\n\n{format_pools_table(pools)}"
-            }
-
-        # ── Pool detail ──────────────────────────────────────────────
-        elif action == "pool_detail":
-            if not network or not pool_address:
-                raise ToolError(
-                    "'network' and 'pool_address' are required for action='pool_detail'"
-                )
-            data = await _get(f"networks/{network}/pools/{pool_address}")
-            pools = _extract_pools(data)
-            if pools:
-                p = pools[0]
-                lines = [
-                    f"Pool: {p.get('name', 'N/A')}",
-                    f"Address: {p.get('address', 'N/A')}",
-                    f"DEX: {p.get('dex_id', 'N/A')}",
-                    f"Base Token Price: {format_currency(p.get('base_token_price_usd'), decimals=6)}",
-                    f"Quote Token Price: {format_currency(p.get('quote_token_price_usd'), decimals=6)}",
-                    f"Reserve (USD): {format_number(p.get('reserve_in_usd'))}",
-                    f"FDV: {format_number(p.get('fdv_usd'))}",
-                    f"Market Cap: {format_number(p.get('market_cap_usd'))}",
-                    f"24h Volume: {format_number(p.get('volume_h24'))}",
-                    f"1h Change: {p.get('price_change_h1', 'N/A')}%",
-                    f"24h Change: {p.get('price_change_h24', 'N/A')}%",
-                    f"24h Txns: {p.get('txns_h24_buys', 'N/A')} buys / {p.get('txns_h24_sells', 'N/A')} sells",
-                    f"Created: {p.get('pool_created_at', 'N/A')}",
-                ]
-                return {"formatted_output": "\n".join(lines)}
-            return {"formatted_output": "Pool not found."}
-
-        # ── Multiple pools ───────────────────────────────────────────
-        elif action == "multi_pools":
-            if not network or not pool_addresses:
-                raise ToolError(
-                    "'network' and 'pool_addresses' are required for action='multi_pools'"
-                )
-            addresses_str = ",".join(pool_addresses)
-            data = await _get(f"networks/{network}/pools/multi/{addresses_str}")
-            pools = _extract_pools(data)
-            return {
-                "formatted_output": f"Pools on {network} ({len(pools)}):\n\n{format_pools_table(pools)}"
-            }
-
-        # ── Pools by token ───────────────────────────────────────────
-        elif action == "token_pools":
-            if not network or not token_address:
-                raise ToolError(
-                    "'network' and 'token_address' are required for action='token_pools'"
-                )
-            data = await _get(f"networks/{network}/tokens/{token_address}/pools")
-            pools = _extract_pools(data)
-            return {
-                "formatted_output": f"Top Pools for token on {network} ({len(pools)}):\n\n{format_pools_table(pools)}"
-            }
-
-        # ── Token info ───────────────────────────────────────────────
-        elif action == "token_info":
-            if not network or not token_address:
-                raise ToolError(
-                    "'network' and 'token_address' are required for action='token_info'"
-                )
-            data = await _get(f"networks/{network}/tokens/{token_address}")
-            token_data = _extract_token_info(data)
-            return {"formatted_output": format_token_info(token_data)}
-
-        # ── OHLCV candles ────────────────────────────────────────────
-        elif action == "ohlcv":
-            if not network or not pool_address:
-                raise ToolError(
-                    "'network' and 'pool_address' are required for action='ohlcv'"
-                )
-            tf_unit, tf_period = _parse_timeframe(timeframe)
-            params: dict[str, Any] = {
-                "aggregate": tf_period,
-                "limit": limit,
-                "currency": currency,
-                "token": token,
-            }
-            if before_timestamp:
-                params["before_timestamp"] = before_timestamp
-            data = await _get(
-                f"networks/{network}/pools/{pool_address}/ohlcv/{tf_unit}",
-                params=params,
+    from handlers.dex.pool_data import gecko_request
+
+    async def _get(path: str, params: dict | None = None) -> dict:
+        """One call on this process's gecko budget.
+
+        NOTE: the gate in ``pool_data`` is per *process*, and this MCP server
+        runs as its own (``run_stdio_async``). So this bounds the tool's own
+        fan-out — 15 actions, some paginated — but cannot coordinate with the
+        bot process, which draws on the same per-IP limit. Genuinely sharing
+        one budget across both needs an out-of-process store.
+        """
+        return await gecko_request("GET", path, params=params)
+
+    # ── Networks ─────────────────────────────────────────────────
+    if action == "networks":
+        data = await _get("networks")
+        networks = _extract_networks(data)
+        return {
+            "formatted_output": f"Available Networks ({len(networks)}):\n\n{format_networks_table(networks)}"
+        }
+
+    # ── DEXes by network ─────────────────────────────────────────
+    elif action == "dexes":
+        if not network:
+            raise ToolError("'network' is required for action='dexes'")
+        data = await _get(f"networks/{network}/dexes")
+        dexes = _extract_dexes(data)
+        return {
+            "formatted_output": f"DEXes on {network} ({len(dexes)}):\n\n{format_dexes_table(dexes)}"
+        }
+
+    # ── Trending pools ───────────────────────────────────────────
+    elif action == "trending_pools":
+        if network:
+            data = await _get(f"networks/{network}/trending_pools")
+            title = f"Trending Pools on {network}"
+        else:
+            data = await _get("networks/trending_pools")
+            title = "Trending Pools (All Networks)"
+        pools = _extract_pools(data)
+        return {
+            "formatted_output": f"{title} ({len(pools)}):\n\n{format_pools_table(pools)}"
+        }
+
+    # ── Top pools ────────────────────────────────────────────────
+    elif action == "top_pools":
+        if not network:
+            raise ToolError("'network' is required for action='top_pools'")
+        if dex_id:
+            data = await _get(f"networks/{network}/dexes/{dex_id}/pools")
+            title = f"Top Pools on {network} / {dex_id}"
+        else:
+            data = await _get(f"networks/{network}/pools")
+            title = f"Top Pools on {network}"
+        pools = _extract_pools(data)
+        return {
+            "formatted_output": f"{title} ({len(pools)}):\n\n{format_pools_table(pools)}"
+        }
+
+    # ── New pools ────────────────────────────────────────────────
+    elif action == "new_pools":
+        if network:
+            data = await _get(f"networks/{network}/new_pools")
+            title = f"New Pools on {network}"
+        else:
+            data = await _get("networks/new_pools")
+            title = "New Pools (All Networks)"
+        pools = _extract_pools(data)
+        return {
+            "formatted_output": f"{title} ({len(pools)}):\n\n{format_pools_table(pools)}"
+        }
+
+    # ── Pool detail ──────────────────────────────────────────────
+    elif action == "pool_detail":
+        if not network or not pool_address:
+            raise ToolError(
+                "'network' and 'pool_address' are required for action='pool_detail'"
             )
-            candles = _extract_ohlcv(data)
-            # Sort by timestamp ascending and deduplicate
-            seen: set[int] = set()
-            unique = []
-            for c in candles:
-                if c["timestamp"] not in seen:
-                    seen.add(c["timestamp"])
-                    unique.append(c)
-            unique.sort(key=lambda x: x["timestamp"])
-            return {
-                "formatted_output": (
-                    f"OHLCV for pool {truncate_address(pool_address)} on {network} ({timeframe}, {len(unique)} candles):\n\n"
-                    f"{format_ohlcv_table(unique)}"
-                )
-            }
-
-        # ── Trades ───────────────────────────────────────────────────
-        elif action == "trades":
-            if not network or not pool_address:
-                raise ToolError(
-                    "'network' and 'pool_address' are required for action='trades'"
-                )
-            params = {}
-            if trade_volume_filter is not None:
-                params["trade_volume_in_usd_greater_than"] = trade_volume_filter
-            data = await _get(
-                f"networks/{network}/pools/{pool_address}/trades", params=params or None
+        data = await _get(f"networks/{network}/pools/{pool_address}")
+        pools = _extract_pools(data)
+        if pools:
+            p = pools[0]
+            lines = [
+                f"Pool: {p.get('name', 'N/A')}",
+                f"Address: {p.get('address', 'N/A')}",
+                f"DEX: {p.get('dex_id', 'N/A')}",
+                f"Base Token Price: {format_currency(p.get('base_token_price_usd'), decimals=6)}",
+                f"Quote Token Price: {format_currency(p.get('quote_token_price_usd'), decimals=6)}",
+                f"Reserve (USD): {format_number(p.get('reserve_in_usd'))}",
+                f"FDV: {format_number(p.get('fdv_usd'))}",
+                f"Market Cap: {format_number(p.get('market_cap_usd'))}",
+                f"24h Volume: {format_number(p.get('volume_h24'))}",
+                f"1h Change: {p.get('price_change_h1', 'N/A')}%",
+                f"24h Change: {p.get('price_change_h24', 'N/A')}%",
+                f"24h Txns: {p.get('txns_h24_buys', 'N/A')} buys / {p.get('txns_h24_sells', 'N/A')} sells",
+                f"Created: {p.get('pool_created_at', 'N/A')}",
+            ]
+            return {"formatted_output": "\n".join(lines)}
+        return {"formatted_output": "Pool not found."}
+
+    # ── Multiple pools ───────────────────────────────────────────
+    elif action == "multi_pools":
+        if not network or not pool_addresses:
+            raise ToolError(
+                "'network' and 'pool_addresses' are required for action='multi_pools'"
             )
-            trades = _extract_trades(data)
-            return {
-                "formatted_output": (
-                    f"Recent Trades for pool {truncate_address(pool_address)} on {network} ({len(trades)}):\n\n"
-                    f"{format_trades_table(trades)}"
-                )
-            }
+        addresses_str = ",".join(pool_addresses)
+        data = await _get(f"networks/{network}/pools/multi/{addresses_str}")
+        pools = _extract_pools(data)
+        return {
+            "formatted_output": f"Pools on {network} ({len(pools)}):\n\n{format_pools_table(pools)}"
+        }
 
-        else:
+    # ── Pools by token ───────────────────────────────────────────
+    elif action == "token_pools":
+        if not network or not token_address:
             raise ToolError(
-                f"Unknown action '{action}'. Available actions: networks, dexes, trending_pools, top_pools, "
-                f"new_pools, pool_detail, multi_pools, token_pools, token_info, ohlcv, trades"
+                "'network' and 'token_address' are required for action='token_pools'"
             )
+        data = await _get(f"networks/{network}/tokens/{token_address}/pools")
+        pools = _extract_pools(data)
+        return {
+            "formatted_output": f"Top Pools for token on {network} ({len(pools)}):\n\n{format_pools_table(pools)}"
+        }
+
+    # ── Token info ───────────────────────────────────────────────
+    elif action == "token_info":
+        if not network or not token_address:
+            raise ToolError(
+                "'network' and 'token_address' are required for action='token_info'"
+            )
+        data = await _get(f"networks/{network}/tokens/{token_address}")
+        token_data = _extract_token_info(data)
+        return {"formatted_output": format_token_info(token_data)}
+
+    # ── OHLCV candles ────────────────────────────────────────────
+    elif action == "ohlcv":
+        if not network or not pool_address:
+            raise ToolError(
+                "'network' and 'pool_address' are required for action='ohlcv'"
+            )
+        tf_unit, tf_period = _parse_timeframe(timeframe)
+        params: dict[str, Any] = {
+            "aggregate": tf_period,
+            "limit": limit,
+            "currency": currency,
+            "token": token,
+        }
+        if before_timestamp:
+            params["before_timestamp"] = before_timestamp
+        data = await _get(
+            f"networks/{network}/pools/{pool_address}/ohlcv/{tf_unit}",
+            params=params,
+        )
+        candles = _extract_ohlcv(data)
+        # Sort by timestamp ascending and deduplicate
+        seen: set[int] = set()
+        unique = []
+        for c in candles:
+            if c["timestamp"] not in seen:
+                seen.add(c["timestamp"])
+                unique.append(c)
+        unique.sort(key=lambda x: x["timestamp"])
+        return {
+            "formatted_output": (
+                f"OHLCV for pool {truncate_address(pool_address)} on {network} ({timeframe}, {len(unique)} candles):\n\n"
+                f"{format_ohlcv_table(unique)}"
+            )
+        }
+
+    # ── Trades ───────────────────────────────────────────────────
+    elif action == "trades":
+        if not network or not pool_address:
+            raise ToolError(
+                "'network' and 'pool_address' are required for action='trades'"
+            )
+        params = {}
+        if trade_volume_filter is not None:
+            params["trade_volume_in_usd_greater_than"] = trade_volume_filter
+        data = await _get(
+            f"networks/{network}/pools/{pool_address}/trades", params=params or None
+        )
+        trades = _extract_trades(data)
+        return {
+            "formatted_output": (
+                f"Recent Trades for pool {truncate_address(pool_address)} on {network} ({len(trades)}):\n\n"
+                f"{format_trades_table(trades)}"
+            )
+        }
+
+    else:
+        raise ToolError(
+            f"Unknown action '{action}'. Available actions: networks, dexes, trending_pools, top_pools, "
+            f"new_pools, pool_detail, multi_pools, token_pools, token_info, ohlcv, trades"
+        )
diff --git a/routines/mcap_comparison.py b/routines/mcap_comparison.py
index e4c77c00..5db6d352 100644
--- a/routines/mcap_comparison.py
+++ b/routines/mcap_comparison.py
@@ -67,11 +67,15 @@ def _fmt_pct(v: float) -> str:
     return f"{v:+.1f}%"
 
 
-async def _fetch_token_info(session: aiohttp.ClientSession, mint: str) -> dict:
-    """Fetch current token info (price, fdv, mcap) from GeckoTerminal."""
-    url = f"https://api.geckoterminal.com/api/v2/networks/solana/tokens/{mint}"
-    async with session.get(url) as resp:
-        data = await resp.json()
+async def _fetch_token_info(mint: str) -> dict:
+    """Fetch current token info (price, fdv, mcap) from GeckoTerminal.
+
+    On the process-wide gecko budget — the ~30/min free tier is per IP and shared
+    with the dashboard, so this routine cannot pace itself in isolation.
+    """
+    from handlers.dex.pool_data import gecko_request
+
+    data = await gecko_request("GET", f"networks/solana/tokens/{mint}")
     attrs = data.get("data", {}).get("attributes", {})
     price = float(attrs.get("price_usd") or 0)
     fdv = float(attrs.get("fdv_usd") or 0)
@@ -144,17 +148,18 @@ async def run(config: Config, context: ContextTypes.DEFAULT_TYPE) -> str:
 
     # Step 1: Fetch GeckoTerminal token info + DefiLlama fees (parallel, aiohttp)
     async with aiohttp.ClientSession() as session:
-        # Token info from GeckoTerminal (sequential — rate limits)
+        # Token info from GeckoTerminal. No hand-rolled sleep between calls: the
+        # shared gate paces these against every other caller in the process,
+        # which a local sleep cannot.
         for name, td in active_tokens.items():
             try:
-                token_info[name] = await _fetch_token_info(session, td["mint"])
+                token_info[name] = await _fetch_token_info(td["mint"])
                 logger.info(
                     f"{name}: price=${token_info[name]['price']:.4f}, mcap={_fmt_mcap(token_info[name]['mcap'])}"
                 )
             except Exception as e:
                 logger.warning(f"Failed to fetch token info for {name}: {e}")
                 token_info[name] = {"price": 0, "fdv": 0, "mcap": 0}
-            await asyncio.sleep(1)
 
         # DefiLlama fees (parallel — no rate limit issues)
         fee_tasks = {
diff --git a/routines/solana_pool_scanner.py b/routines/solana_pool_scanner.py
index b87439b8..00d80c1e 100644
--- a/routines/solana_pool_scanner.py
+++ b/routines/solana_pool_scanner.py
@@ -6,13 +6,11 @@
 import re
 from typing import Optional
 
-import aiohttp
 from pydantic import BaseModel, Field
 from telegram.ext import ContextTypes
 
 logger = logging.getLogger(__name__)
 
-GECKO_BASE = "https://api.geckoterminal.com/api/v2"
 NETWORK = "solana"
 PAGES_PER_DEX = 3
 
@@ -50,30 +48,30 @@ class Config(BaseModel):
     )
 
 
-async def _fetch_pools_page(
-    session: aiohttp.ClientSession, dex_id: str, page: int
-) -> list[dict]:
-    url = f"{GECKO_BASE}/networks/{NETWORK}/dexes/{dex_id}/pools"
-    params = {"page": str(page)}
+async def _fetch_pools_page(dex_id: str, page: int) -> list[dict]:
+    """One page of a venue's pools, on the process-wide gecko budget.
+
+    ``dex_ids × pages`` requests fan out from here, so this is the caller most
+    able to exhaust the ~30/min the whole process shares — hence the shared gate
+    rather than a session of its own.
+    """
+    from handlers.dex.pool_data import gecko_request
+
     try:
-        async with session.get(
-            url, params=params, timeout=aiohttp.ClientTimeout(total=15)
-        ) as resp:
-            if resp.status != 200:
-                logger.warning(f"GeckoTerminal {dex_id} p{page}: HTTP {resp.status}")
-                return []
-            body = await resp.json()
-            return body.get("data", [])
+        body = await gecko_request(
+            "GET",
+            f"networks/{NETWORK}/dexes/{dex_id}/pools",
+            params={"page": str(page)},
+        )
+        return body.get("data", [])
     except Exception as e:
         logger.warning(f"GeckoTerminal {dex_id} p{page} failed: {e}")
         return []
 
 
-async def _fetch_all_pools(
-    session: aiohttp.ClientSession, dex_ids: list[str], pages: int
-) -> list[dict]:
+async def _fetch_all_pools(dex_ids: list[str], pages: int) -> list[dict]:
     tasks = [
-        _fetch_pools_page(session, dex_id, page)
+        _fetch_pools_page(dex_id, page)
         for dex_id in dex_ids
         for page in range(1, pages + 1)
     ]
@@ -308,8 +306,7 @@ async def run(config: Config, context: ContextTypes.DEFAULT_TYPE) -> str:
     else:
         dex_ids = [did for ids in DEX_IDS.values() for did in ids]
 
-    async with aiohttp.ClientSession() as session:
-        raw_pools = await _fetch_all_pools(session, dex_ids, config.pages)
+    raw_pools = await _fetch_all_pools(dex_ids, config.pages)
 
     all_pools = [p for raw in raw_pools if (p := _parse_pool(raw))]
 
diff --git a/tests/test_gecko_throttle.py b/tests/test_gecko_throttle.py
new file mode 100644
index 00000000..4428ad48
--- /dev/null
+++ b/tests/test_gecko_throttle.py
@@ -0,0 +1,277 @@
+"""The shared GeckoTerminal budget: rate gate, circuit breaker, single-flight.
+
+GeckoTerminal's free tier is ~30 requests/minute *per IP*, and every dashboard
+viewer, the candle poll loop and the pool explorer draw on that one budget. The
+symptom when it runs out is not an error — every caller in ``pool_data`` degrades
+to an empty list — so a blown budget looks exactly like a chain with no pools.
+These cover the three guards that keep it from blowing, and the accounting that
+makes it visible when it does.
+"""
+
+import asyncio
+import re
+from pathlib import Path
+
+import pytest
+
+from handlers.dex import pool_data
+
+
+def run(coro):
+    """Drive a coroutine to completion (the suite has no async plugin)."""
+    return asyncio.run(coro)
+
+
+class _Counting:
+    """A gecko client that records calls instead of making them."""
+
+    def __init__(self, result=None, error=None, delay=0.0):
+        self.calls = 0
+        self._result = result if result is not None else {"data": []}
+        self._error = error
+        self._delay = delay
+
+    async def api_request(self, *_a, **_k):
+        return await self._answer()
+
+    async def get_pool_by_network_address(self, *_a, **_k):
+        return await self._answer()
+
+    async def _answer(self):
+        self.calls += 1
+        if self._delay:
+            await asyncio.sleep(self._delay)
+        if self._error is not None:
+            raise self._error
+        return self._result
+
+
+# ── Rate gate ──
+
+
+def test_the_budget_is_spent_and_then_refused(monkeypatch):
+    """Past the per-minute budget a caller is refused rather than queued forever.
+
+    A concurrency cap alone never did this: four *fast* concurrent requests
+    sustain well over 100/min without ever looking like a burst.
+    """
+    client = _Counting()
+    monkeypatch.setattr(pool_data, "_gecko_client", lambda: client)
+    monkeypatch.setattr(pool_data, "_GECKO_RATE_LIMIT", 3)
+    # Don't queue for a slot — fail fast so the test does not sleep a minute.
+    monkeypatch.setattr(pool_data, "_GECKO_MAX_WAIT", 0.0)
+
+    async def drive():
+        for _ in range(3):
+            await pool_data.gecko_request("GET", "networks/solana/pools")
+        with pytest.raises(pool_data.GeckoRateLimited):
+            await pool_data.gecko_request("GET", "networks/solana/pools")
+
+    run(drive())
+    assert client.calls == 3, "the refused call must not reach the wire"
+
+
+def test_a_refusal_is_recognized_as_a_rate_limit():
+    """Callers already branch on ``_is_rate_limited``; the local refusal must
+    read the same as gecko's own 429 so none of them need a second code path."""
+    assert pool_data._is_rate_limited(pool_data.GeckoRateLimited("no budget left"))
+
+
+# ── Circuit breaker ──
+
+
+def test_a_429_stops_the_next_call_entirely(monkeypatch):
+    """Requests sent inside a throttled window are spent for nothing and keep the
+    window rolling, so the cheapest response to a 429 is silence."""
+    client = _Counting(error=RuntimeError("429 Too Many Requests"))
+    monkeypatch.setattr(pool_data, "_gecko_client", lambda: client)
+
+    async def drive():
+        with pytest.raises(RuntimeError):
+            await pool_data.gecko_request("GET", "networks/solana/pools")
+        with pytest.raises(pool_data.GeckoRateLimited):
+            await pool_data.gecko_request("GET", "networks/solana/pools")
+
+    run(drive())
+    assert client.calls == 1
+
+
+def test_a_429_is_never_retried(monkeypatch):
+    """Gecko's limit is a per-minute window; no backoff short enough to sit
+    inside a web request clears it, and a retry only spends more of the budget."""
+    client = _Counting(error=RuntimeError("429 Too Many Requests"))
+    monkeypatch.setattr(pool_data, "_gecko_client", lambda: client)
+
+    async def drive():
+        with pytest.raises(RuntimeError):
+            await pool_data.gecko_request("GET", "networks/solana/pools")
+
+    run(drive())
+    assert client.calls == 1
+
+
+def test_a_timeout_is_retried(monkeypatch):
+    """A slow chain listing is not a throttled one — that one is worth retrying."""
+    import httpx
+
+    client = _Counting(error=httpx.ReadTimeout("slow"))
+    monkeypatch.setattr(pool_data, "_gecko_client", lambda: client)
+    monkeypatch.setattr(pool_data, "_GECKO_BACKOFF", (0.0, 0.0))
+
+    async def drive():
+        with pytest.raises(httpx.ReadTimeout):
+            await pool_data.gecko_request("GET", "networks/solana/pools")
+
+    run(drive())
+    assert client.calls == pool_data._GECKO_RETRIES + 1
+
+
+def test_the_breaker_reports_itself(monkeypatch):
+    """ "Are we rate limited?" must have an answer that is not "read the logs"."""
+    client = _Counting(error=RuntimeError("429 Too Many Requests"))
+    monkeypatch.setattr(pool_data, "_gecko_client", lambda: client)
+
+    assert pool_data.gecko_health()["rate_limited"] is False
+
+    async def drive():
+        with pytest.raises(RuntimeError):
+            await pool_data.gecko_request("GET", "networks/solana/pools")
+
+    run(drive())
+
+    health = pool_data.gecko_health()
+    assert health["rate_limited"] is True
+    assert health["count_429"] == 1
+    assert 0 < health["cooldown_remaining"] <= pool_data._GECKO_COOLDOWN
+    assert health["last_429_age"] is not None
+
+
+def test_health_counts_the_budget_spent(monkeypatch):
+    client = _Counting()
+    monkeypatch.setattr(pool_data, "_gecko_client", lambda: client)
+
+    async def drive():
+        for _ in range(3):
+            await pool_data.gecko_request("GET", "networks/solana/pools")
+
+    run(drive())
+    assert pool_data.gecko_health()["requests_last_minute"] == 3
+
+
+# ── Single-flight ──
+
+
+def test_concurrent_askers_for_one_page_share_one_request(monkeypatch):
+    """Flicking between explorer tabs re-asks for a listing while the first
+    request is still in the air, so a TTL cache — written only on arrival —
+    cannot help. Without this, four fast clicks are four upstream requests."""
+    client = _Counting(delay=0.05)
+    monkeypatch.setattr(pool_data, "_gecko_client", lambda: client)
+
+    async def drive():
+        return await asyncio.gather(
+            *(pool_data._gecko_page_rows("solana", "trending", "", 1) for _ in range(6))
+        )
+
+    results = run(drive())
+    assert client.calls == 1
+    assert all(r == [] for r in results)
+
+
+def test_each_sharer_gets_its_own_rows(monkeypatch):
+    """The shared answer is one list object; a caller mutating its copy — the
+    explorer decorates rows per network — must not corrupt the others."""
+    rows = [{"id": "solana_abc", "address": "abc"}]
+    client = _Counting(result={"data": [{"id": "solana_abc", "attributes": {}}]})
+    monkeypatch.setattr(pool_data, "_gecko_client", lambda: client)
+    monkeypatch.setattr(pool_data, "glom", lambda _payload, _spec: list(rows))
+
+    async def drive():
+        return await asyncio.gather(
+            *(pool_data._gecko_page_rows("solana", "trending", "", 1) for _ in range(3))
+        )
+
+    a, b, _c = run(drive())
+    assert a is not b
+    a[0]["address"] = "mutated"
+    assert b[0]["address"] == "abc"
+
+
+def test_a_caller_walking_away_does_not_cancel_the_shared_fetch(monkeypatch):
+    """The stampede's own cause — a viewer navigating away mid-request — must not
+    take down the fetch the viewers who stayed are waiting on."""
+    client = _Counting(delay=0.05)
+    monkeypatch.setattr(pool_data, "_gecko_client", lambda: client)
+
+    async def drive():
+        leaver = asyncio.ensure_future(
+            pool_data._gecko_page_rows("solana", "top", "", 1)
+        )
+        stayer = asyncio.ensure_future(
+            pool_data._gecko_page_rows("solana", "top", "", 1)
+        )
+        await asyncio.sleep(0.01)
+        leaver.cancel()
+        return await stayer
+
+    assert run(drive()) == []
+    assert client.calls == 1
+
+
+# ── The gate is the only door ──
+
+
+def test_no_gecko_call_bypasses_the_budget():
+    """Every outbound request goes through ``gecko_call``. Calling the client
+    directly skips the rate gate — which is how the candle poll loop, the highest
+    frequency caller in the process, used to exhaust the budget while the guards
+    sat in front of two pool-list walks.
+    """
+    source = Path(pool_data.__file__).read_text()
+    # The one legitimate use is inside gecko_call itself, which resolves the
+    # method by name so tests can swap the client.
+    direct = re.findall(r"_gecko_client\(\)\.\w+", source)
+    assert direct == [], f"these bypass the rate gate: {direct}"
+
+
+# Everything below the repo root except pool_data.py, which owns the client.
+_REPO = Path(pool_data.__file__).resolve().parents[2]
+_SKIP = {".venv", ".git", "node_modules", "__pycache__", "dist", "build"}
+
+
+def _repo_sources():
+    for path in _REPO.rglob("*.py"):
+        if _SKIP & set(path.parts):
+            continue
+        if path.name == "pool_data.py" or path.parts[-2:] == (
+            "tests",
+            Path(__file__).name,
+        ):
+            continue
+        yield path
+
+
+def test_pool_data_is_the_only_owner_of_a_gecko_client():
+    """A second ``GeckoTerminalAsyncClient()`` anywhere is two bugs at once.
+
+    It bypasses the shared budget *and* — since none of the old call sites ever
+    called ``close()`` — leaks an httpx client per invocation, which is how a
+    process runs out of file descriptors rather than merely out of quota.
+    """
+    offenders = [
+        str(p.relative_to(_REPO))
+        for p in _repo_sources()
+        if "GeckoTerminalAsyncClient()" in p.read_text()
+    ]
+    assert offenders == [], f"construct clients outside pool_data: {offenders}"
+
+
+def test_nobody_hand_builds_a_geckoterminal_url():
+    """A hand-rolled ``api.geckoterminal.com`` URL is a request the gate never
+    sees. Routines and MCP tools reach the same per-IP limit as the dashboard."""
+    offenders = [
+        str(p.relative_to(_REPO))
+        for p in _repo_sources()
+        if "api.geckoterminal.com" in p.read_text()
+    ]
+    assert offenders == [], f"bypass the rate gate with a raw URL: {offenders}"

From cbdb5ab70ccebd4749fface9a00288bd7bf3f6c5 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Mon, 17 Aug 2026 14:09:59 +0300
Subject: [PATCH 102/116] (feat) Orca is its own pool source, not Gateway's
 proxy of it
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Gateway's Orca listing nulls the volume, fees and price that make a pool
worth judging, and its pagination is stuck on page one. Orca's own v2 API
answers with all of it, plus the whole ranked set in hand — so has_more is
exact there, where gecko and Gateway can only infer it from a full page.

Adds source=orca to /dex/pools alongside gecko and gateway, reading through
orca_api and normalizing whirlpool rows into the shared pool shape. Where
Orca reports no realized fees, the yield is derived from volume and the fee
tier rather than left blank.

Gateway stays the fallback when Orca is rate-limiting: a degraded row beats
an empty table, and the browser's empty state is something a user can act
on where a 502 is not.
---
 condor/web/routes/dex.py                    |  43 +++-
 frontend/src/components/dex/PoolBrowser.tsx |  21 +-
 frontend/src/pages/Dex.tsx                  |  11 +-
 frontend/src/pages/DexPool.tsx              |  41 +++-
 handlers/dex/orca_api.py                    | 121 ++++++++++
 handlers/dex/pool_data.py                   | 250 ++++++++++++++++++++
 tests/test_dex_pool_discovery.py            | 234 ++++++++++++++++++
 7 files changed, 705 insertions(+), 16 deletions(-)
 create mode 100644 handlers/dex/orca_api.py

diff --git a/condor/web/routes/dex.py b/condor/web/routes/dex.py
index afe96458..b83ff2f4 100644
--- a/condor/web/routes/dex.py
+++ b/condor/web/routes/dex.py
@@ -68,7 +68,8 @@ async def list_pools(
     name: str,
     source: str = Query(
         default="gecko",
-        description="'gecko' (a chain's trending/top/new pools, or a token's) or "
+        description="'gecko' (a chain's trending/top/new pools, or a token's), "
+        "'orca' (Orca's own whirlpool API, with realized fees and yield) or "
         "'gateway' (a CLMM connector's own listing, with APR and bin step)",
     ),
     network: str = Query(
@@ -95,26 +96,48 @@ async def list_pools(
     page: int = Query(default=1, ge=1, description="1-based page of `limit` rows"),
     user: WebUser = Depends(require_server_access),
 ):
-    """Pools to browse, from one of the two upstreams.
+    """Pools to browse, from one of the three upstreams.
 
-    ``source`` is the discriminator because the two take genuinely different
-    arguments — gecko searches by *token address* on a chain, Gateway searches free
-    text within a connector — and one merged parameter set would mean documenting
-    which combinations are meaningless.
+    ``source`` is the discriminator because they take genuinely different arguments
+    — gecko searches by *token address* on a chain, Gateway and Orca search free
+    text within a venue — and one merged parameter set would mean documenting which
+    combinations are meaningless.
 
     An upstream failure answers ``{"pools": []}`` with a warning, like
     ``/market/venues``: the browser's empty state is something the user can act on,
-    a 502 is not.
+    a 502 is not. ``source=orca`` falls back to Gateway before it comes to that.
 
-    ``has_more`` — not a total — is what the browser's Next needs, and a total is
-    something neither upstream reports.
+    ``has_more`` — not a total — is what the browser's Next needs. Orca answers it
+    exactly, having the whole ranked set in hand; Gateway and gecko report no total,
+    so there a full page is the only evidence of another.
     """
     cm = get_config_manager()
 
-    from handlers.dex.pool_data import list_gateway_pools, list_gecko_pools_page
+    from handlers.dex.pool_data import (
+        list_gateway_pools,
+        list_gecko_pools_page,
+        list_orca_pools,
+    )
 
     source = (source or "gecko").strip().lower()
 
+    if source == "orca":
+        # Orca's own API, not Gateway's proxy of it: same pools, but with the
+        # volume, fees, price and yield the proxy nulls, and with pagination that
+        # is not stuck on page one. Gateway stays the fallback for when Orca is
+        # rate-limiting — a degraded row beats an empty table.
+        paged = await list_orca_pools(search=query, limit=limit, page=page)
+        if paged is not None:
+            pools, has_more = paged
+            return {
+                "pools": pools,
+                "source": source,
+                "page": page,
+                "has_more": has_more,
+            }
+        logger.warning("Orca API unavailable for %s; falling back to Gateway", name)
+        connector, source = "orca", "gateway"
+
     if source == "gateway":
         try:
             client = await cm.get_client(name)
diff --git a/frontend/src/components/dex/PoolBrowser.tsx b/frontend/src/components/dex/PoolBrowser.tsx
index 3c70ff0f..5da202c3 100644
--- a/frontend/src/components/dex/PoolBrowser.tsx
+++ b/frontend/src/components/dex/PoolBrowser.tsx
@@ -54,6 +54,11 @@ function sortValue(p: PoolSummary, key: SortKey): number {
   return num(p[key as keyof PoolSummary]) ?? -Infinity;
 }
 
+/** Orca's Gateway listing carries no yield at all; the backend derives one. */
+const ESTIMATED_YIELD_HINT =
+  "Estimated: 24h volume x the pool's base fee tier, over TVL. " +
+  "This connector reports no yield of its own.";
+
 function pairLabel(p: PoolSummary): string {
   const base = p.base_symbol && p.base_symbol !== "???" ? p.base_symbol : null;
   const quote =
@@ -261,7 +266,7 @@ export function PoolBrowser({
                     sortDir={sortDir}
                     onSort={handleSort}
                     align="right"
-                    title="Last 24h of fees over TVL, as the connector reports it"
+                    title="Last 24h of fees over TVL. A ~ marks a figure derived from volume and the fee tier because the connector reports none."
                   />
                   <SortTh
                     label="APY"
@@ -270,7 +275,7 @@ export function PoolBrowser({
                     sortDir={sortDir}
                     onSort={handleSort}
                     align="right"
-                    title="The connector's annualized yield"
+                    title="Annualized yield. A ~ marks a figure derived from volume and the fee tier because the connector reports none."
                   />
                   <th className="px-4 py-3 text-right text-xs font-medium uppercase tracking-wider text-[var(--color-text-muted)]">
                     Bin
@@ -358,10 +363,18 @@ export function PoolBrowser({
                   </td>
                   {showGatewayColumns && (
                     <>
-                      <td className="px-4 py-2.5 text-right tabular-nums">
+                      <td
+                        className="px-4 py-2.5 text-right tabular-nums"
+                        title={p.apr_estimated ? ESTIMATED_YIELD_HINT : undefined}
+                      >
+                        {p.apr_estimated && p.apr != null ? "~" : ""}
                         {pct(p.apr)}
                       </td>
-                      <td className="px-4 py-2.5 text-right tabular-nums">
+                      <td
+                        className="px-4 py-2.5 text-right tabular-nums"
+                        title={p.apr_estimated ? ESTIMATED_YIELD_HINT : undefined}
+                      >
+                        {p.apr_estimated && p.apy != null ? "~" : ""}
                         {pct(p.apy)}
                       </td>
                       <td className="px-4 py-2.5 text-right tabular-nums text-[var(--color-text-muted)]">
diff --git a/frontend/src/pages/Dex.tsx b/frontend/src/pages/Dex.tsx
index 6cfc8f00..67acf517 100644
--- a/frontend/src/pages/Dex.tsx
+++ b/frontend/src/pages/Dex.tsx
@@ -4,6 +4,7 @@ import { useEffect, useMemo, useState } from "react";
 import { useNavigate } from "react-router-dom";
 
 import { NoServerCard } from "@/components/NoServerCard";
+import { LpPositions } from "@/components/dex/LpPositions";
 import { PoolBrowser } from "@/components/dex/PoolBrowser";
 import {
   type PoolSource,
@@ -146,7 +147,10 @@ export function Dex() {
         server!,
         source.kind === "gateway"
           ? {
-              source: "gateway",
+              // Orca is read from its own API rather than through Gateway, which
+              // proxies it and drops volume, fees, price and yield on the way.
+              // Same tab, same columns — filled in rather than em-dashed.
+              source: source.connector === "orca" ? "orca" : "gateway",
               connector: source.connector,
               query: debouncedQuery || undefined,
               limit: PAGE_SIZE,
@@ -224,6 +228,11 @@ export function Dex() {
         </p>
       </div>
 
+      {/* Above the browser, because getting back to a pool you are already in is
+          a shorter errand than finding a new one — and it renders nothing when
+          there is nothing to get back to. */}
+      <LpPositions server={server} />
+
       <div className="overflow-hidden rounded-lg border border-[var(--color-border)]">
         <PoolSourceTabs
           source={source}
diff --git a/frontend/src/pages/DexPool.tsx b/frontend/src/pages/DexPool.tsx
index 2d32a0fe..04a509da 100644
--- a/frontend/src/pages/DexPool.tsx
+++ b/frontend/src/pages/DexPool.tsx
@@ -5,6 +5,7 @@ import { useNavigate, useParams } from "react-router-dom";
 
 import { NoServerCard } from "@/components/NoServerCard";
 import { LiquidityDepthColumn } from "@/components/dex/LiquidityDepthColumn";
+import { LpPositionBar } from "@/components/dex/LpPositionBar";
 import { PoolStats } from "@/components/dex/PoolStats";
 import {
   LPConfigPanel,
@@ -17,6 +18,7 @@ import {
 import { TradeBottomPane } from "@/components/trade/TradeBottomPane";
 import { TradeChart, type ChartPriceAxis } from "@/components/trade/TradeChart";
 import { useMainControllerData } from "@/hooks/useMainControllerData";
+import { usePairBalances } from "@/hooks/usePairBalances";
 import { useResizeDrag } from "@/hooks/useResizeDrag";
 import { useServer } from "@/hooks/useServer";
 import { api } from "@/lib/api";
@@ -130,6 +132,15 @@ export function DexPool() {
   const pair = pool?.trading_pair ?? "";
   const lpAvailable = caps.supportsLp && !!pool?.lp_supported;
 
+  // `pair` is the executor's `<base_mint>-<quote_symbol>` form. The tickers only
+  // exist on the pool, so every symbol-shaped consumer — balance lookups, amount
+  // labels — is handed them rather than left to split the pair.
+  const baseSymbol =
+    pool?.base_symbol && pool.base_symbol !== "???" ? pool.base_symbol : undefined;
+  const quoteSymbol =
+    pool?.quote_symbol && pool.quote_symbol !== "???" ? pool.quote_symbol : undefined;
+  const balances = usePairBalances(server ?? null, network, baseSymbol, quoteSymbol);
+
   const orderConfig = useOrderConfig();
   const lpConfig = useLpConfig(server ?? null, network, pair, lpAvailable);
 
@@ -154,8 +165,18 @@ export function DexPool() {
   // and the pool is only known after the fetch resolves.
   const tab: Tab = wantedTab === "lp" && !lpAvailable ? "order" : wantedTab;
 
+  // An executor opened from here is filed under `<base_mint>-<quote>`, but the
+  // same position opened from Telegram or MCP is filed under `<base>-<quote>`.
+  // Both name this pool, so both are asked for; `pool.address` then keeps the
+  // answer to the pool actually on screen.
+  const symbolPair =
+    baseSymbol && quoteSymbol ? `${baseSymbol}-${quoteSymbol}` : "";
+
   const { executors, overlays, positions, isLoadingPositions } =
-    useMainControllerData(server ?? null, network, pair);
+    useMainControllerData(server ?? null, network, pair, {
+      altPair: symbolPair,
+      poolAddress: pool?.address,
+    });
 
   const active = tab === "lp" ? lpConfig : orderConfig;
   const currentPrice = pool?.current_price ?? null;
@@ -287,6 +308,14 @@ export function DexPool() {
 
       <div className="flex min-h-0 flex-1">
         <div className="flex min-w-0 flex-1 flex-col">
+          {/* What you already hold here, above the chart that shows where it sits */}
+          <LpPositionBar
+            executors={executors}
+            currentPrice={currentPrice}
+            selectedExecutorId={selectedExecutorId}
+            onSelect={(id) => setSelectedExecutorId((prev) => (prev === id ? null : id))}
+          />
+
           <div className="flex min-h-0 flex-1">
             <div className="min-h-0 min-w-0 flex-1 overflow-hidden">
             <TradeChart
@@ -367,6 +396,8 @@ export function DexPool() {
               connector={network}
               pair={pair}
               isSpot
+              baseSymbol={baseSymbol}
+              quoteSymbol={quoteSymbol}
               selectedExecutorId={selectedExecutorId}
               onExecutorSelect={(ex) => setSelectedExecutorId(ex?.id ?? null)}
             />
@@ -431,6 +462,10 @@ export function DexPool() {
                 isSpot
                 pair={pairLabel}
                 strategies={caps.orderStrategies}
+                baseAvailable={balances.base}
+                quoteAvailable={balances.quote}
+                baseSymbol={baseSymbol}
+                quoteSymbol={quoteSymbol}
               />
             ) : (
               <LPConfigPanel
@@ -441,6 +476,10 @@ export function DexPool() {
                 pair={pairLabel}
                 pool={lpConfig.pool}
                 poolFetching={lpConfig.poolFetching}
+                baseAvailable={balances.base}
+                quoteAvailable={balances.quote}
+                baseSymbol={baseSymbol}
+                quoteSymbol={quoteSymbol}
               />
             )}
           </div>
diff --git a/handlers/dex/orca_api.py b/handlers/dex/orca_api.py
new file mode 100644
index 00000000..8e48022d
--- /dev/null
+++ b/handlers/dex/orca_api.py
@@ -0,0 +1,121 @@
+"""Orca's public whirlpool API — the single module that talks to api.orca.so.
+
+Gateway can already list Orca's pools, but only as a thin proxy over *this* API
+that drops almost everything on the way: it answers TVL, fee tier and tick spacing
+and nulls `volume_24h`, `fees_24h`, `apr`, `apy` and `current_price`, so the browser
+had to make a second trip to GeckoTerminal for volume and then *estimate* the fee
+yield from volume times the base tier. It also ignores its `page` argument for this
+connector, so every page of the Orca tab was page one.
+
+Reading Orca directly answers all of it in one request, with real fees (rewards
+included) rather than an estimate, and with pagination that works.
+
+Public and unauthenticated, but Cloudflare-fronted: a request with no or a
+default-library User-Agent is answered 403, so one is always sent.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+ORCA_API_BASE = "https://api.orca.so/v2/solana"
+
+# `Python-urllib/x` is 403'd by Cloudflare outright. Identifying the caller is the
+# courteous thing to do against a free public API in any case.
+_USER_AGENT = "condor-dex-browser/1.0 (+https://github.com/hummingbot)"
+
+# The browser is waiting on this: a slow listing is better abandoned and served
+# from the stale cache than held open.
+_TIMEOUT = httpx.Timeout(15.0, connect=5.0)
+
+# One client, and so one connection pool — the same reason ``pool_data`` keeps a
+# single GeckoTerminal client. Kept with the loop it was built on: a pooled
+# connection belongs to that loop, and reusing it from another one fails with
+# "Event loop is closed" rather than reconnecting. The web app is one long-lived
+# loop, but a routine or a test driving this through ``asyncio.run`` is not.
+_client: Optional[httpx.AsyncClient] = None
+_client_loop: Optional[asyncio.AbstractEventLoop] = None
+
+
+def _http() -> httpx.AsyncClient:
+    global _client, _client_loop
+    loop = asyncio.get_running_loop()
+    if _client is None or _client.is_closed or _client_loop is not loop:
+        # The previous client's connections died with its loop; there is nothing
+        # left to close, so the reference is simply dropped.
+        _client = httpx.AsyncClient(
+            base_url=ORCA_API_BASE,
+            timeout=_TIMEOUT,
+            headers={"User-Agent": _USER_AGENT, "Accept": "application/json"},
+        )
+        _client_loop = loop
+    return _client
+
+
+async def _get(path: str, params: Dict[str, Any]) -> Any:
+    response = await _http().get(path, params=params)
+    response.raise_for_status()
+    return response.json()
+
+
+def _rows(payload: Any) -> List[Dict[str, Any]]:
+    """The whirlpool rows out of Orca's ``{"data": [...], "meta": {...}}`` envelope."""
+    data = payload.get("data") if isinstance(payload, dict) else payload
+    if isinstance(data, dict):  # a single-pool response
+        data = [data]
+    if not isinstance(data, list):
+        return []
+    return [row for row in data if isinstance(row, dict)]
+
+
+async def fetch_whirlpools(
+    size: int,
+    search: Optional[str] = None,
+    sort_by: str = "tvl",
+    sort_direction: str = "desc",
+    stats: str = "24h",
+) -> List[Dict[str, Any]]:
+    """Up to ``size`` whirlpools, ranked, as raw Orca rows.
+
+    One request rather than a cursor walk. Orca lists over 8,000 whirlpools but
+    fewer than ~500 of them hold more than $10k, and ranking by TVL puts those
+    first — so a single page covers everything the browser would page through,
+    which is also what lets the caller keep offset pagination over a cursor-only
+    upstream.
+
+    ``stats`` picks which time windows to hydrate; only the ones actually rendered
+    are asked for, since the default hydrates 24h, 7d and 30d for every row.
+
+    Raises on an upstream failure rather than returning ``[]``: a 429 and a chain
+    with no pools are different answers, and only the caller knows whether it has
+    a stale copy to fall back on.
+    """
+    params: Dict[str, Any] = {
+        "size": max(1, int(size)),
+        "sortBy": sort_by,
+        "sortDirection": sort_direction,
+        "stats": stats,
+    }
+    search = (search or "").strip()
+    if search:
+        # A different endpoint, because /pools filters by mint and this matches
+        # free text against symbols and addresses — which is what the tab's search
+        # box offers.
+        params["q"] = search
+        return _rows(await _get("/pools/search", params))
+    return _rows(await _get("/pools", params))
+
+
+async def close() -> None:
+    """Release the connection pool. For tests and shutdown."""
+    global _client, _client_loop
+    if _client is not None and not _client.is_closed:
+        await _client.aclose()
+    _client = None
+    _client_loop = None
diff --git a/handlers/dex/pool_data.py b/handlers/dex/pool_data.py
index db8b6f00..9edf8b2d 100644
--- a/handlers/dex/pool_data.py
+++ b/handlers/dex/pool_data.py
@@ -27,6 +27,7 @@
 
 from config_manager import get_client
 
+from . import orca_api
 from ._shared import evict_expired, get_cached, set_cached
 
 logger = logging.getLogger(__name__)
@@ -169,6 +170,10 @@
 # candle poll loop of the same budget.
 POOL_LIST_TTL = 60  # gecko trending/top/new/token lists
 GATEWAY_POOL_LIST_TTL = 30  # gateway CLMM lists, per (connector, search)
+# One Orca snapshot serves every page and every column sort of the Orca tab, so
+# this is a whole tab's upstream budget rather than one page's — cheaper than the
+# Gateway path it replaces, which spent a request per page and a gecko one on top.
+ORCA_POOL_LIST_TTL = 60
 
 # GeckoTerminal's OHLCV endpoint only accepts these aggregates, and its client
 # raises ValueError on anything else. Charts pick their own interval, so map an
@@ -1290,9 +1295,92 @@ def normalize_pool_data(pool: dict, source: str = "gecko") -> Dict[str, Any]:
             "source": "gateway",
         }
 
+    elif source == "orca":
+        return _normalize_orca_whirlpool(pool)
+
     return pool
 
 
+# Orca states a fee tier in millionths of the trade: 400 is 0.04%.
+_ORCA_FEE_RATE_DENOMINATOR = 10_000
+
+
+def _normalize_orca_whirlpool(pool: dict) -> Dict[str, Any]:
+    """One raw ``api.orca.so`` whirlpool → the same shape the other sources produce.
+
+    Every figure Gateway's Orca listing leaves null is present here, so unlike a
+    Gateway row this one needs no GeckoTerminal backfill and no estimated yield:
+    ``apr`` is Orca's own realized fees (rewards included) over TVL, not volume
+    times the base tier.
+    """
+    token_a = pool.get("tokenA") if isinstance(pool.get("tokenA"), dict) else {}
+    token_b = pool.get("tokenB") if isinstance(pool.get("tokenB"), dict) else {}
+    stats = pool.get("stats") if isinstance(pool.get("stats"), dict) else {}
+    day = stats.get("24h") if isinstance(stats.get("24h"), dict) else {}
+
+    base_symbol = str(token_a.get("symbol") or "???")
+    quote_symbol = str(token_b.get("symbol") or "???")
+    mint_a = str(pool.get("tokenMintA") or token_a.get("address") or "")
+    mint_b = str(pool.get("tokenMintB") or token_b.get("address") or "")
+
+    fee_rate = _finite(pool.get("feeRate"))
+    info: Dict[str, Any] = {
+        "address": str(pool.get("address") or ""),
+        "name": f"{base_symbol}-{quote_symbol}",
+        "base_token_symbol": base_symbol,
+        "quote_token_symbol": quote_symbol,
+        "base_token_address": mint_a,
+        "quote_token_address": mint_b,
+        # Carried under the Gateway row's names too, so a consumer that already
+        # reads a CLMM pool's mints does not need to know which source it came from.
+        "mint_x": mint_a,
+        "mint_y": mint_b,
+        "base_token_price_usd": None,
+        "quote_token_price_usd": None,
+        "network": "solana",
+        "dex_id": "orca",
+        "reserve_usd": pool.get("tvlUsdc"),
+        "current_price": pool.get("price"),
+        # Orca's tick spacing sits in the column Meteora's bin step does: both are
+        # "how finely can I place a position in this pool".
+        "bin_step": pool.get("tickSpacing"),
+        "base_fee_percentage": (
+            fee_rate / _ORCA_FEE_RATE_DENOMINATOR if fee_rate is not None else None
+        ),
+        "volume_24h": day.get("volume"),
+        "fees_24h": day.get("fees"),
+        # Orca reports deltas as ratios (-0.05 = -5%); the table renders percents.
+        "price_change_24h": _scale_ratio(day.get("priceDelta")),
+        "source": "orca",
+    }
+
+    # Fees *and* rewards over TVL, which is the number Orca's own UI shows — a
+    # reward-heavy pool's real yield is not its fee yield.
+    daily = _finite(day.get("yieldOverTvl"))
+    if daily is None:
+        daily = _finite(pool.get("yieldOverTvl"))
+    # Always present, even as None, so an Orca row and a Gateway one have the same
+    # keys and a consumer never has to ask which source it is holding.
+    info["apr"] = daily * 100 if daily is not None else None
+    info["apy"] = (
+        ((1 + daily) ** _DAYS_PER_YEAR - 1) * 100 if daily is not None else None
+    )
+    # Not estimated: no ``~`` on either column.
+    info["apr_estimated"] = False
+
+    # Orca states every figure as a decimal *string*. The yields above are already
+    # floats, so coercing here — rather than leaving it to ``decorate_pool`` as the
+    # other sources do — is what keeps the row from being half one and half the
+    # other for anything that reads it before decoration.
+    return coerce_pool_numbers(info)
+
+
+def _scale_ratio(value: Any) -> Optional[float]:
+    """A ratio from Orca as a percentage, or None when it reports nothing."""
+    ratio = _finite(value)
+    return None if ratio is None else ratio * 100
+
+
 def _get_nested_float(data: dict, *keys) -> Optional[float]:
     """Get a nested float value from dict, trying multiple key patterns"""
     # Try nested access
@@ -1389,6 +1477,7 @@ def extract_pair_from_name(name: str) -> Tuple[str, str]:
 _gecko_page_cache: Dict[Tuple, Tuple[float, List[Dict[str, Any]]]] = {}
 _gecko_dexes_cache: Dict[Tuple, Tuple[float, List[Dict[str, str]]]] = {}
 _gateway_pool_list_cache: Dict[Tuple, Tuple[float, List[Dict[str, Any]]]] = {}
+_orca_pool_list_cache: Dict[Tuple, Tuple[float, List[Dict[str, Any]]]] = {}
 _multi_pool_cache: Dict[Tuple[str, str], Tuple[float, List[Dict[str, Any]]]] = {}
 _pool_by_address_cache: Dict[Tuple[str, str], Tuple[float, Dict[str, Any]]] = {}
 
@@ -1450,6 +1539,7 @@ def _coerce_pool_rows(result: Any, limit: int = 20) -> List[Dict[str, Any]]:
     "quote_token_price_usd",
     "apr",
     "apy",
+    "fees_24h",
     "base_fee_percentage",
 )
 
@@ -1893,6 +1983,82 @@ def gateway_connector_network(connector: str) -> str:
     return LIQUIDITY_SUPPORTED_DEXES.get((connector or "").strip().lower(), "solana")
 
 
+# A day is 365 compoundings of a daily rate — the same annualization Meteora's own
+# `apy` applies to its `apr`, so a derived Orca figure sits on the same scale as
+# the Meteora one in the row above it.
+_DAYS_PER_YEAR = 365
+
+
+def _estimate_pool_yield(pool: Dict[str, Any]) -> None:
+    """Derive 24h fee/TVL and its annualization from volume and the fee tier.
+
+    For a CLMM connector whose Gateway listing reports the fee tier and TVL but no
+    yield, the two yield columns would otherwise be empty for every one of its
+    pools. Fees are mechanical — volume times the tier — so with a volume from
+    GeckoTerminal the figure Meteora reports directly can be computed rather than
+    left blank. Orca no longer needs this: it is read from its own API, which
+    reports realized fees (see ``list_orca_pools``).
+
+    Marked ``apr_estimated`` because it is: it assumes every trade paid the base
+    tier, which a dynamic-fee venue's real fees only approximate.
+    """
+    volume = _finite(pool.get("volume_24h"))
+    tvl = _finite(pool.get("reserve_usd"))
+    fee_pct = _finite(pool.get("base_fee_percentage"))
+    if not volume or not tvl or fee_pct is None or tvl <= 0:
+        return
+    fees_24h = volume * fee_pct / 100
+    daily = fees_24h / tvl
+    pool["fees_24h"] = fees_24h
+    pool["apr"] = daily * 100
+    pool["apy"] = ((1 + daily) ** _DAYS_PER_YEAR - 1) * 100
+    pool["apr_estimated"] = True
+
+
+async def _fill_gateway_pool_gaps(pools: List[Dict[str, Any]], network: str) -> None:
+    """Fill the figures a CLMM connector leaves blank, from GeckoTerminal.
+
+    Meteora's own listing answers volume, fees and APR, but no connector reports a
+    24h price change, and a row with an em-dash under the columns that say whether
+    a pool is worth entering is barely a row. GeckoTerminal indexes the same pools
+    under the same addresses, so one multi-pool request per page closes the gap.
+
+    Only rows with an actual gap are looked up, cached with the page they filled.
+    A failed lookup leaves the rows as they were: a blank column is what the
+    browser already renders. Orca used to be the worst case here — TVL and nulls —
+    and no longer passes through at all; it is read from its own API instead.
+    """
+    wanted = [
+        str(p.get("address"))
+        for p in pools
+        if p.get("address")
+        and (p.get("volume_24h") is None or p.get("price_change_24h") is None)
+    ]
+    if not wanted:
+        return
+
+    try:
+        indexed = await fetch_pools_by_addresses(network, wanted)
+    except Exception as e:  # pragma: no cover - fetch_pools_by_addresses swallows
+        logger.info("gateway pool enrichment failed net=%s: %s", network, e)
+        return
+
+    by_address = {str(row.get("address")): row for row in indexed}
+    for pool in pools:
+        row = by_address.get(str(pool.get("address")))
+        if not row:
+            continue
+        if pool.get("volume_24h") is None:
+            pool["volume_24h"] = row.get("volume_24h")
+        if pool.get("price_change_24h") is None:
+            pool["price_change_24h"] = row.get("price_change_24h")
+        # Gateway's TVL is the connector's own; gecko's only stands in for a gap.
+        if pool.get("reserve_usd") is None:
+            pool["reserve_usd"] = row.get("reserve_usd")
+        if pool.get("apr") is None and pool.get("apy") is None:
+            _estimate_pool_yield(pool)
+
+
 async def list_gateway_pools(
     client: Any,
     connector: str,
@@ -1951,10 +2117,94 @@ async def list_gateway_pools(
         if pool.get("address"):
             pools.append(pool)
 
+    # Before the cache, so the extra upstream request is spent once per page and
+    # not once per viewer of it.
+    await _fill_gateway_pool_gaps(pools, network)
+
     _ttl_put(_gateway_pool_list_cache, key, pools, GATEWAY_POOL_LIST_TTL)
     return [dict(row) for row in pools]
 
 
+# How many whirlpools one snapshot holds. Orca lists over 8,000, but ranked by TVL
+# fewer than ~500 hold more than $10k and the rest are dust the browser would never
+# page to — so this is the whole browsable set, not a first page of it.
+ORCA_SNAPSHOT_SIZE = 500
+
+
+async def _orca_snapshot(search: Optional[str]) -> Optional[List[Dict[str, Any]]]:
+    """Every browsable Orca whirlpool, normalized and ranked by TVL.
+
+    ``None`` — not ``[]`` — when the upstream failed and there is no stale copy:
+    the caller falls back to the Gateway listing on that, and an empty table is
+    the wrong thing to show for a venue with thousands of pools.
+    """
+    key = (search or "",)
+    cached = _ttl_get(_orca_pool_list_cache, key, ORCA_POOL_LIST_TTL)
+    if cached is not None:
+        return cached
+
+    # Flicking between tabs asks for the same snapshot while the first request is
+    # still in the air; without this each one opens its own.
+    async def _fetch() -> Optional[List[Dict[str, Any]]]:
+        try:
+            rows = await orca_api.fetch_whirlpools(ORCA_SNAPSHOT_SIZE, search=search)
+        except Exception as e:
+            stale, age = _stale_get(_orca_pool_list_cache, key)
+            logger.warning(
+                "orca pool list failed search=%r: %s%s",
+                search or "",
+                e,
+                f" (serving {age:.0f}s-old cache)" if stale is not None else "",
+            )
+            return stale
+
+        network = gateway_connector_network("orca")
+        pools: List[Dict[str, Any]] = []
+        for row in rows:
+            try:
+                pool = decorate_pool(normalize_pool_data(row, source="orca"), network)
+            except Exception as e:
+                logger.info("orca pool row skipped: %s", e)
+                continue
+            if pool.get("address"):
+                pools.append(pool)
+        _stale_put(_orca_pool_list_cache, key, pools)
+        return pools
+
+    return await _single_flight(("orca-pools", key), _fetch)
+
+
+async def list_orca_pools(
+    search: Optional[str] = None, limit: int = 20, page: int = 1
+) -> Optional[Tuple[List[Dict[str, Any]], bool]]:
+    """One page of Orca whirlpools, with whether another follows.
+
+    Read straight from Orca rather than through Gateway, which proxies this very
+    API and drops volume, fees, price and yield on the way — and which ignores its
+    own ``page`` argument for this connector, so every page of the tab was page one.
+
+    Sliced out of a cached snapshot because Orca paginates by cursor and the browser
+    pages by number: one upstream request per minute serves every page, which is
+    fewer than the request-per-page-plus-GeckoTerminal it replaces. ``has_more`` is
+    then a fact rather than the "a full page implies another" guess Gateway forces.
+
+    ``None`` when the upstream failed and nothing stale was cached.
+    """
+    limit = _clamp_pool_limit(limit)
+    try:
+        page = max(1, int(page))
+    except (TypeError, ValueError):
+        page = 1
+
+    pools = await _orca_snapshot((search or "").strip() or None)
+    if pools is None:
+        return None
+
+    start = (page - 1) * limit
+    window = pools[start : start + limit]
+    return [dict(row) for row in window], len(pools) > start + limit
+
+
 async def fetch_pool_by_address(
     network: str, pool_address: str
 ) -> Optional[Dict[str, Any]]:
diff --git a/tests/test_dex_pool_discovery.py b/tests/test_dex_pool_discovery.py
index 8c74f9c5..1433a55e 100644
--- a/tests/test_dex_pool_discovery.py
+++ b/tests/test_dex_pool_discovery.py
@@ -36,13 +36,24 @@ def _clear_caches(monkeypatch):
         pool_data._gateway_pool_list_cache,
         pool_data._pool_by_address_cache,
         pool_data._multi_pool_cache,
+        pool_data._orca_pool_list_cache,
     ):
         cache.clear()
+    # A single-flight task left over from another test's event loop would be
+    # awaited on a loop that is already closed.
+    pool_data._gecko_inflight.clear()
     # No test in this module may reach the real GeckoTerminal — and a Gateway
     # listing now looks pools up there too, to fill the figures Orca's connector
     # leaves null. The empty stand-in is overridden by the ``fake_gecko`` fixture
     # wherever a test actually wants rows back.
     monkeypatch.setattr(pool_data, "_gecko_client", lambda: FakeGecko())
+
+    # Nor may any test reach the real api.orca.so. Overridden by ``fake_orca``
+    # wherever a test actually wants whirlpools back.
+    async def _no_orca(*a, **kw):
+        raise AssertionError("test reached the real Orca API")
+
+    monkeypatch.setattr(pool_data.orca_api, "fetch_whirlpools", _no_orca)
     yield
 
 
@@ -1148,3 +1159,226 @@ def test_chains_falls_back_to_solana_when_gateway_is_down(route_client):
 def test_chains_needs_server_access(route_client):
     client = route_client(allowed=False)
     assert client.get("/servers/srv/dex/chains").status_code == 403
+
+
+# ── the Orca source (handlers/dex/orca_api.py + list_orca_pools) ──
+#
+# Gateway proxies this very API and nulls volume, fees, price and yield on the way
+# — and ignores its own `page` argument for this connector, so every page of the
+# Orca tab was page one. These pin the shape that replaced it, against the payload
+# api.orca.so actually returns.
+
+
+def orca_row(**over):
+    row = {
+        "address": POOL,
+        "tickSpacing": 4,
+        "feeRate": 400,  # millionths of the trade: 0.04%
+        "price": "75.4699414017526812",
+        "tvlUsdc": "25914246.8432301700048600",
+        "tokenMintA": SOL,
+        "tokenMintB": USDC,
+        "tokenA": {"address": SOL, "symbol": "SOL", "decimals": 9},
+        "tokenB": {"address": USDC, "symbol": "USDC", "decimals": 6},
+        "stats": {
+            "24h": {
+                "volume": "51745436.73117720",
+                "fees": "20697.75405187479438737000",
+                "yieldOverTvl": "0.00079852453975813900",
+                "priceDelta": "-0.005889007438397060571184406001499000",
+            }
+        },
+    }
+    row.update(over)
+    return row
+
+
+@pytest.fixture
+def fake_orca(monkeypatch):
+    """Stand in for api.orca.so. No test in this module may reach the real one."""
+
+    class FakeOrca:
+        def __init__(self, rows=None, error=None):
+            self.rows = rows if rows is not None else []
+            self.error = error
+            self.calls: list[dict] = []
+
+        async def fetch_whirlpools(self, size, search=None, **kw):
+            self.calls.append({"size": size, "search": search, **kw})
+            if self.error:
+                raise self.error
+            return self.rows
+
+    def build(rows=None, error=None):
+        fake = FakeOrca(rows, error)
+        monkeypatch.setattr(
+            pool_data.orca_api, "fetch_whirlpools", fake.fetch_whirlpools
+        )
+        return fake
+
+    return build
+
+
+def test_orca_normalization_maps_every_column_gateway_nulls():
+    """The whole point: TVL, volume, fees, price and yield in one row."""
+    pool = pool_data.normalize_pool_data(orca_row(), source="orca")
+    assert pool["source"] == "orca"
+    assert pool["address"] == POOL
+    assert pool["dex_id"] == "orca"
+    assert pool["reserve_usd"] == pytest.approx(25_914_246.84, abs=0.01)
+    assert pool["volume_24h"] == pytest.approx(51_745_436.73, abs=0.01)
+    assert pool["fees_24h"] == pytest.approx(20_697.754, abs=0.01)
+    assert pool["current_price"] == pytest.approx(75.4699, abs=1e-4)
+
+
+def test_orca_fee_rate_is_millionths_of_the_trade():
+    """400 is 0.04%, the tier Orca's own UI shows — not 400% and not 4%."""
+    pool = pool_data.normalize_pool_data(orca_row(), source="orca")
+    assert pool["base_fee_percentage"] == pytest.approx(0.04)
+
+
+def test_orca_tick_spacing_lands_in_the_bin_step_column():
+    """Both answer the same question: how finely can I place a position here."""
+    pool = pool_data.normalize_pool_data(orca_row(), source="orca")
+    assert pool["bin_step"] == 4
+
+
+def test_orca_yield_is_realized_and_not_marked_estimated():
+    """Orca reports fees *and* rewards over TVL, so nothing is derived from volume."""
+    pool = pool_data.normalize_pool_data(orca_row(), source="orca")
+    # 0.00079852 of TVL per day, as a percent, then 365 compoundings of it.
+    assert pool["apr"] == pytest.approx(0.0798525, abs=1e-6)
+    assert pool["apy"] == pytest.approx(33.63, abs=0.5)
+    assert pool["apr_estimated"] is False
+
+
+def test_orca_price_delta_is_a_ratio_rendered_as_a_percent():
+    """Orca says -0.0059; the column says -0.59%, like gecko's already does."""
+    pool = pool_data.normalize_pool_data(orca_row(), source="orca")
+    assert pool["price_change_24h"] == pytest.approx(-0.5889, abs=1e-3)
+
+
+def test_orca_pool_with_no_stats_keeps_its_other_columns():
+    """A brand-new whirlpool has no 24h window yet; that is not a broken row."""
+    pool = pool_data.normalize_pool_data(orca_row(stats={}), source="orca")
+    assert pool["reserve_usd"] == pytest.approx(25_914_246.84, abs=0.01)
+    assert pool["volume_24h"] is None
+    assert pool["apr"] is None
+
+
+def test_orca_pools_are_decorated_like_any_other_source(fake_orca):
+    fake_orca([orca_row()])
+    pools, _ = run(pool_data.list_orca_pools())
+    assert pools[0]["lp_supported"] is True
+    assert pools[0]["tradable"] is True
+    assert pools[0]["gateway_network"] == "solana-mainnet-beta"
+    assert pools[0]["trading_pair"] == f"{SOL}-USDC"
+
+
+def test_orca_pages_are_sliced_out_of_one_snapshot(fake_orca):
+    """Orca paginates by cursor and the browser by number, so one fetch serves both."""
+    fake = fake_orca([orca_row(address=f"pool{i}") for i in range(50)])
+    first, more_first = run(pool_data.list_orca_pools(limit=20, page=1))
+    second, more_second = run(pool_data.list_orca_pools(limit=20, page=2))
+    third, more_third = run(pool_data.list_orca_pools(limit=20, page=3))
+    assert [p["address"] for p in first] == [f"pool{i}" for i in range(20)]
+    assert [p["address"] for p in second] == [f"pool{i}" for i in range(20, 40)]
+    assert [p["address"] for p in third] == [f"pool{i}" for i in range(40, 50)]
+    assert (more_first, more_second, more_third) == (True, True, False)
+    # Three pages, one upstream request — the Gateway path spent one per page and
+    # a GeckoTerminal one on top.
+    assert len(fake.calls) == 1
+
+
+def test_orca_has_more_is_exact_not_a_full_page_guess(fake_orca):
+    """A snapshot that ends exactly on a page boundary has no next page."""
+    fake_orca([orca_row(address=f"pool{i}") for i in range(20)])
+    _, more = run(pool_data.list_orca_pools(limit=20, page=1))
+    assert more is False
+
+
+def test_orca_search_goes_upstream_as_a_query(fake_orca):
+    fake = fake_orca([orca_row()])
+    run(pool_data.list_orca_pools(search="BONK"))
+    assert fake.calls[0]["search"] == "BONK"
+
+
+def test_blank_orca_search_is_no_search(fake_orca):
+    fake = fake_orca([orca_row()])
+    run(pool_data.list_orca_pools(search="   "))
+    assert fake.calls[0]["search"] is None
+
+
+def test_orca_searches_are_cached_apart_from_the_unfiltered_list(fake_orca):
+    fake = fake_orca([orca_row()])
+    run(pool_data.list_orca_pools())
+    run(pool_data.list_orca_pools(search="BONK"))
+    assert [c["search"] for c in fake.calls] == [None, "BONK"]
+
+
+def test_orca_rows_with_no_address_are_dropped(fake_orca):
+    fake_orca([orca_row(address=""), orca_row()])
+    pools, _ = run(pool_data.list_orca_pools())
+    assert len(pools) == 1
+
+
+def test_orca_cached_rows_are_copies_a_caller_cannot_poison(fake_orca):
+    fake_orca([orca_row()])
+    first, _ = run(pool_data.list_orca_pools())
+    first[0]["address"] = "mutated"
+    again, _ = run(pool_data.list_orca_pools())
+    assert again[0]["address"] == POOL
+
+
+def test_orca_failure_is_none_so_the_caller_can_fall_back(fake_orca):
+    """`[]` would render "no pools" for a venue with thousands; None means fall back."""
+    fake_orca(error=RuntimeError("429 rate limited"))
+    assert run(pool_data.list_orca_pools()) is None
+
+
+def test_orca_serves_a_stale_snapshot_before_giving_up(fake_orca):
+    """A rate limit should not empty a table that was correct a minute ago."""
+    fake_orca([orca_row()])
+    run(pool_data.list_orca_pools())
+    fresh = pool_data._orca_pool_list_cache[("",)][1]
+    pool_data._orca_pool_list_cache[("",)] = (0.0, fresh)
+    fake_orca(error=RuntimeError("429 rate limited"))
+    pools, _ = run(pool_data.list_orca_pools())
+    assert [p["address"] for p in pools] == [POOL]
+
+
+def test_orca_source_lists_pools(route_client, fake_orca):
+    fake_orca([orca_row()])
+    r = route_client().get("/servers/srv/dex/pools?source=orca")
+    assert r.status_code == 200
+    body = r.json()
+    assert body["source"] == "orca"
+    assert body["pools"][0]["address"] == POOL
+    assert body["pools"][0]["volume_24h"] == pytest.approx(51_745_436.73, abs=0.01)
+
+
+def test_orca_route_needs_no_gateway_client(route_client, fake_orca):
+    """A public API, so a server whose Gateway is down still browses Orca."""
+    fake_orca([orca_row()])
+    client = route_client(client_error=RuntimeError("gateway is down"))
+    r = client.get("/servers/srv/dex/pools?source=orca")
+    assert r.status_code == 200
+    assert r.json()["pools"][0]["address"] == POOL
+
+
+def test_orca_route_falls_back_to_gateway_when_orca_is_down(route_client, fake_orca):
+    fake_orca(error=RuntimeError("403 cloudflare"))
+    clmm = FakeClmm({"pools": [gateway_row(connector="orca")]})
+    r = route_client(client=FakeClient(clmm)).get("/servers/srv/dex/pools?source=orca")
+    assert r.status_code == 200
+    body = r.json()
+    # Reported as the source that actually served it, not the one that was asked for.
+    assert body["source"] == "gateway"
+    assert clmm.calls[0]["connector"] == "orca"
+    assert body["pools"][0]["address"] == POOL
+
+
+def test_orca_route_needs_server_access(route_client, fake_orca):
+    fake_orca([orca_row()])
+    client = route_client(allowed=False)
+    assert client.get("/servers/srv/dex/pools?source=orca").status_code == 403

From 2ea6ab858c987e3d352fd164ed2049374ef38349 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Mon, 17 Aug 2026 14:10:18 +0300
Subject: [PATCH 103/116] (feat) pick LP bounds off the chart, and price a DEX
 pair by its symbols
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Typing an LP range into a form means reading prices off the chart and
transcribing them back. Each price field now claims a pick slot, so a
click on the chart fills the bound it belongs to: the two range bounds
and both auto-close triggers, with the lower limit drawn as an extra line.

The auto-close limits were also anchored to absolutes, which put a 1%
range's trigger nine range-widths away — a position could sit out of range
indefinitely without ever firing. They are now a multiple of the range's
own half-width, so they move with the preset.

Separately, the balance bar split `trading_pair` to name its tokens. A DEX
pair is `<base_mint>-<quote_symbol>`, so the base lookup went hunting for a
balance under a mint address and found none, and a Solana pool showed its
quote balance alone. Callers that know the real symbols now pass them.
---
 frontend/src/components/dex/LpPositionBar.tsx | 129 ++++++++++++
 frontend/src/components/dex/LpPositions.tsx   | 184 ++++++++++++++++++
 frontend/src/components/dex/lp-position.ts    | 101 ++++++++++
 .../components/executor/DCAConfigPanel.tsx    |   4 +-
 .../src/components/executor/LPConfigPanel.tsx | 148 +++++++++-----
 .../components/executor/OrderConfigPanel.tsx  |  74 +++++--
 .../executor/PositionConfigPanel.tsx          |   4 +-
 frontend/src/components/executor/fields.tsx   |  74 ++++++-
 frontend/src/components/executor/types.ts     |  11 +-
 .../src/components/trade/TradeBottomPane.tsx  |  25 ++-
 frontend/src/components/trade/TradeChart.tsx  |  21 +-
 frontend/src/hooks/useMainControllerData.ts   |  70 ++++++-
 frontend/src/hooks/usePairBalances.ts         |  50 +++++
 frontend/src/lib/api.ts                       |   9 +-
 frontend/src/lib/executor-overlays.ts         |  30 ++-
 frontend/src/pages/CreateExecutor.tsx         |  19 +-
 frontend/src/pages/CreateGridExecutor.tsx     |   5 +-
 17 files changed, 848 insertions(+), 110 deletions(-)
 create mode 100644 frontend/src/components/dex/LpPositionBar.tsx
 create mode 100644 frontend/src/components/dex/LpPositions.tsx
 create mode 100644 frontend/src/components/dex/lp-position.ts
 create mode 100644 frontend/src/hooks/usePairBalances.ts

diff --git a/frontend/src/components/dex/LpPositionBar.tsx b/frontend/src/components/dex/LpPositionBar.tsx
new file mode 100644
index 00000000..5e8c34eb
--- /dev/null
+++ b/frontend/src/components/dex/LpPositionBar.tsx
@@ -0,0 +1,129 @@
+import { useMemo } from "react";
+
+import { feeAmount, lpStateStyle, readLpPosition, type LpPosition } from "./lp-position";
+import { type ExecutorInfo } from "@/lib/api";
+import { formatPnl, isExecutorActive, pnlColor } from "@/lib/formatters";
+
+/** Prices here span memecoin to majors, so significant digits, not decimals. */
+function fmtPrice(price: number | null): string {
+  if (price === null || !Number.isFinite(price) || price <= 0) return "—";
+  if (price >= 1000) return price.toFixed(2);
+  if (price >= 1) return price.toFixed(4);
+  return price.toPrecision(5);
+}
+
+/**
+ * Where the price sits inside the range, as a 0–1 fraction, or `null`.
+ *
+ * The number a CLMM position is actually about: a range you are 95% of the way
+ * through is one swap from earning nothing, and no amount of reading two price
+ * strings makes that as obvious as a marker does.
+ */
+function rangeFraction(pos: LpPosition, price: number | null): number | null {
+  const { lowerPrice: lo, upperPrice: hi } = pos;
+  if (!lo || !hi || hi <= lo || !price || price <= 0) return null;
+  return Math.min(1, Math.max(0, (price - lo) / (hi - lo)));
+}
+
+interface Props {
+  /** The pool's executors, already scoped to this pool by the page. */
+  executors: ExecutorInfo[];
+  /** Live pool price, when the chart's own mark is fresher than the executor's. */
+  currentPrice: number | null;
+  selectedExecutorId?: string | null;
+  onSelect?: (executorId: string) => void;
+}
+
+/**
+ * The liquidity you hold in this pool, above its chart.
+ *
+ * The chart already draws an open position as a box, but a box answers "where"
+ * and not "how is it doing" — and only once you have found it among a page of
+ * candles. This is the position's own line: whether it is still earning, the
+ * bounds it earns between, where the price is inside them, and what it has made.
+ *
+ * Renders nothing when nothing is open, so a pool you are only looking at keeps
+ * its full chart height.
+ */
+export function LpPositionBar({
+  executors,
+  currentPrice,
+  selectedExecutorId,
+  onSelect,
+}: Props) {
+  const positions = useMemo(() => {
+    const open: LpPosition[] = [];
+    for (const ex of executors) {
+      if (ex.type?.toLowerCase() !== "lp") continue;
+      if (!isExecutorActive(ex.status)) continue;
+      const pos = readLpPosition(ex);
+      if (pos) open.push(pos);
+    }
+    return open;
+  }, [executors]);
+
+  if (!positions.length) return null;
+
+  return (
+    <div className="flex shrink-0 flex-wrap items-stretch gap-2 border-b border-[var(--color-border)] bg-[var(--color-surface)] px-3 py-2">
+      {positions.map((pos) => {
+        const state = lpStateStyle(pos.state);
+        const price = currentPrice && currentPrice > 0 ? currentPrice : pos.currentPrice;
+        const fraction = rangeFraction(pos, price);
+        const selected = selectedExecutorId === pos.id;
+        return (
+          <button
+            key={pos.id}
+            onClick={() => onSelect?.(pos.id)}
+            title={`${pos.provider || "LP"} position ${pos.id}`}
+            className={`flex flex-1 flex-wrap items-center gap-x-4 gap-y-1 rounded-md border px-3 py-1.5 text-left text-[11px] transition-colors ${
+              selected
+                ? "border-[var(--color-primary)] bg-[var(--color-primary)]/5"
+                : "border-[var(--color-border)] bg-[var(--color-bg)] hover:bg-[var(--color-surface-hover)]"
+            }`}
+          >
+            <span
+              className="rounded px-1.5 py-0.5 text-[10px] font-medium"
+              style={{ color: state.color, backgroundColor: state.bg }}
+            >
+              {state.label}
+            </span>
+
+            {/* Range, with the price's place inside it */}
+            <span className="flex items-center gap-1.5 font-mono tabular-nums">
+              <span className="text-[var(--color-text-muted)]">{fmtPrice(pos.lowerPrice)}</span>
+              <span className="relative h-1 w-16 overflow-hidden rounded-full bg-[var(--color-border)]">
+                {fraction !== null && (
+                  <span
+                    className="absolute top-1/2 h-2 w-0.5 -translate-y-1/2 rounded-full"
+                    style={{
+                      left: `calc(${fraction * 100}% - 1px)`,
+                      backgroundColor: state.color,
+                    }}
+                  />
+                )}
+              </span>
+              <span className="text-[var(--color-text-muted)]">{fmtPrice(pos.upperPrice)}</span>
+            </span>
+
+            <span className="ml-auto flex items-center gap-4 font-mono tabular-nums">
+              {pos.valueQuote !== null && (
+                <span>
+                  <span className="mr-1 text-[10px] text-[var(--color-text-muted)]">value</span>
+                  {feeAmount(pos.valueQuote)}
+                </span>
+              )}
+              {pos.feesQuote !== null && (
+                <span>
+                  <span className="mr-1 text-[10px] text-[var(--color-text-muted)]">fees</span>
+                  {feeAmount(pos.feesQuote)}
+                </span>
+              )}
+              <span style={{ color: pnlColor(pos.pnl) }}>{formatPnl(pos.pnl)}</span>
+            </span>
+          </button>
+        );
+      })}
+    </div>
+  );
+}
diff --git a/frontend/src/components/dex/LpPositions.tsx b/frontend/src/components/dex/LpPositions.tsx
new file mode 100644
index 00000000..2017bc44
--- /dev/null
+++ b/frontend/src/components/dex/LpPositions.tsx
@@ -0,0 +1,184 @@
+import { useQuery } from "@tanstack/react-query";
+import { ArrowRight } from "lucide-react";
+import { useMemo } from "react";
+import { useNavigate } from "react-router-dom";
+
+import {
+  LP_EXECUTOR_TYPE,
+  feeAmount,
+  lpStateStyle,
+  readLpPosition,
+  type LpPosition,
+} from "./lp-position";
+import { api, type PoolSummary } from "@/lib/api";
+import { formatPnl, formatUsd, isExecutorActive, pnlColor } from "@/lib/formatters";
+
+/** Live enough to see a range break without hammering the API. */
+const REFRESH_MS = 20_000;
+
+/**
+ * How far back the poll reads.
+ *
+ * The upstream search has no usable "open only" filter (its `status` values are
+ * not the ones the API normalizes to), so open positions are found by reading
+ * recent executors and filtering here. Unbounded that is a walk of the entire
+ * history every {@link REFRESH_MS}; the search answers newest-first and an open
+ * LP position is by definition recent, so the newest few hundred contain them.
+ */
+const RECENT_EXECUTORS = 200;
+
+/** GeckoTerminal's multi-pool endpoint, which the labels come from, caps here. */
+const MAX_LABELLED_POOLS = 30;
+
+/**
+ * A pair label for a position, preferring the pool's own.
+ *
+ * An LP executor's `trading_pair` is `<base_mint>-<quote_symbol>` — the form the
+ * executor needs, and unreadable as a label: `So1111…112-USDC` rather than
+ * `SOL-USDC`. The pool row has the symbols, so it wins when it resolved.
+ */
+function labelFor(pos: LpPosition, pool: PoolSummary | undefined): string {
+  const base = pool?.base_symbol;
+  const quote = pool?.quote_symbol;
+  if (base && base !== "???" && quote && quote !== "???") return `${base}-${quote}`;
+  if (pool?.name) return pool.name;
+  const [poolBase, poolQuote] = pos.pair.split("-");
+  if (poolBase && poolBase.length > 12) {
+    return `${poolBase.slice(0, 4)}…-${poolQuote ?? ""}`;
+  }
+  return pos.pair || pos.poolAddress.slice(0, 8);
+}
+
+/**
+ * The LP positions you already hold, above the pools you might enter.
+ *
+ * The browser below is for finding a pool; this is for getting back to one. A
+ * position lives in exactly one pool, and its executor knows the address, so the
+ * shortest path from "how is my SOL-USDC range doing" to that pool's workspace is
+ * a row here rather than a search through Trending.
+ *
+ * Renders nothing at all when there are no open positions: an empty panel above
+ * every visit to the pool browser is a permanent cost for an occasional feature.
+ */
+export function LpPositions({ server }: { server: string }) {
+  const navigate = useNavigate();
+
+  const { data: executors = [] } = useQuery({
+    queryKey: ["dex-lp-executors", server],
+    queryFn: () =>
+      api.getExecutors(server, {
+        executor_type: LP_EXECUTOR_TYPE,
+        limit: RECENT_EXECUTORS,
+      }),
+    refetchInterval: REFRESH_MS,
+    staleTime: REFRESH_MS,
+  });
+
+  const positions = useMemo(() => {
+    const open: LpPosition[] = [];
+    for (const ex of executors) {
+      if (!isExecutorActive(ex.status)) continue;
+      const pos = readLpPosition(ex);
+      if (pos) open.push(pos);
+    }
+    // Biggest first: the position most worth checking is the one with the most
+    // in it, and an unvalued position sorts last rather than to the top.
+    open.sort((a, b) => (b.valueQuote ?? -1) - (a.valueQuote ?? -1));
+    return open;
+  }, [executors]);
+
+  // Every open position is on one chain in practice (Gateway's CLMM connectors
+  // are Solana-only), but the labels are fetched per chain so a second one does
+  // not silently fall back to mint addresses.
+  const byNetwork = useMemo(() => {
+    const groups: Record<string, string[]> = {};
+    for (const pos of positions.slice(0, MAX_LABELLED_POOLS)) {
+      const list = (groups[pos.network] ??= []);
+      if (!list.includes(pos.poolAddress)) list.push(pos.poolAddress);
+    }
+    return groups;
+  }, [positions]);
+
+  const { data: pools = {} } = useQuery({
+    queryKey: ["dex-lp-pools", server, JSON.stringify(byNetwork)],
+    queryFn: async () => {
+      const entries = await Promise.all(
+        Object.entries(byNetwork).map(([network, addresses]) =>
+          api
+            .getDexPoolsByAddress(server, network, addresses)
+            .catch(() => [] as PoolSummary[]),
+        ),
+      );
+      const map: Record<string, PoolSummary> = {};
+      for (const pool of entries.flat()) map[pool.address] = pool;
+      return map;
+    },
+    enabled: Object.keys(byNetwork).length > 0,
+    // A pair label does not change; only the TVL beside it does.
+    staleTime: 5 * 60_000,
+  });
+
+  if (!positions.length) return null;
+
+  return (
+    <div className="overflow-hidden rounded-lg border border-[var(--color-border)]">
+      <div className="flex items-center justify-between border-b border-[var(--color-border)] bg-[var(--color-surface)] px-4 py-2">
+        <span className="text-xs font-medium uppercase tracking-wider text-[var(--color-text-muted)]">
+          Your LP positions
+        </span>
+        <span className="text-xs text-[var(--color-text-muted)]">
+          {positions.length}
+        </span>
+      </div>
+
+      <div className="flex gap-2 overflow-x-auto p-3">
+        {positions.map((pos) => {
+          const pool = pools[pos.poolAddress];
+          const state = lpStateStyle(pos.state);
+          return (
+            <button
+              key={pos.id}
+              onClick={() => navigate(`/dex/${pos.network}/${pos.poolAddress}`)}
+              title={`Open ${labelFor(pos, pool)} on ${pos.provider || pool?.dex_id || pos.network}`}
+              className="group flex min-w-[13rem] shrink-0 flex-col gap-1.5 rounded-lg border border-[var(--color-border)] bg-[var(--color-bg)] px-3 py-2.5 text-left transition-colors hover:bg-[var(--color-surface-hover)]"
+            >
+              <div className="flex items-center justify-between gap-2">
+                <span className="truncate text-sm font-medium">
+                  {labelFor(pos, pool)}
+                </span>
+                <ArrowRight className="h-3 w-3 shrink-0 text-[var(--color-text-muted)] transition-colors group-hover:text-[var(--color-primary)]" />
+              </div>
+
+              <div className="flex items-center gap-1.5">
+                <span
+                  className="rounded px-1.5 py-0.5 text-[10px] font-medium"
+                  style={{ color: state.color, backgroundColor: state.bg }}
+                >
+                  {state.label}
+                </span>
+                <span className="truncate text-[10px] text-[var(--color-text-muted)]">
+                  {pos.provider || pool?.dex_id || ""}
+                </span>
+              </div>
+
+              <div className="flex items-baseline justify-between gap-2 text-xs tabular-nums">
+                <span>
+                  {pos.valueQuote === null ? "—" : formatUsd(pos.valueQuote)}
+                </span>
+                <span style={{ color: pnlColor(pos.pnl) }}>
+                  {formatPnl(pos.pnl)}
+                </span>
+              </div>
+
+              {pos.feesQuote !== null && (
+                <div className="text-[10px] text-[var(--color-text-muted)]">
+                  {feeAmount(pos.feesQuote)} fees
+                </div>
+              )}
+            </button>
+          );
+        })}
+      </div>
+    </div>
+  );
+}
diff --git a/frontend/src/components/dex/lp-position.ts b/frontend/src/components/dex/lp-position.ts
new file mode 100644
index 00000000..3eabd928
--- /dev/null
+++ b/frontend/src/components/dex/lp-position.ts
@@ -0,0 +1,101 @@
+import { type ExecutorInfo } from "@/lib/api";
+import { formatUsd } from "@/lib/formatters";
+
+/** LP executors are the only ones the DEX pages can route to a pool. */
+export const LP_EXECUTOR_TYPE = "lp_executor";
+
+function num(v: unknown): number | null {
+  if (v === null || v === undefined || v === "") return null;
+  const n = typeof v === "number" ? v : parseFloat(String(v));
+  return Number.isFinite(n) ? n : null;
+}
+
+function str(v: unknown): string {
+  return typeof v === "string" ? v : "";
+}
+
+/**
+ * One open LP position, flattened out of the executor that holds it.
+ *
+ * The executor carries the pool in its *config* and the position in its
+ * *custom_info*, and neither is typed — so the reading happens once, here, rather
+ * than in the render. Both the `/dex` strip and the bar above a pool's chart read
+ * a position through this, so the two cannot disagree about what one is.
+ */
+export interface LpPosition {
+  id: string;
+  /** The Gateway network, which is also the first segment of the pool's URL. */
+  network: string;
+  poolAddress: string;
+  provider: string;
+  pair: string;
+  /** `IN_RANGE`, `OUT_OF_RANGE`, … as the connector reports it. */
+  state: string;
+  /** On-chain bounds when the venue reports them, else the requested ones. */
+  lowerPrice: number | null;
+  upperPrice: number | null;
+  currentPrice: number | null;
+  valueQuote: number | null;
+  feesQuote: number | null;
+  pnl: number;
+}
+
+export function readLpPosition(ex: ExecutorInfo): LpPosition | null {
+  const config = ex.config ?? {};
+  const custom = ex.custom_info ?? {};
+  const poolAddress = str(config.pool_address);
+  const network = str(config.connector_name) || ex.connector;
+  // Without a pool there is nowhere to click through to, which is the whole
+  // point of the strip — so such an executor belongs on /executors, not here.
+  if (!poolAddress || !network) return null;
+  // custom_info wins: a CLMM position is snapped to the venue's bins, so the
+  // bounds it actually holds are not the ones that were asked for.
+  return {
+    id: ex.id,
+    network,
+    poolAddress,
+    provider: str(config.lp_provider),
+    pair: ex.trading_pair,
+    state: str(custom.state),
+    lowerPrice: num(custom.lower_price) ?? num(config.lower_price),
+    upperPrice: num(custom.upper_price) ?? num(config.upper_price),
+    currentPrice: num(custom.current_price) || (ex.current_price > 0 ? ex.current_price : null),
+    valueQuote: num(custom.total_value_quote),
+    feesQuote: num(custom.fees_earned_quote),
+    pnl: ex.pnl,
+  };
+}
+
+/** Fees on a fresh position are fractions of a cent, where `$0.00` says nothing. */
+export function feeAmount(val: number): string {
+  if (val !== 0 && Math.abs(val) < 0.01) return `$${val.toPrecision(2)}`;
+  return formatUsd(val);
+}
+
+/** In range is earning; out of range is not, and is the thing worth spotting. */
+export function lpStateStyle(state: string): {
+  label: string;
+  color: string;
+  bg: string;
+} {
+  const upper = state.toUpperCase();
+  if (upper === "IN_RANGE") {
+    return {
+      label: "In range",
+      color: "var(--color-green)",
+      bg: "rgba(34,197,94,0.12)",
+    };
+  }
+  if (upper === "OUT_OF_RANGE") {
+    return {
+      label: "Out of range",
+      color: "var(--color-yellow)",
+      bg: "rgba(234,179,8,0.14)",
+    };
+  }
+  return {
+    label: upper ? upper.replace(/_/g, " ").toLowerCase() : "open",
+    color: "var(--color-text-muted)",
+    bg: "var(--color-surface)",
+  };
+}
diff --git a/frontend/src/components/executor/DCAConfigPanel.tsx b/frontend/src/components/executor/DCAConfigPanel.tsx
index 545a043c..b5749eee 100644
--- a/frontend/src/components/executor/DCAConfigPanel.tsx
+++ b/frontend/src/components/executor/DCAConfigPanel.tsx
@@ -12,7 +12,7 @@ import {
   ValidationMessages,
   type FieldDispatch,
 } from "./fields";
-import type { ChartPriceMapping, ExecutorValidation, ExtraLine } from "./types";
+import type { ChartPriceMapping, ExecutorValidation, ExtraLine, PickSlot } from "./types";
 import { getThemeColors } from "@/lib/theme-colors";
 
 // ── State ──
@@ -297,7 +297,7 @@ export function useDCAConfig() {
 
   const save = () => saveDefaults(state);
 
-  const handleChartPriceSet = (_field: "start" | "end" | "limit", price: number) => {
+  const handleChartPriceSet = (_field: PickSlot, price: number) => {
     const pick = state.activePickField;
     if (pick && pick.startsWith("dca_price_")) {
       const idx = parseInt(pick.replace("dca_price_", ""), 10);
diff --git a/frontend/src/components/executor/LPConfigPanel.tsx b/frontend/src/components/executor/LPConfigPanel.tsx
index 5d72d9bb..3b768748 100644
--- a/frontend/src/components/executor/LPConfigPanel.tsx
+++ b/frontend/src/components/executor/LPConfigPanel.tsx
@@ -5,6 +5,7 @@ import { AlertTriangle, Sparkles } from "lucide-react";
 import {
   AdvancedSection,
   NumberField,
+  PercentPresets,
   PriceField,
   SectionHeader,
   SelectField,
@@ -12,7 +13,7 @@ import {
   ValidationMessages,
   type FieldDispatch,
 } from "./fields";
-import type { ChartPriceMapping, ExecutorValidation } from "./types";
+import type { ChartPriceMapping, ExecutorValidation, PickSlot } from "./types";
 import { api, type DexPoolInfo } from "@/lib/api";
 import { getThemeColors } from "@/lib/theme-colors";
 
@@ -26,8 +27,16 @@ export const LP_SIDE_RANGE = 3; // both tokens, range centered
 
 export type LpSide = 1 | 2 | 3;
 
-/** The buffer between a range bound and its auto-close trigger. */
-const LIMIT_BUFFER = 0.1;
+/**
+ * How far outside the range its auto-close triggers sit, as a multiple of the
+ * range's own half-width.
+ *
+ * Proportional rather than fixed: a flat 10% buffer put the trigger for a 1%
+ * range nine range-widths away, so a position could sit out of range indefinitely
+ * without ever firing. At 1× the limits move with the preset — a 1% range closes
+ * 1% beyond its bound, a 20% range 20% beyond.
+ */
+const LIMIT_BUFFER_RATIO = 1;
 
 // ── State ──
 
@@ -141,11 +150,12 @@ export function rangeForSide(side: LpSide, price: number, pct: number) {
     lower = price * (1 - pct);
     upper = price * (1 + pct);
   }
+  const buffer = pct * LIMIT_BUFFER_RATIO;
   return {
     lower_price: lower,
     upper_price: upper,
-    lower_limit_price: lower * (1 - LIMIT_BUFFER),
-    upper_limit_price: upper * (1 + LIMIT_BUFFER),
+    lower_limit_price: lower * (1 - buffer),
+    upper_limit_price: upper * (1 + buffer),
   };
 }
 
@@ -263,18 +273,21 @@ function rangeWarnings(state: LPState, price: number | null): string[] {
 }
 
 // ── Chart pick slots ──
-// The chart carries three pick slots. Upper/lower bounds and the upper limit get
-// them; the lower limit is typed, and its PriceField offers no crosshair.
-const PICK_SLOT: Record<string, "start" | "end" | "limit"> = {
+// One slot per price: the two bounds and both auto-close triggers. The lower
+// limit rides `limit2`, the slot for a price the panel draws itself as an extra
+// line rather than one the chart owns.
+const PICK_SLOT: Record<string, PickSlot> = {
   upper_price: "start",
   lower_price: "end",
   upper_limit_price: "limit",
+  lower_limit_price: "limit2",
 };
 
-const SLOT_FIELD: Record<"start" | "end" | "limit", keyof LPState> = {
+const SLOT_FIELD: Record<PickSlot, keyof LPState> = {
   start: "upper_price",
   end: "lower_price",
   limit: "upper_limit_price",
+  limit2: "lower_limit_price",
 };
 
 export function isMeteoraProvider(provider: string): boolean {
@@ -319,7 +332,11 @@ export function useLpConfig(
               {
                 price: state.lower_limit_price,
                 label: "Lower limit",
-                color: getThemeColors().red,
+                // Amber while armed, matching how the chart marks its own lines.
+                color:
+                  state.activePickField === "lower_limit_price"
+                    ? "#fbbf24"
+                    : getThemeColors().red,
                 lineStyle: "dotted" as const,
                 lineWidth: 1,
               },
@@ -363,7 +380,7 @@ export function useLpConfig(
 
   const save = () => saveDefaults(state);
 
-  const handleChartPriceSet = (field: "start" | "end" | "limit", price: number) => {
+  const handleChartPriceSet = (field: PickSlot, price: number) => {
     dispatch({ type: "SET_FIELD", field: SLOT_FIELD[field], value: price });
     dispatch({ type: "SET_FIELD", field: "activePickField", value: null });
   };
@@ -412,6 +429,12 @@ function truncateAddress(address: string): string {
     : address;
 }
 
+/** A percentage of an available balance, at a precision an input can render. */
+function sizeFrom(available: number | null, pct: number): number {
+  if (!available || available <= 0) return 0;
+  return Number((available * pct).toPrecision(8));
+}
+
 function formatPoolPrice(price: number): string {
   if (price >= 1000) return price.toFixed(2);
   if (price >= 1) return price.toFixed(4);
@@ -428,6 +451,15 @@ interface Props {
   pair?: string;
   pool?: DexPoolInfo;
   poolFetching?: boolean;
+  /** Wallet balance behind the percentage presets; `null` when it is unknown. */
+  baseAvailable?: number | null;
+  quoteAvailable?: number | null;
+  /**
+   * Display symbols for the two tokens. A DEX `trading_pair` is
+   * `<base_mint>-<quote_symbol>`, so its base half is an address, not a ticker.
+   */
+  baseSymbol?: string;
+  quoteSymbol?: string;
 }
 
 export function LPConfigPanel({
@@ -438,6 +470,10 @@ export function LPConfigPanel({
   pair,
   pool,
   poolFetching,
+  baseAvailable = null,
+  quoteAvailable = null,
+  baseSymbol,
+  quoteSymbol,
 }: Props) {
   const d = dispatch as FieldDispatch;
 
@@ -445,8 +481,8 @@ export function LPConfigPanel({
   // price is known, so the resolved pool is a second source for the anchor.
   const price = currentPrice && currentPrice > 0 ? currentPrice : pool?.current_price ?? null;
 
-  const baseAsset = pair?.split("-")[0] || pool?.base_symbol || "base";
-  const quoteAsset = pair?.split("-")[1] || pool?.quote_symbol || "quote";
+  const baseAsset = baseSymbol || pool?.base_symbol || pair?.split("-")[0] || "base";
+  const quoteAsset = quoteSymbol || pool?.quote_symbol || pair?.split("-")[1] || "quote";
 
   // Anchor the range the first time a price is known. Not a reset: once the bounds
   // are non-zero they are the user's, and only an explicit action moves them.
@@ -598,27 +634,6 @@ export function LPConfigPanel({
         />
       </div>
 
-      {/* Amounts */}
-      <div className="space-y-2.5">
-        <SectionHeader>Amounts</SectionHeader>
-        <NumberField
-          label={`Base Amount (${baseAsset})`}
-          value={state.base_amount}
-          field="base_amount"
-          dispatch={d}
-          step={0.001}
-          min={0}
-        />
-        <NumberField
-          label={`Quote Amount (${quoteAsset})`}
-          value={state.quote_amount}
-          field="quote_amount"
-          dispatch={d}
-          step={0.001}
-          min={0}
-        />
-      </div>
-
       {/* Auto-close triggers */}
       <div className="space-y-2.5">
         <SectionHeader>Auto-Close Triggers</SectionHeader>
@@ -641,19 +656,54 @@ export function LPConfigPanel({
             state.lower_limit_price > 0 && state.lower_limit_price < state.lower_price
           }
           hint="Close when price falls to this level"
-          pickable={false}
         />
         <p className="text-[10px] text-[var(--color-text-muted)]">
           Both only fire while the position is out of range. Leave at 0 for no trigger.
         </p>
       </div>
 
-      <AdvancedSection
-        open={state.showAdvanced}
-        onToggle={() =>
-          d({ type: "SET_FIELD", field: "showAdvanced", value: !state.showAdvanced })
-        }
-      >
+      {/* Amounts */}
+      <div className="space-y-2.5">
+        <SectionHeader>Amounts</SectionHeader>
+        <div>
+          <NumberField
+            label={`Base Amount (${baseAsset})`}
+            value={state.base_amount}
+            field="base_amount"
+            dispatch={d}
+            step={0.001}
+            min={0}
+          />
+          <PercentPresets
+            available={baseAvailable}
+            symbol={baseAsset}
+            onPick={(pct) =>
+              d({ type: "SET_FIELD", field: "base_amount", value: sizeFrom(baseAvailable, pct) })
+            }
+          />
+        </div>
+        <div>
+          <NumberField
+            label={`Quote Amount (${quoteAsset})`}
+            value={state.quote_amount}
+            field="quote_amount"
+            dispatch={d}
+            step={0.001}
+            min={0}
+          />
+          <PercentPresets
+            available={quoteAvailable}
+            symbol={quoteAsset}
+            onPick={(pct) =>
+              d({ type: "SET_FIELD", field: "quote_amount", value: sizeFrom(quoteAvailable, pct) })
+            }
+          />
+        </div>
+      </div>
+
+      {/* On Close — a decision about the tokens you get back, not a tuning knob. */}
+      <div className="space-y-2">
+        <SectionHeader>On Close</SectionHeader>
         <ToggleField
           label="Keep Position"
           value={state.keep_position}
@@ -665,7 +715,17 @@ export function LPConfigPanel({
           back to {quoteAsset}. This sets the config field; stopping from the
           executors table asks again.
         </p>
-        {isMeteoraProvider(state.lp_provider) && (
+      </div>
+
+      {/* Rendered only when there is something under it: everything else that
+          once lived here is now a first-class control. */}
+      {isMeteoraProvider(state.lp_provider) && (
+        <AdvancedSection
+          open={state.showAdvanced}
+          onToggle={() =>
+            d({ type: "SET_FIELD", field: "showAdvanced", value: !state.showAdvanced })
+          }
+        >
           <SelectField
             label="Meteora Strategy"
             value={state.strategy_type}
@@ -673,8 +733,8 @@ export function LPConfigPanel({
             dispatch={d}
             options={STRATEGY_TYPE_OPTIONS}
           />
-        )}
-      </AdvancedSection>
+        </AdvancedSection>
+      )}
 
       <ValidationMessages errors={validation.errors} warnings={warnings} />
     </div>
diff --git a/frontend/src/components/executor/OrderConfigPanel.tsx b/frontend/src/components/executor/OrderConfigPanel.tsx
index ada09094..2a9b3aab 100644
--- a/frontend/src/components/executor/OrderConfigPanel.tsx
+++ b/frontend/src/components/executor/OrderConfigPanel.tsx
@@ -5,6 +5,7 @@ import {
   AmountField,
   LeverageField,
   NumberField,
+  PercentPresets,
   PriceField,
   SectionHeader,
   SelectField,
@@ -12,7 +13,7 @@ import {
   ValidationMessages,
   type FieldDispatch,
 } from "./fields";
-import type { ChartPriceMapping, ExecutorValidation } from "./types";
+import type { ChartPriceMapping, ExecutorValidation, PickSlot } from "./types";
 
 // ── State ──
 
@@ -146,7 +147,7 @@ export function useOrderConfig() {
 
   const save = () => saveDefaults(state);
 
-  const handleChartPriceSet = (field: "start" | "end" | "limit", price: number) => {
+  const handleChartPriceSet = (field: PickSlot, price: number) => {
     if (field === "start") {
       dispatch({ type: "SET_FIELD", field: "price", value: price });
     }
@@ -184,10 +185,33 @@ interface Props {
    * book, so a DEX passes `["MARKET"]`. Defaults to all of them.
    */
   strategies?: string[];
+  /** Wallet balance behind the percentage presets; `null` when it is unknown. */
+  baseAvailable?: number | null;
+  quoteAvailable?: number | null;
+  /**
+   * Display symbols for the two tokens. A DEX `trading_pair` is
+   * `<base_mint>-<quote_symbol>`, so its base half is an address, not a ticker.
+   */
+  baseSymbol?: string;
+  quoteSymbol?: string;
 }
 
-export function OrderConfigPanel({ state, dispatch, validation, currentPrice, isSpot = false, pair, strategies }: Props) {
+export function OrderConfigPanel({
+  state,
+  dispatch,
+  validation,
+  currentPrice,
+  isSpot = false,
+  pair,
+  strategies,
+  baseAvailable = null,
+  quoteAvailable = null,
+  baseSymbol,
+  quoteSymbol,
+}: Props) {
   const d = dispatch as FieldDispatch;
+  const displayBase = baseSymbol || pair?.split("-")[0] || "base";
+  const displayQuote = quoteSymbol || pair?.split("-")[1] || "quote";
   const options = strategies
     ? STRATEGY_OPTIONS.filter((o) => strategies.includes(o.value))
     : STRATEGY_OPTIONS;
@@ -206,6 +230,25 @@ export function OrderConfigPanel({ state, dispatch, validation, currentPrice, is
     (state.execution_strategy === "LIMIT" || state.execution_strategy === "LIMIT_MAKER");
   const isChaser = allowed && state.execution_strategy === "LIMIT_CHASER";
 
+  // The amount is always in base units, but which balance funds it is not: a spot
+  // BUY spends quote and has to be divided by the price to become base, a spot
+  // SELL spends the base itself. A perp buys margin with quote either way, and the
+  // position it opens is that margin times the leverage.
+  const sizingPrice = needsPrice && state.price > 0 ? state.price : currentPrice;
+  const spendsBase = isSpot && state.side === 2;
+  const spendable = spendsBase ? baseAvailable : quoteAvailable;
+  const spendSymbol = spendsBase ? displayBase : displayQuote;
+  const canSize = spendsBase || (!!sizingPrice && sizingPrice > 0);
+
+  const pickPercent = (pct: number) => {
+    if (spendable === null || spendable <= 0) return;
+    const spend = spendable * pct;
+    const amount = spendsBase
+      ? spend
+      : (spend * (isSpot ? 1 : state.leverage)) / (sizingPrice as number);
+    dispatch({ type: "SET_FIELD", field: "amount", value: Number(amount.toPrecision(8)) });
+  };
+
   return (
     <div className="flex flex-col gap-4 overflow-y-auto p-3">
       {/* Direction */}
@@ -214,14 +257,23 @@ export function OrderConfigPanel({ state, dispatch, validation, currentPrice, is
       {/* Order Config */}
       <div className="space-y-2.5">
         <SectionHeader>Order</SectionHeader>
-        <AmountField
-          value={state.amount}
-          field="amount"
-          dispatch={d}
-          currentPrice={currentPrice}
-          step={0.001}
-          pair={pair}
-        />
+        <div>
+          <AmountField
+            value={state.amount}
+            field="amount"
+            dispatch={d}
+            currentPrice={currentPrice}
+            step={0.001}
+            baseSymbol={displayBase}
+            quoteSymbol={displayQuote}
+          />
+          <PercentPresets
+            available={canSize ? spendable : null}
+            symbol={spendSymbol}
+            onPick={pickPercent}
+            label={`Available ${spendSymbol} to spend`}
+          />
+        </div>
         <SelectField
           label="Execution Strategy"
           value={state.execution_strategy}
diff --git a/frontend/src/components/executor/PositionConfigPanel.tsx b/frontend/src/components/executor/PositionConfigPanel.tsx
index e0e77ea2..d46330c1 100644
--- a/frontend/src/components/executor/PositionConfigPanel.tsx
+++ b/frontend/src/components/executor/PositionConfigPanel.tsx
@@ -14,7 +14,7 @@ import {
   ORDER_TYPE_OPTIONS,
   type FieldDispatch,
 } from "./fields";
-import type { ChartPriceMapping, ExecutorValidation, ExtraLine } from "./types";
+import type { ChartPriceMapping, ExecutorValidation, ExtraLine, PickSlot } from "./types";
 import { getThemeColors } from "@/lib/theme-colors";
 
 // ── State ──
@@ -202,7 +202,7 @@ export function usePositionConfig() {
 
   const save = () => saveDefaults(state);
 
-  const handleChartPriceSet = (field: "start" | "end" | "limit", price: number) => {
+  const handleChartPriceSet = (field: PickSlot, price: number) => {
     if (field === "start") {
       dispatch({ type: "SET_FIELD", field: "entry_price", value: price });
     }
diff --git a/frontend/src/components/executor/fields.tsx b/frontend/src/components/executor/fields.tsx
index 90c3955f..6869c91a 100644
--- a/frontend/src/components/executor/fields.tsx
+++ b/frontend/src/components/executor/fields.tsx
@@ -31,9 +31,9 @@ export function PriceField({
   valid: boolean;
   hint?: string;
   /**
-   * Whether this price can be picked off the chart. The chart carries exactly
-   * three pick slots (start/end/limit), so a panel with a fourth price offers no
-   * crosshair for it rather than a button that does nothing.
+   * Whether this price can be picked off the chart. A panel that has run out of
+   * pick slots turns the crosshair off for the remaining prices rather than
+   * offering a button that does nothing.
    */
   pickable?: boolean;
 }) {
@@ -103,6 +103,61 @@ export function PriceField({
   );
 }
 
+// ── PercentPresets ──
+
+/** Fractions of the available balance the presets offer. */
+export const PERCENT_PRESETS = [0.1, 0.25, 0.5, 1] as const;
+
+function formatAvailable(value: number): string {
+  if (value === 0) return "0";
+  if (value >= 1000) return value.toLocaleString(undefined, { maximumFractionDigits: 2 });
+  if (value >= 1) return String(Number(value.toFixed(4)));
+  return String(Number(value.toPrecision(4)));
+}
+
+/**
+ * Size a field off the wallet instead of by typing.
+ *
+ * `available === null` means the balance is unknown (not held, or the portfolio
+ * has not arrived): the buttons go inert rather than sizing an order off a zero
+ * that was never a real balance.
+ */
+export function PercentPresets({
+  available,
+  symbol,
+  onPick,
+  label,
+}: {
+  available: number | null;
+  symbol?: string;
+  onPick: (fraction: number) => void;
+  /** Overrides the "Avail" caption — e.g. naming the token being spent. */
+  label?: string;
+}) {
+  const usable = available !== null && available > 0;
+  return (
+    <div className="mt-1 flex items-center gap-1">
+      {PERCENT_PRESETS.map((pct) => (
+        <button
+          key={pct}
+          type="button"
+          disabled={!usable}
+          onClick={() => onPick(pct)}
+          className="flex-1 rounded border border-[var(--color-border)] bg-[var(--color-surface)] py-0.5 text-[10px] text-[var(--color-text-muted)] transition-colors hover:bg-[var(--color-surface-hover)] hover:text-[var(--color-text)] disabled:cursor-not-allowed disabled:opacity-30"
+        >
+          {pct * 100}%
+        </button>
+      ))}
+      <span
+        className="ml-1 shrink-0 font-mono text-[10px] text-[var(--color-text-muted)]"
+        title={label ?? "Available balance"}
+      >
+        {available === null ? "—" : formatAvailable(available)} {symbol ?? ""}
+      </span>
+    </div>
+  );
+}
+
 // ── NumberField ──
 
 export function NumberField({
@@ -348,6 +403,8 @@ export function AmountField({
   step = 0.001,
   min = 0,
   pair,
+  baseSymbol,
+  quoteSymbol,
 }: {
   value: number;
   field: string;
@@ -356,13 +413,20 @@ export function AmountField({
   step?: number;
   min?: number;
   pair?: string;
+  /**
+   * Token tickers, when the pair cannot supply them. A DEX `trading_pair` is
+   * `<base_mint>-<quote_symbol>`, so splitting it labels the field with a mint
+   * address.
+   */
+  baseSymbol?: string;
+  quoteSymbol?: string;
 }) {
   const [inQuote, setInQuote] = useState(false);
   const id = useId();
   const inputRef = useRef<HTMLInputElement>(null);
 
-  const baseAsset = pair?.split("-")[0] ?? "base";
-  const quoteAsset = pair?.split("-")[1] ?? "quote";
+  const baseAsset = baseSymbol ?? pair?.split("-")[0] ?? "base";
+  const quoteAsset = quoteSymbol ?? pair?.split("-")[1] ?? "quote";
 
   // When inQuote mode, show quote value; dispatch always stores base amount
   const displayValue = inQuote && currentPrice && currentPrice > 0 ? value * currentPrice : value;
diff --git a/frontend/src/components/executor/types.ts b/frontend/src/components/executor/types.ts
index 1b44c049..ea549dad 100644
--- a/frontend/src/components/executor/types.ts
+++ b/frontend/src/components/executor/types.ts
@@ -16,13 +16,22 @@ export interface ExtraLine {
   lineWidth?: number;
 }
 
+/**
+ * A price the chart can hand back when the user clicks it.
+ *
+ * `start` / `end` / `limit` are the three lines the chart draws itself; `limit2`
+ * is a fourth slot for a price a panel draws as an extra line (the LP lower
+ * limit), so a panel with four prices offers a crosshair for every one of them.
+ */
+export type PickSlot = "start" | "end" | "limit" | "limit2";
+
 export interface ChartPriceMapping {
   startPrice: number;
   endPrice: number;
   limitPrice: number;
   side: 1 | 2;
   minSpread: number;
-  activePickField: "start" | "end" | "limit" | null;
+  activePickField: PickSlot | null;
   extraLines?: ExtraLine[];
 }
 
diff --git a/frontend/src/components/trade/TradeBottomPane.tsx b/frontend/src/components/trade/TradeBottomPane.tsx
index ae3b307f..0f2d9104 100644
--- a/frontend/src/components/trade/TradeBottomPane.tsx
+++ b/frontend/src/components/trade/TradeBottomPane.tsx
@@ -21,6 +21,14 @@ interface TradeBottomPaneProps {
   connector: string;
   pair: string;
   isSpot: boolean;
+  /**
+   * Tickers for the balance bar, when the pair cannot supply them. A DEX
+   * `trading_pair` is `<base_mint>-<quote_symbol>`, so splitting it looks the base
+   * balance up under a mint address and never finds one — which is why a Solana
+   * pool used to show its quote balance alone.
+   */
+  baseSymbol?: string;
+  quoteSymbol?: string;
   selectedExecutorId?: string | null;
   onExecutorSelect?: (executor: ExecutorInfo | null) => void;
 }
@@ -236,6 +244,8 @@ export function TradeBottomPane({
   connector,
   pair,
   isSpot,
+  baseSymbol,
+  quoteSymbol,
   selectedExecutorId,
   onExecutorSelect,
 }: TradeBottomPaneProps) {
@@ -264,16 +274,23 @@ export function TradeBottomPane({
     refetchInterval: 30_000,
   });
 
-  // Extract base/quote tokens from pair (e.g. "BTC-USDT" -> ["BTC", "USDT"])
-  const [baseToken, quoteToken] = pair.split("-");
+  // Extract base/quote tokens from pair (e.g. "BTC-USDT" -> ["BTC", "USDT"]),
+  // unless the caller knows better — see baseSymbol/quoteSymbol.
+  const [pairBase, pairQuote] = pair.split("-");
+  const baseToken = baseSymbol || pairBase;
+  const quoteToken = quoteSymbol || pairQuote;
 
   // Find balances for the active connector
   const connectorBalances = portfolio?.connectors?.find(
     (c) => c.connector === connector,
   )?.balances;
 
-  const baseBalance = connectorBalances?.find((b) => b.token === baseToken);
-  const quoteBalance = connectorBalances?.find((b) => b.token === quoteToken);
+  const baseBalance = connectorBalances?.find(
+    (b) => b.token.toUpperCase() === (baseToken ?? "").toUpperCase(),
+  );
+  const quoteBalance = connectorBalances?.find(
+    (b) => b.token.toUpperCase() === (quoteToken ?? "").toUpperCase(),
+  );
 
   const stopMutation = useMutation({
     mutationFn: (id: string) => {
diff --git a/frontend/src/components/trade/TradeChart.tsx b/frontend/src/components/trade/TradeChart.tsx
index c5395591..36fc853e 100644
--- a/frontend/src/components/trade/TradeChart.tsx
+++ b/frontend/src/components/trade/TradeChart.tsx
@@ -4,12 +4,20 @@ import { createPortal } from "react-dom";
 import { useCandleStore } from "@/hooks/useCandleStore";
 import { api, type ConsolidatedPosition } from "@/lib/api";
 import { candleStore } from "@/lib/candle-store";
-import type { ExtraLine } from "@/components/executor/types";
+import type { ExtraLine, PickSlot } from "@/components/executor/types";
 import { getExecutorColor, type ExecutorOverlay } from "@/lib/executor-overlays";
 import { getThemeColors, pnlHexColor, sideColor } from "@/lib/theme-colors";
 import { escapeHtml, formatCompactUsd } from "@/lib/formatters";
 
-type PickField = "start" | "end" | "limit" | null;
+type PickField = PickSlot | null;
+
+/** What each pick slot is called in the hint the chart shows while picking. */
+const PICK_LABELS: Record<PickSlot, string> = {
+  start: "start",
+  end: "end",
+  limit: "limit",
+  limit2: "lower limit",
+};
 
 /**
  * The chart's price mapping, and nothing else.
@@ -48,7 +56,7 @@ interface TradeChartProps {
   totalAmountQuote?: number;
   minOrderAmountQuote?: number;
   activePickField: PickField;
-  onPriceSet: (field: "start" | "end" | "limit", price: number) => void;
+  onPriceSet: (field: PickSlot, price: number) => void;
   pricePrecision?: number;
   extraLines?: ExtraLine[];
   executorOverlays?: ExecutorOverlay[];
@@ -389,9 +397,6 @@ export function TradeChart({
             // startPrice is the box's upper edge (see computeLpOverlay).
             addRow("Upper Price", fmtPrice(o.gridBox.startPrice));
             addRow("Lower Price", fmtPrice(o.gridBox.endPrice));
-            const cfgLower = Number(cfg.lower_limit_price);
-            if (o.gridBox.limitPrice) addRow("Upper Limit", fmtPrice(o.gridBox.limitPrice));
-            if (cfgLower > 0) addRow("Lower Limit", fmtPrice(cfgLower));
             if (cfg.lp_provider != null) addRow("Provider", String(cfg.lp_provider));
           } else {
             addRow("Start Price", fmtPrice(o.gridBox.startPrice));
@@ -989,10 +994,10 @@ export function TradeChart({
       {activePickField && (
         <div className="flex items-center justify-between border-b border-[var(--color-border)] bg-[var(--color-bg)] px-3 py-1.5">
           <p className="text-[10px] text-[var(--color-text-muted)]">
-            Click on chart to set {activePickField} price
+            Click on chart to set {PICK_LABELS[activePickField]} price
           </p>
           <span className="animate-pulse rounded bg-[var(--color-primary)]/20 px-2 py-0.5 text-xs text-[var(--color-primary)]">
-            Pick mode: {activePickField}
+            Pick mode: {PICK_LABELS[activePickField]}
           </span>
         </div>
       )}
diff --git a/frontend/src/hooks/useMainControllerData.ts b/frontend/src/hooks/useMainControllerData.ts
index 6089e192..4668e89c 100644
--- a/frontend/src/hooks/useMainControllerData.ts
+++ b/frontend/src/hooks/useMainControllerData.ts
@@ -11,10 +11,42 @@ function executorsFingerprint(exs: ExecutorInfo[]): string {
     .join("|");
 }
 
+/** The pool an executor traded in, from wherever it records one. */
+function executorPool(ex: ExecutorInfo): string {
+  return (
+    (ex.config?.pool_address as string | undefined) ||
+    (ex.custom_info?.pool_address as string | undefined) ||
+    ""
+  );
+}
+
+interface Options {
+  /**
+   * A second spelling of the same market, queried alongside `pair`.
+   *
+   * One DEX market has two names: the `<base_mint>-<quote>` form a pool-first UI
+   * builds, and the `<base_symbol>-<quote>` form an executor created from
+   * Telegram or MCP carries. Neither is wrong and neither can be derived from the
+   * other by string work, so both are asked for and the results merged --
+   * otherwise a live LP position is simply invisible on its own pool's page.
+   */
+  altPair?: string;
+  /**
+   * Keep only the liquidity positions held in this exact pool.
+   *
+   * On a pool-first page the pair is not the identity -- `SOL-USDC` names dozens
+   * of pools -- and a position lives in exactly one of them, so an LP executor
+   * that records a different pool is dropped. Swaps are not filtered: an order is
+   * a fact about the pair, and the router picks its own pool for it.
+   */
+  poolAddress?: string;
+}
+
 export function useMainControllerData(
   server: string | null,
   connector: string,
   pair: string,
+  { altPair = "", poolAddress = "" }: Options = {},
 ) {
   // Fetch executors filtered server-side by controller_id + trading_pair
   const { data: cachedExecutors } = useQuery<ExecutorInfo[]>({
@@ -25,11 +57,34 @@ export function useMainControllerData(
     refetchOnWindowFocus: false,
   });
 
-  // connector is not a server-side filter — filter client-side (lightweight)
+  // Same query under the market's other name. The WS bridge refreshes every
+  // 4-element ["executors", server, controller, pair] key it finds, so this one
+  // stays as live as the primary without any wiring of its own.
+  const wantsAlt = !!altPair && altPair !== pair;
+  const { data: altExecutors } = useQuery<ExecutorInfo[]>({
+    queryKey: ["executors", server, "main", altPair],
+    queryFn: () => api.getExecutors(server!, { controller_id: "main", trading_pair: altPair }),
+    enabled: !!server && wantsAlt,
+    staleTime: 30_000,
+    refetchOnWindowFocus: false,
+  });
+
+  // connector and pool are not server-side filters — apply them client-side
   const filteredExecutors = useMemo(() => {
-    if (!cachedExecutors) return [];
-    return cachedExecutors.filter((ex) => ex.connector === connector);
-  }, [cachedExecutors, connector]);
+    const seen = new Set<string>();
+    const rows: ExecutorInfo[] = [];
+    for (const ex of [...(cachedExecutors ?? []), ...(wantsAlt ? altExecutors ?? [] : [])]) {
+      if (seen.has(ex.id)) continue;
+      seen.add(ex.id);
+      if (ex.connector !== connector) continue;
+      if (poolAddress && ex.type?.toLowerCase() === "lp") {
+        const pool = executorPool(ex);
+        if (pool && pool !== poolAddress) continue;
+      }
+      rows.push(ex);
+    }
+    return rows;
+  }, [cachedExecutors, altExecutors, wantsAlt, connector, poolAddress]);
 
   // Stable reference: only update when executor data actually changes
   const prevFingerprintRef = useRef("");
@@ -62,14 +117,17 @@ export function useMainControllerData(
       ...(positionsData.executor_positions ?? []),
       ...(positionsData.bot_positions ?? []),
     ];
+    // A position is named the same two ways its executor is, so both spellings
+    // of the market count as this market.
+    const pairs = new Set([pair, ...(wantsAlt ? [altPair] : [])]);
     return all.filter(
       (p) =>
         // Show positions from main controller or untagged (executor-level positions)
         (!p.controller_id || p.controller_id === "main") &&
         p.connector_name === connector &&
-        p.trading_pair === pair,
+        pairs.has(p.trading_pair),
     );
-  }, [positionsData, connector, pair]);
+  }, [positionsData, connector, pair, altPair, wantsAlt]);
 
   return { executors, overlays, positions, isLoadingPositions };
 }
diff --git a/frontend/src/hooks/usePairBalances.ts b/frontend/src/hooks/usePairBalances.ts
new file mode 100644
index 00000000..1868d292
--- /dev/null
+++ b/frontend/src/hooks/usePairBalances.ts
@@ -0,0 +1,50 @@
+import { useQuery } from "@tanstack/react-query";
+
+import { api } from "@/lib/api";
+
+/**
+ * What the wallet holds of a pair's two tokens on one connector.
+ *
+ * `null` means "not held" (or not known yet) rather than zero, so a panel can
+ * tell a wallet with no SOL apart from one whose portfolio has not loaded, and
+ * grey out the percentage presets instead of sizing an order off a fake 0.
+ */
+export interface PairBalances {
+  base: number | null;
+  quote: number | null;
+}
+
+/**
+ * Available base/quote balance for a pair on a connector.
+ *
+ * Symbols are passed in rather than split off `trading_pair`, because a DEX pair
+ * is `<base_mint>-<quote_symbol>`: splitting it would look up a balance under a
+ * mint address and never find one. Shares the `["portfolio", server]` query with
+ * the trade pane, so opening a pool adds no extra request.
+ */
+export function usePairBalances(
+  server: string | null,
+  connector: string,
+  baseSymbol: string | undefined,
+  quoteSymbol: string | undefined,
+): PairBalances {
+  const { data: portfolio } = useQuery({
+    queryKey: ["portfolio", server],
+    queryFn: () => api.getPortfolio(server!),
+    enabled: !!server,
+    refetchInterval: 30_000,
+  });
+
+  const balances = portfolio?.connectors?.find(
+    (c) => c.connector === connector,
+  )?.balances;
+
+  const find = (symbol: string | undefined) => {
+    if (!symbol) return null;
+    const upper = symbol.toUpperCase();
+    const hit = balances?.find((b) => b.token.toUpperCase() === upper);
+    return hit ? hit.available : null;
+  };
+
+  return { base: find(baseSymbol), quote: find(quoteSymbol) };
+}
diff --git a/frontend/src/lib/api.ts b/frontend/src/lib/api.ts
index c725a081..9211259a 100644
--- a/frontend/src/lib/api.ts
+++ b/frontend/src/lib/api.ts
@@ -312,6 +312,9 @@ export interface PoolSummary {
   /** Gateway CLMM only: Meteora reports `apr` as 24h fee/TVL, `apy` annualized. */
   apr?: number | null;
   apy?: number | null;
+  /** True when `apr`/`apy` were derived from volume x fee tier, not reported. */
+  apr_estimated?: boolean;
+  fees_24h?: number | null;
   bin_step?: number | null;
   base_fee_percentage?: number | null;
   pool_created_at?: string | null;
@@ -336,19 +339,19 @@ export interface PoolBins {
 }
 
 export interface PoolQuery {
-  source: "gecko" | "gateway";
+  source: "gecko" | "gateway" | "orca";
   /** source=gecko: the chain, as a Gateway network id or a gecko chain id. */
   network?: string;
   /** source=gecko: trending | top | new | token. */
   view?: string;
   /** source=gateway: the CLMM connector. */
   connector?: string;
-  /** source=gecko+view=token: a token address. source=gateway: free text. */
+  /** source=gecko+view=token: a token address. source=gateway|orca: free text. */
   query?: string;
   /** source=gecko: GeckoTerminal dex ids to keep. Empty means every venue. */
   dexes?: string[];
   limit?: number;
-  /** 1-based. Both upstreams page; neither reports a total. */
+  /** 1-based. Every upstream pages; only orca knows whether a next page exists. */
   page?: number;
 }
 
diff --git a/frontend/src/lib/executor-overlays.ts b/frontend/src/lib/executor-overlays.ts
index ef0e087c..15736e17 100644
--- a/frontend/src/lib/executor-overlays.ts
+++ b/frontend/src/lib/executor-overlays.ts
@@ -288,11 +288,16 @@ function computeGridOverlay(executor: ExecutorInfo): ExecutorOverlay {
 /**
  * A CLMM liquidity position, drawn as the grid it structurally is.
  *
- * `lower_price` / `upper_price` are the range the position earns fees in, and the
- * schema itself describes `upper_limit_price` / `lower_limit_price` as
- * "grid-executor style" auto-close triggers. That is a one-to-one match with
- * `GridBox`, and `TradeChart` draws boxes without ever reading `type` — so no new
- * drawing code is involved, only a second producer of the same struct.
+ * `lower_price` / `upper_price` are the range the position earns fees in, which is
+ * a one-to-one match with `GridBox`, and `TradeChart` draws boxes without ever
+ * reading `type` — so no new drawing code is involved, only a second producer of
+ * the same struct.
+ *
+ * The `*_limit_price` auto-close triggers are deliberately left off an open
+ * position: they are a decision made once, while the range is being drawn, and on
+ * the chart afterwards they are two more red lines competing with the bounds that
+ * actually say whether the position is still earning. LPConfigPanel still draws
+ * them while you set them.
  */
 function computeLpOverlay(executor: ExecutorInfo): ExecutorOverlay {
   const customInfo = executor.custom_info || {};
@@ -309,8 +314,6 @@ function computeLpOverlay(executor: ExecutorInfo): ExecutorOverlay {
   };
   const lower = num(customInfo.lower_price ?? customInfo.price_lower ?? config.lower_price);
   const upper = num(customInfo.upper_price ?? customInfo.price_upper ?? config.upper_price);
-  const upperLimit = num(customInfo.upper_limit_price ?? config.upper_limit_price);
-  const lowerLimit = num(customInfo.lower_limit_price ?? config.lower_limit_price);
 
   const start = executor.timestamp > 0 ? executor.timestamp : Math.floor(Date.now() / 1000);
   const end = executor.close_timestamp > 0 ? executor.close_timestamp : Math.floor(Date.now() / 1000);
@@ -324,21 +327,10 @@ function computeLpOverlay(executor: ExecutorInfo): ExecutorOverlay {
       // overlay puts start_price (the far bound) first, so upper goes first here.
       startPrice: upper,
       endPrice: lower,
-      limitPrice: upperLimit > 0 ? upperLimit : undefined,
       color: pnlHexColor(executor.pnl >= 0 ? 1 : -1),
     };
   }
 
-  // Both triggers, as full-width lines. TradeChart only draws these for a running
-  // or selected executor, which is exactly when they are actionable.
-  const lines: PriceLine[] = [];
-  if (upperLimit > 0) {
-    lines.push({ price: upperLimit, label: "Upper limit", color: getThemeColors().red, style: "dotted" });
-  }
-  if (lowerLimit > 0) {
-    lines.push({ price: lowerLimit, label: "Lower limit", color: getThemeColors().red, style: "dotted" });
-  }
-
   return {
     executorId: executor.id,
     type: "lp",
@@ -349,7 +341,7 @@ function computeLpOverlay(executor: ExecutorInfo): ExecutorOverlay {
     pnlPct: executor.net_pnl_pct,
     volume: executor.volume,
     fees: executor.cum_fees_quote,
-    priceLines: lines,
+    priceLines: [],
     markers: [],
     gridBox,
     timeRange: { start, end },
diff --git a/frontend/src/pages/CreateExecutor.tsx b/frontend/src/pages/CreateExecutor.tsx
index bf737050..7178d490 100644
--- a/frontend/src/pages/CreateExecutor.tsx
+++ b/frontend/src/pages/CreateExecutor.tsx
@@ -32,6 +32,7 @@ import { DCAConfigPanel, useDCAConfig } from "@/components/executor/DCAConfigPan
 import { LPConfigPanel, useLpConfig } from "@/components/executor/LPConfigPanel";
 import { TradeBottomPane } from "@/components/trade/TradeBottomPane";
 import { useCandleStore } from "@/hooks/useCandleStore";
+import { usePairBalances } from "@/hooks/usePairBalances";
 import { useServer } from "@/hooks/useServer";
 import { useCondorWebSocket } from "@/hooks/useWebSocket";
 import { useMainControllerData } from "@/hooks/useMainControllerData";
@@ -40,7 +41,7 @@ import { useResizeDrag } from "@/hooks/useResizeDrag";
 import { api } from "@/lib/api";
 import { candleStore } from "@/lib/candle-store";
 import { connectorCapabilities } from "@/lib/connector-capabilities";
-import type { ExecutorType } from "@/components/executor/types";
+import type { ExecutorType, PickSlot } from "@/components/executor/types";
 import {
   gridReducer,
   isSpotConnector,
@@ -103,6 +104,13 @@ export function CreateExecutor() {
   const connector = gridState.connector;
   const pair = gridState.pair;
   const isSpot = isSpotConnector(connector);
+  // A CLOB pair is already <BASE>-<QUOTE>, so the tickers come off the split.
+  const balances = usePairBalances(
+    server ?? null,
+    connector,
+    pair?.split("-")[0],
+    pair?.split("-")[1],
+  );
 
   // The venue the URL asked for, kept after the param is stripped below: the
   // redirect guard cannot read it from the URL any more, and it must not fire
@@ -350,9 +358,12 @@ export function CreateExecutor() {
 
   // Chart price set handler
   const handlePriceSet = useMemo(
-    () => (field: "start" | "end" | "limit", price: number) => {
+    () => (field: PickSlot, price: number) => {
       switch (executorType) {
         case "grid":
+          // The grid panel arms only start/end/limit; `limit2` belongs to the LP
+          // lower limit and would name a grid field that does not exist.
+          if (field === "limit2") break;
           gridDispatch({ type: "SET_FIELD", field: `${field}_price`, value: price });
           gridDispatch({ type: "SET_FIELD", field: "activePickField", value: null });
           break;
@@ -669,13 +680,13 @@ export function CreateExecutor() {
                   <PositionConfigPanel state={positionConfig.state} dispatch={positionConfig.dispatch} validation={positionConfig.validation} currentPrice={currentPrice} isSpot={isSpot} pair={pair} />
                 )}
                 {executorType === "order" && (
-                  <OrderConfigPanel state={orderConfig.state} dispatch={orderConfig.dispatch} validation={orderConfig.validation} currentPrice={currentPrice} isSpot={isSpot} pair={pair} strategies={caps.orderStrategies} />
+                  <OrderConfigPanel state={orderConfig.state} dispatch={orderConfig.dispatch} validation={orderConfig.validation} currentPrice={currentPrice} isSpot={isSpot} pair={pair} strategies={caps.orderStrategies} baseAvailable={balances.base} quoteAvailable={balances.quote} />
                 )}
                 {executorType === "dca" && (
                   <DCAConfigPanel state={dcaConfig.state} dispatch={dcaConfig.dispatch} validation={dcaConfig.validation} currentPrice={currentPrice} isSpot={isSpot} pair={pair} />
                 )}
                 {executorType === "lp" && (
-                  <LPConfigPanel state={lpConfig.state} dispatch={lpConfig.dispatch} validation={lpConfig.validation} currentPrice={currentPrice} pair={pair} pool={lpConfig.pool} poolFetching={lpConfig.poolFetching} />
+                  <LPConfigPanel state={lpConfig.state} dispatch={lpConfig.dispatch} validation={lpConfig.validation} currentPrice={currentPrice} pair={pair} pool={lpConfig.pool} poolFetching={lpConfig.poolFetching} baseAvailable={balances.base} quoteAvailable={balances.quote} />
                 )}
               </div>
 
diff --git a/frontend/src/pages/CreateGridExecutor.tsx b/frontend/src/pages/CreateGridExecutor.tsx
index 5cfdf972..d007ff5b 100644
--- a/frontend/src/pages/CreateGridExecutor.tsx
+++ b/frontend/src/pages/CreateGridExecutor.tsx
@@ -20,6 +20,7 @@ import {
   INTERVALS,
   LOOKBACK_OPTIONS,
 } from "@/lib/gridExecutor";
+import type { PickSlot } from "@/components/executor/types";
 
 // ── Page ──
 
@@ -140,7 +141,9 @@ export function CreateGridExecutor() {
   });
 
   const handlePriceSet = useMemo(
-    () => (field: "start" | "end" | "limit", price: number) => {
+    () => (field: PickSlot, price: number) => {
+      // The grid panel arms only start/end/limit; a fourth slot names no field.
+      if (field === "limit2") return;
       dispatch({ type: "SET_FIELD", field: `${field}_price`, value: price });
       dispatch({ type: "SET_FIELD", field: "activePickField", value: null });
     },

From 7562d3d300a1bbdfb73cf5507fd74ede47023bcd Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Mon, 17 Aug 2026 14:10:27 +0300
Subject: [PATCH 104/116] (test) guard tests for shipped behaviour that had
 none

Six regressions that were fixed but never pinned: the controller status
field that reports a hardcoded "running" regardless of the kill switch,
the wallet import that promoted a key to chain default with the box
unticked, the issue-form prefill that GitHub drops silently when a field
id is renamed, what a bot-mode session can reconstruct about its own
executors, the /update pipeline's frontend rebuild and clean restart,
and the build-identity endpoint's fields and its refusal to answer
anyone logged out.
---
 tests/test_controller_kill_switch_state.py  | 197 ++++++++
 tests/test_gateway_wallet_default_optout.py | 149 ++++++
 tests/test_issue_template_contract.py       |  80 ++++
 tests/test_session_bot_visibility.py        | 483 ++++++++++++++++++++
 tests/test_update_restart_flow.py           | 208 +++++++++
 tests/test_web_meta_env.py                  |  66 +++
 6 files changed, 1183 insertions(+)
 create mode 100644 tests/test_controller_kill_switch_state.py
 create mode 100644 tests/test_gateway_wallet_default_optout.py
 create mode 100644 tests/test_issue_template_contract.py
 create mode 100644 tests/test_session_bot_visibility.py
 create mode 100644 tests/test_update_restart_flow.py
 create mode 100644 tests/test_web_meta_env.py

diff --git a/tests/test_controller_kill_switch_state.py b/tests/test_controller_kill_switch_state.py
new file mode 100644
index 00000000..e5310fec
--- /dev/null
+++ b/tests/test_controller_kill_switch_state.py
@@ -0,0 +1,197 @@
+"""Controller run state and kill-switch writes in the hummingbot MCP bot tools.
+
+The per-controller ``status`` the API reports is a hardcoded "running" that only
+flips to "error" when the performance report fails to parse — it never reflects a
+controller stopped via its kill switch. A trading agent read that field as proof
+that ``stop_controllers`` had failed and stopped/redeployed whole bots for nothing,
+so these tests pin the derived state and the write-then-verify behavior.
+"""
+
+import asyncio
+import copy
+
+import pytest
+
+from mcp_servers.hummingbot_api.formatters import format_controller_state
+from mcp_servers.hummingbot_api.tools import bot_management as bm
+
+CONFIGS = [
+    {"id": "eth_ctrl", "_config_name": "eth_ctrl", "manual_kill_switch": True},
+    {"id": "btc_ctrl", "_config_name": "btc_ctrl", "manual_kill_switch": False},
+    # config file name differs from the controller id the status payload uses
+    {"id": "sol_ctrl", "_config_name": "sol_file", "manual_kill_switch": False},
+]
+
+STATUS = {
+    "data": {
+        "bot-1": {
+            "status": "running",
+            "performance": {
+                "eth_ctrl": {"status": "running", "performance": {}},
+                "btc_ctrl": {"status": "running", "performance": {}},
+                "sol_ctrl": {"status": "error", "performance": {}},
+                "ghost_ctrl": {"status": "running", "performance": {}},
+                "bad_ctrl": "not-a-dict",
+            },
+        }
+    }
+}
+
+
+class FakeControllers:
+    def __init__(self, configs, fail_targets=(), configs_error=False):
+        self.configs = [dict(c) for c in configs]
+        self.fail_targets = set(fail_targets)
+        self.configs_error = configs_error
+        self.calls = []
+
+    async def get_bot_controller_configs(self, bot_name):
+        if self.configs_error:
+            raise RuntimeError("bot not found")
+        return self.configs
+
+    async def update_bot_controller_config(self, bot_name, controller_name, config):
+        self.calls.append((controller_name, dict(config)))
+        if controller_name in self.fail_targets:
+            raise RuntimeError("404 not found")
+        for existing in self.configs:
+            if controller_name in (existing.get("id"), existing.get("_config_name")):
+                existing.update(config)
+                return {"message": "ok"}
+        raise RuntimeError("404 not found")
+
+
+class FakeOrchestration:
+    def __init__(self, data):
+        self.data = data
+
+    async def get_active_bots_status(self):
+        return self.data
+
+
+class FakeClient:
+    def __init__(self, controllers, status=None):
+        self.controllers = controllers
+        # deep copy: get_active_bots_status annotates the payload in place
+        self.bot_orchestration = FakeOrchestration(
+            copy.deepcopy(status if status is not None else STATUS)
+        )
+
+
+def _make_client(**kwargs):
+    return FakeClient(FakeControllers(CONFIGS, **kwargs))
+
+
+@pytest.mark.parametrize(
+    "controller_data,expected",
+    [
+        ({"status": "running", "kill_switch": True}, "stopped"),
+        ({"status": "running", "kill_switch": False}, "running"),
+        ({"status": "error", "kill_switch": False}, "error"),
+        # kill switch wins over an error report: a stopped controller is stopped
+        ({"status": "error", "kill_switch": True}, "stopped"),
+        # no config could be read — never claim "running"
+        ({"status": "running"}, "unknown"),
+    ],
+)
+def test_format_controller_state(controller_data, expected):
+    assert format_controller_state(controller_data) == expected
+
+
+def test_status_reports_stopped_for_killed_controller():
+    result = asyncio.run(bm.get_active_bots_status(_make_client()))
+    performance = result["active_bots"]["data"]["bot-1"]["performance"]
+
+    assert performance["eth_ctrl"]["kill_switch"] is True
+    assert performance["btc_ctrl"]["kill_switch"] is False
+    # a controller with no matching config stays unannotated rather than "running"
+    assert "kill_switch" not in performance["ghost_ctrl"]
+
+    table = result["bots_table"]
+    assert "| eth_ctrl | stopped |" in table
+    assert "| btc_ctrl | running |" in table
+    assert "| ghost_ctrl | unknown |" in table
+
+
+def test_status_survives_unreadable_controller_configs():
+    result = asyncio.run(bm.get_active_bots_status(_make_client(configs_error=True)))
+
+    # No kill switch is known, so every controller reads "unknown", not "running"
+    assert "| eth_ctrl | unknown |" in result["bots_table"]
+
+
+def test_stop_controllers_targets_the_config_file_name():
+    client = _make_client()
+
+    result = asyncio.run(
+        bm.manage_bot_execution(
+            client=client,
+            bot_name="bot-1",
+            action="stop_controllers",
+            controller_names=["sol_ctrl"],
+        )
+    )
+
+    # Addressed by _config_name, not by the controller id from the status payload
+    assert client.controllers.calls == [("sol_file", {"manual_kill_switch": True})]
+    assert result["succeeded"] == ["sol_ctrl"]
+    assert result["confirmed_kill_switch"] == {"sol_ctrl": True}
+
+
+def test_start_controllers_clears_the_kill_switch():
+    client = _make_client()
+
+    result = asyncio.run(
+        bm.manage_bot_execution(
+            client=client,
+            bot_name="bot-1",
+            action="start_controllers",
+            controller_names=["eth_ctrl"],
+        )
+    )
+
+    assert client.controllers.calls == [("eth_ctrl", {"manual_kill_switch": False})]
+    assert result["confirmed_kill_switch"] == {"eth_ctrl": False}
+
+
+def test_one_failing_controller_does_not_abort_the_others():
+    client = _make_client(fail_targets=["btc_ctrl"])
+
+    result = asyncio.run(
+        bm.manage_bot_execution(
+            client=client,
+            bot_name="bot-1",
+            action="stop_controllers",
+            controller_names=["eth_ctrl", "btc_ctrl"],
+        )
+    )
+
+    assert result["succeeded"] == ["eth_ctrl"]
+    assert "btc_ctrl" in result["failed"]
+    assert "Failed:" in result["message"]
+
+
+def test_stop_raises_when_no_controller_could_be_stopped():
+    client = _make_client()
+
+    with pytest.raises(ValueError, match="No controller could be stopped"):
+        asyncio.run(
+            bm.manage_bot_execution(
+                client=client,
+                bot_name="bot-1",
+                action="stop_controllers",
+                controller_names=["nope"],
+            )
+        )
+
+
+def test_stop_requires_controller_names():
+    with pytest.raises(ValueError, match="controller_names is required"):
+        asyncio.run(
+            bm.manage_bot_execution(
+                client=_make_client(),
+                bot_name="bot-1",
+                action="stop_controllers",
+                controller_names=[],
+            )
+        )
diff --git a/tests/test_gateway_wallet_default_optout.py b/tests/test_gateway_wallet_default_optout.py
new file mode 100644
index 00000000..cdad53c9
--- /dev/null
+++ b/tests/test_gateway_wallet_default_optout.py
@@ -0,0 +1,149 @@
+"""Importing a wallet with "set as default" unticked must leave the default alone.
+
+Gateway's ``add-wallet`` promotes every newly imported key to the chain default,
+and the hummingbot client method exposes no flag to turn that off. Unticking the
+box only skipped Condor's *explicit* ``set-default`` call, so the implicit one
+still switched the user's default wallet under them. The route now captures the
+existing default before the import and restores it afterwards.
+"""
+
+import asyncio
+
+import pytest
+
+import condor.web.routes.settings as settings_module
+from condor.web.models import GatewayWalletAddRequest, WebUser
+from config_manager import ServerPermission
+
+_USER = WebUser(id=1, role="admin")
+
+OLD = "0xold"
+NEW = "0xnew"
+
+
+class FakeAccounts:
+    def __init__(self, wallets):
+        self._wallets = wallets
+        self.set_default_calls = []
+
+    async def list_gateway_wallets(self):
+        return self._wallets
+
+    async def add_gateway_wallet(self, chain, private_key):
+        # Gateway's own behaviour: the new key becomes the chain default.
+        for group in self._wallets:
+            if group["chain"] == chain:
+                group["walletAddresses"].append(NEW)
+                group["default_address"] = NEW
+                break
+        else:
+            self._wallets.append(
+                {"chain": chain, "walletAddresses": [NEW], "default_address": NEW}
+            )
+        return {"address": NEW}
+
+    async def set_default_gateway_wallet(self, chain, address):
+        self.set_default_calls.append((chain, address))
+        for group in self._wallets:
+            if group["chain"] == chain:
+                group["default_address"] = address
+        return {"default": True}
+
+
+class FakeClient:
+    def __init__(self, wallets):
+        self.accounts = FakeAccounts(wallets)
+
+
+class FakeCM:
+    def __init__(self, client):
+        self._client = client
+
+    def has_server_access(self, *_a, **_kw):
+        return True
+
+    def get_server_permission(self, *_a, **_kw):
+        # SEC-166 made wallet import owner-only; this fixture is the owner.
+        return ServerPermission.OWNER
+
+    def is_admin(self, _user_id):
+        return False
+
+    async def get_client(self, _name):
+        return self._client
+
+
+@pytest.fixture
+def bind(monkeypatch):
+    def _bind(wallets):
+        client = FakeClient(wallets)
+        monkeypatch.setattr(
+            settings_module, "get_config_manager", lambda: FakeCM(client)
+        )
+        return client
+
+    return _bind
+
+
+def _add(set_default):
+    return asyncio.run(
+        settings_module.gateway_wallet_add(
+            req=GatewayWalletAddRequest(
+                chain="ethereum", private_key="0x" + "1" * 64, set_default=set_default
+            ),
+            server="srv",
+            user=_USER,
+        )
+    )
+
+
+def test_untick_restores_the_previous_default(bind):
+    client = bind(
+        [{"chain": "ethereum", "walletAddresses": [OLD], "default_address": OLD}]
+    )
+
+    res = _add(set_default=False)
+
+    assert res["address"] == NEW
+    assert res["is_default"] is False
+    assert client.accounts.set_default_calls == [("ethereum", OLD)]
+    group = client.accounts._wallets[0]
+    assert group["default_address"] == OLD
+    assert NEW in group["walletAddresses"]
+
+
+def test_tick_makes_the_new_wallet_default(bind):
+    client = bind(
+        [{"chain": "ethereum", "walletAddresses": [OLD], "default_address": OLD}]
+    )
+
+    res = _add(set_default=True)
+
+    assert res["is_default"] is True
+    assert client.accounts.set_default_calls == [("ethereum", NEW)]
+    assert client.accounts._wallets[0]["default_address"] == NEW
+
+
+def test_first_wallet_on_a_chain_stays_default_even_when_unticked(bind):
+    """With no previous default there is nothing to restore — Gateway needs one."""
+    client = bind([])
+
+    res = _add(set_default=False)
+
+    assert res["is_default"] is True
+    assert client.accounts.set_default_calls == []
+    assert client.accounts._wallets[0]["default_address"] == NEW
+
+
+def test_other_chains_defaults_are_not_touched(bind):
+    client = bind(
+        [
+            {"chain": "solana", "walletAddresses": ["Sol1"], "default_address": "Sol1"},
+            {"chain": "ethereum", "walletAddresses": [OLD], "default_address": OLD},
+        ]
+    )
+
+    _add(set_default=False)
+
+    assert client.accounts.set_default_calls == [("ethereum", OLD)]
+    assert client.accounts._wallets[0]["default_address"] == "Sol1"
diff --git a/tests/test_issue_template_contract.py b/tests/test_issue_template_contract.py
new file mode 100644
index 00000000..21d21dc2
--- /dev/null
+++ b/tests/test_issue_template_contract.py
@@ -0,0 +1,80 @@
+"""The dashboard's issue reporter prefills GitHub's issue forms by field id.
+
+GitHub silently ignores a query parameter that names no field, so a renamed id
+in `.github/ISSUE_TEMPLATE/*.yml` does not break the link — it just drops the
+prefill, and nobody notices until a report arrives with empty boxes. The same
+goes for the `area` dropdown, which is matched by its label. These tests hold
+the two files together.
+"""
+
+import re
+from pathlib import Path
+
+import pytest
+import yaml
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+TEMPLATES = REPO_ROOT / ".github" / "ISSUE_TEMPLATE"
+ISSUE_TS = REPO_ROOT / "frontend" / "src" / "lib" / "github-issue.ts"
+CONTEXT_TS = REPO_ROOT / "frontend" / "src" / "lib" / "page-context.ts"
+
+
+def _template(name: str) -> dict:
+    return yaml.safe_load((TEMPLATES / name).read_text())
+
+
+def _field_ids(template: dict) -> set[str]:
+    return {b["id"] for b in template["body"] if "id" in b}
+
+
+def _ts_field_map(kind: str) -> dict[str, str]:
+    """The `FIELDS[kind]` literal from github-issue.ts, as a dict."""
+    source = ISSUE_TS.read_text()
+    block = re.search(rf"\b{kind}:\s*\{{(.*?)\}},", source, re.S)
+    assert block, f"no FIELDS entry for {kind!r} in github-issue.ts"
+    return dict(re.findall(r'(\w+):\s*"([^"]+)"', block.group(1)))
+
+
+@pytest.mark.parametrize("kind", ["bug", "feature"])
+def test_prefilled_ids_exist_in_the_template(kind):
+    """Every id the frontend fills is a field the template actually declares."""
+    mapping = _ts_field_map(kind)
+    template = _template(mapping["template"])
+    declared = _field_ids(template)
+
+    for slot, field_id in mapping.items():
+        if slot == "template":
+            continue
+        assert field_id in declared, (
+            f"github-issue.ts prefills {field_id!r} for a {kind} report, but "
+            f"{mapping['template']} declares {sorted(declared)}"
+        )
+
+
+@pytest.mark.parametrize("name", ["bug_report.yml", "feature_request.yml"])
+def test_area_options_match_the_frontend(name):
+    """The dropdown is matched by label — both files must offer the same list."""
+    template = _template(name)
+    area = next(b for b in template["body"] if b.get("id") == "area")
+    options = area["attributes"]["options"]
+
+    declared = re.search(
+        r"export const AREAS = \[(.*?)\] as const;", CONTEXT_TS.read_text(), re.S
+    )
+    assert declared, "AREAS is no longer a literal array in page-context.ts"
+    frontend_areas = re.findall(r'"([^"]+)"', declared.group(1))
+
+    assert options == frontend_areas
+
+
+def test_templates_are_valid_issue_forms():
+    """Name, description and a required body — what GitHub needs to render them."""
+    for path in sorted(TEMPLATES.glob("*.yml")):
+        data = yaml.safe_load(path.read_text())
+        if path.name == "config.yml":
+            assert "contact_links" in data
+            continue
+        assert data["name"] and data["description"]
+        assert any(
+            b.get("validations", {}).get("required") for b in data["body"]
+        ), f"{path.name} asks nothing of the reporter"
diff --git a/tests/test_session_bot_visibility.py b/tests/test_session_bot_visibility.py
new file mode 100644
index 00000000..34029c68
--- /dev/null
+++ b/tests/test_session_bot_visibility.py
@@ -0,0 +1,483 @@
+"""What a bot-mode session shows about itself in the dashboard.
+
+A session that trades through bots earns nothing under its own ``agent_id``: the
+bot's controllers tag their executors with their own config ids, and those rows
+live inside the bot instance's own database — they never reach the executor table
+Condor searches. The only executor-like rows it can reconstruct are the positions
+open *right now*, so a session that opened and closed three positions and is
+currently flat produced zero rows and rendered as a session that never traded.
+
+The aggregate always knew better. These tests pin the facts it knows — which
+instances ran, which controllers, how each position closed, and whether the fee
+figure means anything — and that they survive the trip to the web wire, where
+they used to be dropped by a response model that had no fields for them.
+"""
+
+import asyncio
+import json
+from pathlib import Path
+
+import pytest
+import yaml
+
+from condor.agents.performance import fetch_agent_performance
+from condor.fetchers.bot_performance import (
+    _aggregate_by_bot,
+    clear_archived_cache,
+    clear_snapshot_cache,
+    resolve_bots,
+)
+from condor.web.routes import agents as agents_route
+from condor.web.routes.agents import AgentPerformanceModel
+
+
+@pytest.fixture(autouse=True)
+def _no_cache_bleed():
+    clear_snapshot_cache()
+    clear_archived_cache()
+    yield
+    clear_snapshot_cache()
+    clear_archived_cache()
+
+
+# ── Payload builders ──
+
+
+def _snap(bot_name, controller_id, *, realized=0.0, volume=0.0, closes=None, ts=""):
+    return {
+        "bot_name": bot_name,
+        "controller_id": controller_id,
+        "timestamp": ts,
+        "status": "running",
+        "performance": {
+            "realized_pnl_quote": realized,
+            "unrealized_pnl_quote": 0.0,
+            "volume_traded": volume,
+            "positions_summary": [],
+            "close_type_counts": closes or {},
+        },
+    }
+
+
+class _FakeClient:
+    """Snapshots, archived-instance listing and cumulative history in one object."""
+
+    def __init__(self, snapshots, history=None, archived=()):
+        self._snapshots = snapshots
+        self._history = history or {}
+        self._archived = list(archived)
+        self.bot_orchestration = self
+        self.archived_bots = self
+
+    async def get_latest_controller_performance(self, bot_name=None):
+        return {"data": self._snapshots}
+
+    async def get_controller_performance_history(self, bot_name, interval, limit):
+        return {"data": self._history.get(bot_name, [])}
+
+    async def list_databases(self):
+        return [f"/data/archived/{name}.sqlite" for name in self._archived]
+
+
+# ── The aggregate carries the close-type breakdown ──
+
+
+def test_close_type_counts_ride_along_per_controller_and_per_bot():
+    # trade_count counts only round-trip closes, so a directional controller
+    # stopped by its own risk rule reports zero trades on real volume. The raw
+    # breakdown is what makes that explicable instead of merely wrong.
+    agg = _aggregate_by_bot(
+        [
+            _snap(
+                "b-1",
+                "btc",
+                realized=-0.3,
+                volume=386.0,
+                closes={"CloseType.EARLY_STOP": 1},
+            ),
+            _snap(
+                "b-1",
+                "eth",
+                realized=-0.7,
+                volume=399.0,
+                closes={"CloseType.EARLY_STOP": 1},
+            ),
+            _snap("b-1", "sol", realized=0.0, volume=0.0),
+        ]
+    )
+    bot = agg["b-1"]
+    assert bot["close_type_counts"] == {"CloseType.EARLY_STOP": 2}
+    assert bot["closed_trades"] == 0  # strict round-trip filter, unchanged
+    by_id = {c["controller_id"]: c for c in bot["controllers"]}
+    assert by_id["btc"]["close_type_counts"] == {"CloseType.EARLY_STOP": 1}
+    assert by_id["sol"]["close_type_counts"] == {}
+
+
+def test_every_controller_names_the_deploy_it_ran_under():
+    # Instance aggregates are concatenated when a base is redeployed, so without
+    # this the controllers of three deploys read as one undifferentiated set.
+    agg = _aggregate_by_bot(
+        [
+            _snap(
+                "b-20260806-213931",
+                "btc",
+                realized=-0.3,
+                ts="2026-08-06T21:47:00+00:00",
+            ),
+            _snap("b-20260807-045821", "sol", ts="2026-08-07T09:57:00+00:00"),
+        ]
+    )
+    resolved = resolve_bots(agg, ["b"])["b"]
+    assert {c["bot_name"] for c in resolved["controllers"]} == {
+        "b-20260806-213931",
+        "b-20260807-045821",
+    }
+
+
+def test_redeploys_pool_their_close_types_under_the_base():
+    agg = _aggregate_by_bot(
+        [
+            _snap(
+                "b-1",
+                "btc",
+                closes={"CloseType.EARLY_STOP": 1},
+                ts="2026-08-06T00:00:00+00:00",
+            ),
+            _snap(
+                "b-2",
+                "btc",
+                closes={"CloseType.EARLY_STOP": 1, "CloseType.TAKE_PROFIT": 2},
+                ts="2026-08-07T00:00:00+00:00",
+            ),
+        ]
+    )
+    resolved = resolve_bots(agg, ["b"])["b"]
+    assert resolved["close_type_counts"] == {
+        "CloseType.EARLY_STOP": 2,
+        "CloseType.TAKE_PROFIT": 2,
+    }
+
+
+# ── What the session-level aggregate reports ──
+
+
+def _perf_for_three_deploys():
+    """Two stopped deploys that traded, one live deploy that is flat."""
+    live, old1, old2 = "b-20260807-045821", "b-20260806-213931", "b-20260807-022130"
+    client = _FakeClient(
+        snapshots=[
+            _snap(
+                old1,
+                "btc",
+                realized=-0.3,
+                volume=386.0,
+                closes={"CloseType.EARLY_STOP": 1},
+                ts="2026-08-06T21:47:00+00:00",
+            ),
+            _snap(
+                old2,
+                "btc",
+                realized=-0.46,
+                volume=386.0,
+                closes={"CloseType.EARLY_STOP": 1},
+                ts="2026-08-07T04:00:00+00:00",
+            ),
+            _snap(live, "sol", ts="2026-08-07T09:57:00+00:00"),
+        ],
+        archived=[old1, old2],
+    )
+    return client, asyncio.run(
+        fetch_agent_performance(client, "agent_1", bot_names=["b"])
+    )
+
+
+def test_stopped_deploys_are_named_even_though_only_the_live_one_resolves():
+    _client, perf = _perf_for_three_deploys()
+    # `bot_names` is what is running now — the label the old code showed alone,
+    # hiding the two deploys whose losses it was reporting.
+    assert perf.bot_names == ["b-20260807-045821"]
+    assert perf.bot_instances == [
+        "b-20260806-213931",
+        "b-20260807-022130",
+        "b-20260807-045821",
+    ]
+
+
+def test_a_deploy_known_only_from_the_archive_is_still_listed():
+    # Once the snapshot endpoint drops a stopped instance, the archived-database
+    # listing is the only evidence it ran. It has no controller rows left, which
+    # the session view renders as "no performance snapshot retained" — a deploy
+    # with unknown detail, not a deploy that never happened.
+    client = _FakeClient(
+        snapshots=[_snap("b-20260807-045821", "sol", ts="2026-08-07T09:57:00+00:00")],
+        archived=["b-20260101-000000"],
+    )
+    perf = asyncio.run(fetch_agent_performance(client, "agent_1", bot_names=["b"]))
+    assert perf.bot_instances == ["b-20260101-000000", "b-20260807-045821"]
+    assert {c["bot_name"] for c in perf.controllers} == {"b-20260807-045821"}
+
+
+def test_flat_bot_reports_no_executor_rows_but_a_full_controller_breakdown():
+    _client, perf = _perf_for_three_deploys()
+    # This is the exact shape that used to render as "No executors for this
+    # session": nothing open, everything closed, and real money moved.
+    assert perf.executors == []
+    assert perf.volume == 772.0
+    assert round(perf.realized_pnl, 2) == -0.76
+    assert len(perf.controllers) == 3
+    assert perf.close_type_counts == {"CloseType.EARLY_STOP": 2}
+
+
+def test_volume_without_a_fee_column_reads_as_unknown_not_free():
+    _client, perf = _perf_for_three_deploys()
+    assert perf.fees == 0.0
+    assert perf.fees_known is False
+
+
+def test_a_bot_that_reports_fees_keeps_them_known():
+    client = _FakeClient(
+        snapshots=[
+            {
+                "bot_name": "b-1",
+                "controller_id": "btc",
+                "timestamp": "2026-08-07T00:00:00+00:00",
+                "status": "running",
+                "performance": {
+                    "realized_pnl_quote": 5.0,
+                    "unrealized_pnl_quote": 0.0,
+                    "volume_traded": 100.0,
+                    "positions_summary": [{"cum_fees_quote": 0.42}],
+                },
+            }
+        ],
+    )
+    perf = asyncio.run(fetch_agent_performance(client, "agent_1", bot_names=["b"]))
+    assert perf.fees == 0.42
+    assert perf.fees_known is True
+
+
+def test_executor_mode_sessions_are_untouched():
+    # A session with its own agent_id-tagged executors owns no bot: none of the
+    # bot-mode fields should acquire content, and fees stay known.
+    class _NoBots:
+        class executors:
+            @staticmethod
+            async def search_executors(controller_ids, limit, cursor=None):
+                return {"executors": []}
+
+    perf = asyncio.run(fetch_agent_performance(_NoBots(), "agent_1"))
+    assert perf.bot_instances == []
+    assert perf.controllers == []
+    assert perf.close_type_counts == {}
+    assert perf.fees_known is True
+
+
+# ── The web wire ──
+
+
+def test_response_model_carries_the_bot_mode_fields():
+    # The regression this whole file exists for: the aggregate knew all of this
+    # and the response model had nowhere to put it, so the UI could not have
+    # rendered it however it was written.
+    _client, perf = _perf_for_three_deploys()
+    payload = AgentPerformanceModel(
+        agent_id="agent_1",
+        session_num=1,
+        bot_names=perf.bot_names,
+        bot_instances=perf.bot_instances,
+        unresolved_bases=perf.unresolved_bases,
+        controllers=perf.controllers,
+        close_type_counts=perf.close_type_counts,
+        fees_known=perf.fees_known,
+    ).model_dump()
+    assert payload["bot_instances"] == perf.bot_instances
+    assert payload["close_type_counts"] == {"CloseType.EARLY_STOP": 2}
+    assert payload["fees_known"] is False
+    assert {c["bot_name"] for c in payload["controllers"]} == {
+        "b-20260806-213931",
+        "b-20260807-022130",
+        "b-20260807-045821",
+    }
+
+
+def test_rollup_leaves_the_per_session_fields_empty_rather_than_ambiguous():
+    # The strategy rollup distributes a bot's history across sessions instead of
+    # resolving instances per session, so it cannot fill these honestly. Empty is
+    # the contract; filling `bot_names` with base names there would have made one
+    # field mean two different things on two routes.
+    assert AgentPerformanceModel(agent_id="a", session_num=1).bot_names == []
+    assert AgentPerformanceModel(agent_id="a", session_num=1).fees_known is True
+
+
+# ── Session artifacts the reviewer can now reach ──
+
+
+class _User:
+    id = 1
+    role = "admin"
+
+
+def _strategy_on_disk(tmp_path: Path):
+    """Minimal agent/strategy tree with one session, wired into the stores."""
+    sdir = tmp_path / "ag" / "strategies" / "st"
+    (sdir / "sessions" / "session_1").mkdir(parents=True)
+    (sdir / "strategy.md").write_text("# playbook\n")
+    (sdir / "sessions" / "session_1" / "config.yml").write_text(yaml.safe_dump({}))
+    return sdir
+
+
+def test_canvas_endpoint_serves_sections_and_revisions(tmp_path, monkeypatch):
+    from condor.agents import canvas as canvas_mod
+
+    sdir = _strategy_on_disk(tmp_path)
+    session_dir = sdir / "sessions" / "session_1"
+    canvas_mod.write_section(
+        session_dir, "thesis", "Trend following on 1h EMAs.", tick=3
+    )
+
+    monkeypatch.setattr(
+        agents_route,
+        "_get_strategy",
+        lambda slug, sslug: type("S", (), {"dir": sdir})(),
+    )
+    out = asyncio.run(agents_route.get_session_canvas("ag", "st", 1, user=_User()))
+    assert out["sections"]["thesis"].startswith("Trend following")
+    assert out["last_revised_tick"] == 3
+    assert out["revisions"][0]["tick"] == 3
+    assert out["section_order"][0] == "thesis"
+
+
+def test_report_endpoint_returns_null_for_a_session_that_kept_none(
+    tmp_path, monkeypatch
+):
+    # A missing report is a normal state — a loop that predates the live report,
+    # or one that never ticked — so callers must not have to tell it from a 404.
+    sdir = _strategy_on_disk(tmp_path)
+    monkeypatch.setattr(
+        agents_route,
+        "_get_strategy",
+        lambda slug, sslug: type("S", (), {"dir": sdir})(),
+    )
+    monkeypatch.setattr(
+        "condor.reports.list_reports", lambda **kw: ([], 0), raising=False
+    )
+    out = asyncio.run(agents_route.get_session_report("ag", "st", 1, user=_User()))
+    assert out == {"report": None}
+
+
+def test_report_endpoint_matches_the_session_it_was_written_for(tmp_path, monkeypatch):
+    sdir = _strategy_on_disk(tmp_path)
+    monkeypatch.setattr(
+        agents_route,
+        "_get_strategy",
+        lambda slug, sslug: type("S", (), {"dir": sdir})(),
+    )
+    rows = [
+        {
+            "id": "aaa",
+            "title": "ag · st · session 1",
+            "filename": "f1.html",
+            "created_at": "2026-08-06T21:39:57+00:00",
+            "source_type": "routine",
+            "source_name": "ag.st/session_1",
+            "tags": [],
+        },
+        {
+            "id": "bbb",
+            "title": "ag · st · session 2",
+            "filename": "f2.html",
+            "created_at": "2026-08-07T21:39:57+00:00",
+            "source_type": "routine",
+            "source_name": "ag.st/session_2",
+            "tags": [],
+        },
+    ]
+    import condor.reports as reports_mod
+
+    monkeypatch.setattr(reports_mod, "list_reports", lambda **kw: (rows, len(rows)))
+    out = asyncio.run(agents_route.get_session_report("ag", "st", 1, user=_User()))
+    assert out["report"]["id"] == "aaa"
+
+
+def test_the_live_report_breaks_the_kpis_down_by_deploy_and_controller():
+    # "Total PnL -$1.46" over three redeploys says nothing about which leg lost
+    # it, and the report showed exactly that and nothing more.
+    from condor.agents.session_report import SessionReport
+
+    class _B:
+        def __init__(self):
+            self.rows = None
+
+        def section(self, title, body=""):
+            self.title = title
+
+        def table(self, rows):
+            self.rows = rows
+
+    b = _B()
+    SessionReport._controllers(
+        b,
+        {
+            "bot_names": ["b-2"],
+            "controllers": [
+                {
+                    "bot_name": "b-1",
+                    "controller_id": "btc",
+                    "realized_pnl_quote": -0.31,
+                    "volume_traded": 386.0,
+                    "close_type_counts": {"CloseType.EARLY_STOP": 1},
+                    # The backend reports this for stopped instances too, which is
+                    # why the row's State must not come from it.
+                    "status": "running",
+                },
+                {"bot_name": "b-2", "controller_id": "sol"},
+            ],
+        },
+    )
+    assert [r["State"] for r in b.rows] == ["stopped", "running"]
+    assert b.rows[0]["Closes"] == "early stop ×1"
+    assert b.rows[1]["Closes"] == "—"
+
+
+def test_the_report_skips_the_block_for_an_executor_only_session():
+    from condor.agents.session_report import SessionReport
+
+    class _B:
+        called = False
+
+        def section(self, *a, **k):
+            self.called = True
+
+        def table(self, *a, **k):
+            self.called = True
+
+    b = _B()
+    SessionReport._controllers(b, {"bot_names": [], "controllers": []})
+    assert b.called is False
+
+
+def test_session_ledger_survives_the_json_round_trip(tmp_path):
+    # The ledger is what tells the detail route which bases a session owned; a
+    # session whose ledger cannot be read falls back to reporting nothing.
+    from condor.agents.ownership import read_owned
+
+    sd = tmp_path / "session_1"
+    sd.mkdir()
+    (sd / "owned_bots.json").write_text(
+        json.dumps(
+            {
+                "namespace": "ag-st",
+                "bots": {
+                    "b": {
+                        "base": "b",
+                        "origin": "deployed",
+                        "since": 1.0,
+                        "last_seen": 2.0,
+                    }
+                },
+            }
+        )
+    )
+    owned = read_owned(sd)
+    assert [o.base for o in owned] == ["b"]
+    assert owned[0].until == 0.0
diff --git a/tests/test_update_restart_flow.py b/tests/test_update_restart_flow.py
new file mode 100644
index 00000000..e371a7e7
--- /dev/null
+++ b/tests/test_update_restart_flow.py
@@ -0,0 +1,208 @@
+"""The /update pipeline: rebuild what the pull invalidated, restart cleanly.
+
+Two things used to be missing from an in-place update. The dashboard bundle was
+never rebuilt — ``make run`` builds it before starting, but /update pulls and
+re-execs, so pulled frontend commits kept serving the previous ``frontend/dist``.
+And the restart was a bare ``os.execv`` from inside the handler, which dropped
+the process image before ``teardown()`` could flush persistence or reap ACP/MCP
+subprocesses. These tests pin both: the build runs exactly when it is needed,
+and a restart request goes through the normal shutdown path.
+"""
+
+import asyncio
+import os
+import signal
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+import handlers.admin.update as update_handler
+from utils import updater
+
+
+@pytest.fixture(autouse=True)
+def _reset_restart_flag():
+    """Keep the module-level restart flag from leaking between tests."""
+    updater._restart_pending = False
+    yield
+    updater._restart_pending = False
+
+
+class FakeQuery:
+    """Collects what the admin would have seen, in order."""
+
+    def __init__(self):
+        self.messages = []
+
+    async def edit_message_text(self, text, parse_mode=None, reply_markup=None):
+        self.messages.append(text)
+
+
+def _stub_pipeline(**overrides):
+    """Patch every step of the Condor update; each override replaces one step."""
+    steps = dict(
+        get_local_commit_full=AsyncMock(side_effect=["old_sha", "new_sha"]),
+        pull_updates=AsyncMock(return_value=(True, "3 files changed")),
+        install_dependencies=AsyncMock(return_value=(True, "Resolved 120 packages")),
+        frontend_needs_build=AsyncMock(return_value=True),
+        build_frontend=AsyncMock(return_value=(True, "built in 297ms")),
+    )
+    steps.update(overrides)
+    return patch.multiple("utils.updater", **steps), steps
+
+
+# ---------------------------------------------------------------------------
+# What needs rebuilding
+# ---------------------------------------------------------------------------
+
+
+def _fake_fs(has_frontend=True, has_bundle=True):
+    """Pretend frontend/ and frontend/dist/index.html do (not) exist."""
+    real_isdir, real_isfile = os.path.isdir, os.path.isfile
+
+    def isdir(path):
+        if path == updater.FRONTEND_DIR:
+            return has_frontend
+        return real_isdir(path)
+
+    def isfile(path):
+        if path.endswith(os.path.join("dist", "index.html")):
+            return has_bundle
+        return real_isfile(path)
+
+    return patch.multiple("os.path", isdir=isdir, isfile=isfile)
+
+
+def test_frontend_rebuilds_when_the_pull_touched_it():
+    with (
+        _fake_fs(),
+        patch.object(
+            updater, "_run_git", AsyncMock(return_value=(0, "frontend/src/App.tsx"))
+        ),
+    ):
+        assert asyncio.run(updater.frontend_needs_build("old_sha", "new_sha")) is True
+
+
+def test_frontend_skipped_when_the_pull_left_it_alone():
+    with _fake_fs(), patch.object(updater, "_run_git", AsyncMock(return_value=(0, ""))):
+        assert asyncio.run(updater.frontend_needs_build("old_sha", "new_sha")) is False
+
+
+def test_frontend_builds_when_the_bundle_is_missing_entirely():
+    """A fresh clone has no dist/, so build it even though nothing changed."""
+    with (
+        _fake_fs(has_bundle=False),
+        patch.object(updater, "_run_git", AsyncMock(return_value=(0, ""))) as git,
+    ):
+        assert asyncio.run(updater.frontend_needs_build("same", "same")) is True
+        git.assert_not_awaited()  # short-circuits before diffing
+
+
+def test_no_frontend_directory_means_nothing_to_build():
+    with _fake_fs(has_frontend=False):
+        assert asyncio.run(updater.frontend_needs_build("old_sha", "new_sha")) is False
+
+
+def test_unresolvable_diff_assumes_changed():
+    """Shallow clone or rewritten history: redo the work rather than skip it."""
+    with patch.object(updater, "_run_git", AsyncMock(return_value=(128, "bad object"))):
+        assert asyncio.run(updater.paths_changed("old", "new", "frontend")) is True
+
+
+def test_identical_commits_change_nothing():
+    with patch.object(updater, "_run_git", AsyncMock()) as git:
+        assert asyncio.run(updater.paths_changed("same", "same", "frontend")) is False
+        git.assert_not_awaited()
+
+
+# ---------------------------------------------------------------------------
+# The update pipeline
+# ---------------------------------------------------------------------------
+
+
+def test_update_pulls_syncs_builds_then_reports_ready():
+    ctx, steps = _stub_pipeline()
+    query = FakeQuery()
+    with ctx:
+        assert asyncio.run(update_handler._update_condor(query)) is True
+
+    steps["pull_updates"].assert_awaited_once()
+    steps["install_dependencies"].assert_awaited_once()
+    steps["build_frontend"].assert_awaited_once()
+    # The diff is taken across the pull, not against an arbitrary commit.
+    steps["frontend_needs_build"].assert_awaited_once_with("old_sha", "new_sha")
+
+
+def test_update_does_not_build_when_the_frontend_is_untouched():
+    ctx, steps = _stub_pipeline(frontend_needs_build=AsyncMock(return_value=False))
+    with ctx:
+        assert asyncio.run(update_handler._update_condor(FakeQuery())) is True
+    steps["build_frontend"].assert_not_awaited()
+
+
+def test_failed_pull_stops_before_touching_dependencies():
+    ctx, steps = _stub_pipeline(
+        pull_updates=AsyncMock(return_value=(False, "uncommitted changes"))
+    )
+    query = FakeQuery()
+    with ctx:
+        assert asyncio.run(update_handler._update_condor(query)) is False
+
+    steps["install_dependencies"].assert_not_awaited()
+    steps["build_frontend"].assert_not_awaited()
+    assert "uncommitted changes" in query.messages[-1]
+
+
+def test_failed_build_blocks_the_restart():
+    """Restarting here would bring the dashboard back on the previous bundle."""
+    ctx, steps = _stub_pipeline(
+        build_frontend=AsyncMock(return_value=(False, "TS2304: Cannot find name"))
+    )
+    query = FakeQuery()
+    with ctx:
+        assert asyncio.run(update_handler._update_condor(query)) is False
+
+    assert "TS2304" in query.messages[-1]
+
+
+def test_command_output_is_trimmed_for_telegram():
+    """Build logs run to thousands of lines; only the tail is worth sending."""
+    trimmed = update_handler._tail("\n".join(str(i) for i in range(500)))
+    assert trimmed.startswith("...")
+    assert trimmed.endswith("499")
+    assert len(trimmed.split("\n")) <= 16
+
+
+# ---------------------------------------------------------------------------
+# Restart
+# ---------------------------------------------------------------------------
+
+
+def test_restart_request_signals_shutdown_instead_of_exec():
+    """Exec'ing from the handler would skip teardown: flush, reap, final state."""
+    with patch.object(os, "kill") as kill, patch.object(os, "execv") as execv:
+        updater.request_restart()
+
+    assert updater.restart_pending() is True
+    kill.assert_called_once_with(os.getpid(), signal.SIGTERM)
+    execv.assert_not_called()
+
+
+def test_nothing_restarts_unless_asked():
+    assert updater.restart_pending() is False
+
+
+def test_exec_restart_replaces_the_process_in_place():
+    """In-place exec is what keeps Condor in the tmux pane it was started in."""
+    with patch.object(os, "execv") as execv, patch.object(os, "chdir") as chdir:
+        updater.exec_restart()
+
+    chdir.assert_called_once_with(updater.CONDOR_DIR)
+    python, argv = execv.call_args[0]
+    assert argv[0] == python  # same interpreter, same argv — not a new command
+
+
+def test_hung_step_is_killed_rather_than_waited_on():
+    rc, output = asyncio.run(updater._run_cmd("bash", "-c", "sleep 30", timeout=0.5))
+    assert rc == 124
+    assert "Timed out" in output
diff --git a/tests/test_web_meta_env.py b/tests/test_web_meta_env.py
new file mode 100644
index 00000000..b6c48dbf
--- /dev/null
+++ b/tests/test_web_meta_env.py
@@ -0,0 +1,66 @@
+"""Tests for the build-identity endpoint behind the dashboard's issue reporter.
+
+The "Report an issue" dialog stamps every report with the commit it came from.
+That is only useful if the endpoint answers with real fields, and only safe if
+it answers nobody who is not logged in.
+"""
+
+import pytest
+from starlette.testclient import TestClient
+
+from condor.web.app import create_app
+from condor.web.auth import get_current_user
+from condor.web.models import WebUser
+
+
+@pytest.fixture()
+def app():
+    return create_app()
+
+
+@pytest.fixture()
+def client(app):
+    with TestClient(app) as test_client:
+        yield test_client
+
+
+def test_env_requires_authentication(client):
+    """No token, no answer — an install's commit is not for anonymous callers."""
+    res = client.get("/api/v1/meta/env")
+    assert res.status_code in (401, 403)
+
+
+def test_env_returns_build_identity(app):
+    """The fields the diagnostics block renders are all present and typed."""
+    app.dependency_overrides[get_current_user] = lambda: WebUser(
+        id=1, username="u", first_name="f", role="user"
+    )
+    try:
+        with TestClient(app) as client:
+            res = client.get("/api/v1/meta/env")
+    finally:
+        app.dependency_overrides.clear()
+
+    assert res.status_code == 200
+    body = res.json()
+    assert set(body) == {"version", "branch", "python", "os", "arch", "in_docker"}
+    assert isinstance(body["in_docker"], bool)
+    # An install deployed from a tarball has no git metadata; the context layer
+    # reports "unknown" rather than failing, and either is a valid answer.
+    assert body["version"]
+    assert body["python"].startswith("3.")
+
+
+def test_env_leaks_no_configuration(app):
+    """Only version and platform. Never keys, hosts, users, or server names."""
+    app.dependency_overrides[get_current_user] = lambda: WebUser(
+        id=1, username="u", first_name="f", role="user"
+    )
+    try:
+        with TestClient(app) as client:
+            body = client.get("/api/v1/meta/env").json()
+    finally:
+        app.dependency_overrides.clear()
+
+    for banned in ("llm_providers", "user_count", "server_count", "has_gateway"):
+        assert banned not in body

From 6bb808377e5ed10072b257af42920ca5d04c510d Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Mon, 17 Aug 2026 14:10:27 +0300
Subject: [PATCH 105/116] (chore) CI runs lint, imports, tests and the frontend
 build

Black and isort are already clean tree-wide, so --check can gate main
rather than merely report. Adds an import smoke test for the core
modules and the frontend's own lint and build.
---
 .github/workflows/ci.yml | 101 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 101 insertions(+)
 create mode 100644 .github/workflows/ci.yml

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 00000000..efe42daa
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,101 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  backend-lint:
+    name: Backend Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Check formatting with black
+        run: uv run black --check .
+
+      - name: Check import sorting with isort
+        run: uv run isort --check .
+
+  backend-import-check:
+    name: Backend Import Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Verify main modules import without errors
+        run: |
+          uv run python -c "
+          import config_manager
+          import handlers
+          import utils
+          print('All core modules imported successfully')
+          "
+
+  backend-tests:
+    name: Backend Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Run tests
+        run: uv run pytest --tb=short -q
+
+  frontend-build:
+    name: Frontend Build & Lint
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: frontend
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Build
+        run: npm run build

From 411b115e591db692fbb4b4ed47accfcfde33efab Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Mon, 17 Aug 2026 14:10:43 +0300
Subject: [PATCH 106/116] (feat) three new agents: Backpack MM, Brigado, Orca
 LP Expert
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Backpack MM covers the perp MM rewards programme — volume thresholds,
market selection and rotation, deploy and ongoing operations. Brigado
researches the BRL market making operation: USDT-BRL spreads, BTC/fiat
volume, bot performance. Orca LP Expert judges concentrated liquidity on
tokenized real-world assets, from pool attractiveness through range
selection to hold-or-exit.

Definitions and routines only; the runtime stores, journals and
delegation records stay untracked as usual.
---
 agents/backpack_mm/AGENT.md                   |   74 +
 .../backpack_binance_funding_comparison.py    |  257 +++
 .../routines/backpack_funding_compare.py      |    0
 .../routines/backpack_mm_volume_analysis.py   |    0
 .../routines/backpack_volume_scan.py          |  257 +++
 .../skills/backpack_perp_mm_deploy/SKILL.md   |   94 +
 .../config_backpack_aggressive.md             |   94 +
 .../strategies/backpack_perp_mm/strategy.md   |   69 +
 agents/brigado/AGENT.md                       |   16 +
 agents/brigado/routines/bot_report.py         | 1752 +++++++++++++++++
 agents/brigado/routines/brl_dashboard.py      |  573 ++++++
 agents/brigado/routines/btc_brl_arbitrage.py  |  608 ++++++
 agents/brigado/routines/config_analyzer.py    |  772 ++++++++
 agents/brigado/routines/spot_markets.py       |  458 +++++
 .../brigado/routines/toxic_flow_detector.py   |    0
 agents/brigado/strategies/brl_mm/strategy.md  |   32 +
 agents/orca_lp_expert/AGENT.md                |   66 +
 .../routines/orca_rwa_lp_ranger.py            |  468 +++++
 .../routines/orca_rwa_pool_analysis.py        |  274 +++
 .../skills/add_token_to_gateway/SKILL.md      |  117 ++
 20 files changed, 5981 insertions(+)
 create mode 100644 agents/backpack_mm/AGENT.md
 create mode 100644 agents/backpack_mm/routines/backpack_binance_funding_comparison.py
 create mode 100644 agents/backpack_mm/routines/backpack_funding_compare.py
 create mode 100644 agents/backpack_mm/routines/backpack_mm_volume_analysis.py
 create mode 100644 agents/backpack_mm/routines/backpack_volume_scan.py
 create mode 100644 agents/backpack_mm/skills/backpack_perp_mm_deploy/SKILL.md
 create mode 100644 agents/backpack_mm/skills/backpack_perp_mm_deploy/config_backpack_aggressive.md
 create mode 100644 agents/backpack_mm/strategies/backpack_perp_mm/strategy.md
 create mode 100644 agents/brigado/AGENT.md
 create mode 100644 agents/brigado/routines/bot_report.py
 create mode 100644 agents/brigado/routines/brl_dashboard.py
 create mode 100644 agents/brigado/routines/btc_brl_arbitrage.py
 create mode 100644 agents/brigado/routines/config_analyzer.py
 create mode 100644 agents/brigado/routines/spot_markets.py
 create mode 100644 agents/brigado/routines/toxic_flow_detector.py
 create mode 100644 agents/brigado/strategies/brl_mm/strategy.md
 create mode 100644 agents/orca_lp_expert/AGENT.md
 create mode 100644 agents/orca_lp_expert/routines/orca_rwa_lp_ranger.py
 create mode 100644 agents/orca_lp_expert/routines/orca_rwa_pool_analysis.py
 create mode 100644 agents/orca_lp_expert/skills/add_token_to_gateway/SKILL.md

diff --git a/agents/backpack_mm/AGENT.md b/agents/backpack_mm/AGENT.md
new file mode 100644
index 00000000..79987b40
--- /dev/null
+++ b/agents/backpack_mm/AGENT.md
@@ -0,0 +1,74 @@
+---
+name: Backpack MM
+description: Backpack Market Maker Program specialist — volume analysis, market selection,
+  bot deployment, and ongoing MM operations on Backpack perps
+agent_key: claude-acp:sonnet
+tools: []
+when_to_consult: When the user wants to analyze Backpack exchange markets, deploy
+  or manage MM bots on Backpack perps, understand volume requirements for the MM program,
+  check bot performance against program thresholds, or rotate markets for the Backpack
+  MM Rewards Program
+server_required: true
+server_name: local
+created_by: 481175164
+created_at: '2026-07-30T06:45:22.685798+00:00'
+---
+
+# Backpack MM Agent
+
+You are a specialist in the Backpack Exchange Market Maker Program. You analyze the volume landscape, select markets, deploy and manage pmm_mister bots, and track program qualification metrics.
+
+## What you do
+- Analyze 24h volume per market on Backpack (spot + perpetuals)
+- Compute how much maker volume is needed to reach program thresholds
+- Assess spread / uptime requirements per market
+- Recommend which markets are most tractable given capital constraints
+- Deploy and manage pmm_mister bots on Backpack perps
+- Monitor bot performance and adjust configs for program compliance
+- Rotate markets when volume shifts make qualification harder/easier
+
+## Program knowledge — Backpack Market Maker Program
+
+**Reward pool:** $300,000/month — $200k perps, $100k spot
+
+**Tier score** = max(Total Maker Share, Adjusted Maker Share)
+- Total Maker Share = user maker vol / total maker vol (no multipliers)
+- Adjusted Maker Share = user adjusted vol / total adjusted vol (lower-liquidity markets get multipliers)
+
+**Blended Score** (determines reward share per market):
+- (Volume Score × 0.8) + (Liquidity Score × 0.2)
+
+**Volume Score** = user maker vol / total maker vol on that market
+
+**Liquidity Score** = (Avg Order Size / Avg Spread) × Uptime Score
+- Orders must be within **100bps from mid** to count
+- Avg order size must be **≥ $2,000**
+
+**Minimum thresholds to receive rewards on a market:**
+- Volume Score ≥ 1.5%
+- Avg order size ≥ $2,000
+- At least 1% of total allocation
+
+**First month:** MM5 maker fees (best tier) regardless of volume.
+
+## Bot configuration
+
+Read the `backpack_perp_mm_deploy` skill before any deployment or config change.
+The adapted aggressive config uses:
+- Connector: `backpack_perpetual`
+- **Position mode: ONEWAY** — universal default for all pmm_mister configs on any connector; HEDGE only if explicitly requested. Backpack specifically does not support HEDGE at all (errors on startup)
+- 2 levels weighted 2:1, spreads 6bps/15bps
+- 300s effectivization, 30s cooldown
+- LIMIT_MAKER orders (type 3) for maker credit
+- 2x leverage, 5% global SL
+- $20K total_amount_quote per controller (min for $2K+ orders)
+
+## How you answer
+- Lead with the key number or recommendation
+- Use key: value format, not prose paragraphs
+- Always cite the data source and timestamp
+- Flag when data is estimated vs fetched live
+- If a routine is available, call it and reason over its output — don't guess
+
+## Routines
+- `backpack_volume_scan` — 24h perp volume scan with MM program thresholds
diff --git a/agents/backpack_mm/routines/backpack_binance_funding_comparison.py b/agents/backpack_mm/routines/backpack_binance_funding_comparison.py
new file mode 100644
index 00000000..b1b9473a
--- /dev/null
+++ b/agents/backpack_mm/routines/backpack_binance_funding_comparison.py
@@ -0,0 +1,257 @@
+"""Compare funding rates between Backpack and Binance perpetuals — interval-normalized carry comparison."""
+
+import asyncio
+import logging
+
+import aiohttp
+from pydantic import BaseModel, Field
+from telegram.ext import ContextTypes
+
+from condor.reports import ReportBuilder
+from routines.base import RoutineResult
+
+logger = logging.getLogger(__name__)
+
+CATEGORY = "Arbitrage"
+
+BACKPACK_API = "https://api.backpack.exchange/api/v1"
+BINANCE_FAPI = "https://fapi.binance.com/fapi/v1"
+
+HOURS_PER_YEAR = 8760
+
+
+class Config(BaseModel):
+    """Compare Backpack vs Binance perpetual funding rates, normalized by each exchange's payment interval."""
+
+    backpack_interval_h: int = Field(
+        default=1, description="Backpack funding interval in hours (default: 1h)"
+    )
+    binance_interval_h: int = Field(
+        default=8, description="Binance funding interval in hours (default: 8h)"
+    )
+    min_spread_apr_pct: float = Field(
+        default=10.0, description="Min annualized spread % to highlight as opportunity"
+    )
+    top_n: int = Field(default=20, description="Max rows in opportunities table")
+
+
+def _normalize_base(base: str) -> str:
+    """Strip kilo-denomination prefix for cross-exchange matching (1000SHIB / kSHIB → SHIB)."""
+    if base.startswith("1000"):
+        return base[4:]
+    if base and base[0] == "k" and len(base) > 1 and base[1].isupper():
+        return base[1:]
+    return base
+
+
+async def _fetch_backpack_rates(
+    session: aiohttp.ClientSession,
+) -> dict[str, tuple[float, str]]:
+    """Returns {canonical_base: (rate_per_payment, raw_base)} for all Backpack perp markets."""
+    async with session.get(f"{BACKPACK_API}/markets") as resp:
+        markets = await resp.json()
+
+    perp_symbols = [m["symbol"] for m in markets if m.get("marketType") == "PERP"]
+
+    sem = asyncio.Semaphore(8)
+
+    async def _fetch_one(symbol: str):
+        async with sem:
+            try:
+                async with session.get(
+                    f"{BACKPACK_API}/fundingRates",
+                    params={"symbol": symbol, "limit": 1},
+                ) as r:
+                    data = await r.json()
+                    if isinstance(data, list) and data:
+                        rate = data[0].get("fundingRate")
+                        if rate is not None:
+                            return symbol, float(rate)
+            except Exception as e:
+                logger.warning(f"Backpack funding fetch failed for {symbol}: {e}")
+        return symbol, None
+
+    results = await asyncio.gather(*[_fetch_one(s) for s in perp_symbols])
+
+    out: dict[str, tuple[float, str]] = {}
+    for symbol, rate in results:
+        if rate is not None:
+            raw_base = symbol.replace("_USDC_PERP", "").replace("_USDT_PERP", "")
+            canonical = _normalize_base(raw_base)
+            out[canonical] = (rate, raw_base)
+
+    return out
+
+
+async def _fetch_binance_rates(session: aiohttp.ClientSession) -> dict[str, float]:
+    """Returns {canonical_base: rate_per_payment} for all Binance USDT perp markets."""
+    async with session.get(f"{BINANCE_FAPI}/premiumIndex") as resp:
+        data = await resp.json()
+
+    out: dict[str, float] = {}
+    for item in data:
+        symbol = item.get("symbol", "")
+        if not symbol.endswith("USDT"):
+            continue
+        raw_base = symbol[:-4]
+        canonical = _normalize_base(raw_base)
+        rate = item.get("lastFundingRate")
+        if rate is not None:
+            out[canonical] = float(rate)
+
+    return out
+
+
+async def run(config: Config, context: ContextTypes.DEFAULT_TYPE) -> RoutineResult:
+    async with aiohttp.ClientSession() as session:
+        bp_raw, bn_raw = await asyncio.gather(
+            _fetch_backpack_rates(session),
+            _fetch_binance_rates(session),
+        )
+
+    common = sorted(set(bp_raw) & set(bn_raw))
+
+    def to_apr(rate_per_payment: float, interval_h: int) -> float:
+        """Convert a per-payment rate to annualized rate (APR)."""
+        payments_per_year = HOURS_PER_YEAR / interval_h
+        return rate_per_payment * payments_per_year
+
+    rows = []
+    for base in common:
+        bp_rate_raw, raw_base = bp_raw[base]
+        bn_rate_raw = bn_raw[base]
+
+        bp_apr = to_apr(bp_rate_raw, config.backpack_interval_h)
+        bn_apr = to_apr(bn_rate_raw, config.binance_interval_h)
+        spread_apr = bp_apr - bn_apr
+
+        # Per-hour rates for a granular comparison column
+        bp_per_h_bps = (bp_rate_raw / config.backpack_interval_h) * 10000
+        bn_per_h_bps = (bn_rate_raw / config.binance_interval_h) * 10000
+        spread_per_h_bps = bp_per_h_bps - bn_per_h_bps
+
+        if spread_apr > 0.0001:
+            trade = "Long BN / Short BP"
+        elif spread_apr < -0.0001:
+            trade = "Long BP / Short BN"
+        else:
+            trade = "Neutral"
+
+        rows.append(
+            {
+                "Asset": base,
+                "BP Symbol": raw_base,
+                "BP APR": f"{bp_apr * 100:.2f}%",
+                "BN APR": f"{bn_apr * 100:.2f}%",
+                "Spread APR": f"{spread_apr * 100:+.2f}%",
+                "Spread bps/h": f"{spread_per_h_bps:+.3f}",
+                "Trade": trade,
+                "_spread_apr": spread_apr,
+                "_spread_abs_apr": abs(spread_apr),
+                "_bp_apr": bp_apr,
+                "_bn_apr": bn_apr,
+                "_spread_per_h_bps": spread_per_h_bps,
+            }
+        )
+
+    rows.sort(key=lambda r: r["_spread_abs_apr"], reverse=True)
+
+    min_spread = config.min_spread_apr_pct / 100
+    opps = [r for r in rows if r["_spread_abs_apr"] >= min_spread]
+    top_rows = opps[: config.top_n]
+
+    table_cols = [
+        "Asset",
+        "BP Symbol",
+        "BP APR",
+        "BN APR",
+        "Spread APR",
+        "Spread bps/h",
+        "Trade",
+    ]
+    clean_top = [{k: r[k] for k in table_cols} for r in top_rows]
+    clean_all = [{k: r[k] for k in table_cols} for r in rows[:60]]
+
+    # ── Report ─────────────────────────────────────────────────────────────
+    builder = ReportBuilder("Backpack vs Binance Funding (Interval-Normalized)")
+    builder.source("routine", "backpack_binance_funding_comparison")
+    builder.tags(["funding", "arbitrage", "backpack", "binance", "carry"])
+    builder.manual_order()
+
+    builder.section("01 / OVERVIEW")
+    builder.kpi("Backpack Perps", str(len(bp_raw)))
+    builder.kpi("Binance Perps", str(len(bn_raw)))
+    builder.kpi("Common Markets", str(len(common)))
+    builder.kpi(f"Opps ≥{config.min_spread_apr_pct}% APR", str(len(opps)))
+    builder.kpi("BP Interval", f"{config.backpack_interval_h}h")
+    builder.kpi("BN Interval", f"{config.binance_interval_h}h")
+
+    builder.markdown(
+        f"Rates are **annualized**: Backpack raw rate ÷ {config.backpack_interval_h}h × 8,760 h/yr; "
+        f"Binance raw rate ÷ {config.binance_interval_h}h × 8,760 h/yr. "
+        f"**Spread bps/h** = (BP per-hour rate − BN per-hour rate) × 10,000 — "
+        f"the carry you earn or pay per hour of holding the delta-neutral pair."
+    )
+
+    dataset_rows = [
+        {
+            "asset": r["Asset"],
+            "bp_apr_pct": round(r["_bp_apr"] * 100, 2),
+            "bn_apr_pct": round(r["_bn_apr"] * 100, 2),
+            "spread_apr_pct": round(r["_spread_apr"] * 100, 2),
+            "abs_spread_apr_pct": round(r["_spread_abs_apr"] * 100, 2),
+            "spread_bps_per_h": round(r["_spread_per_h_bps"], 3),
+        }
+        for r in rows
+    ]
+    builder.dataset("funding", dataset_rows)
+    builder.chart(
+        "bar",
+        "Spread (APR %) by Asset",
+        "funding",
+        "asset",
+        "spread_apr_pct",
+        y_label="Spread APR (%)",
+        x_label="Asset",
+        reference_lines=[{"axis": "y", "value": 0, "label": "Zero"}],
+    )
+
+    builder.section(
+        "02 / OPPORTUNITIES",
+        f"Sorted by |spread APR|. Threshold: {config.min_spread_apr_pct}% APR. "
+        f"BP pays every {config.backpack_interval_h}h, BN every {config.binance_interval_h}h.",
+    )
+    if clean_top:
+        builder.table(clean_top, table_cols)
+    else:
+        builder.markdown(
+            f"No common markets with |spread| ≥ {config.min_spread_apr_pct}% APR."
+        )
+
+    builder.section("03 / ALL COMMON MARKETS", "Full list sorted by |spread APR|.")
+    builder.table(clean_all, table_cols)
+
+    report_id = await builder.save()
+
+    # ── Inline summary ──────────────────────────────────────────────────────
+    top3 = top_rows[:3]
+    lines = [
+        f"Backpack vs Binance Funding  (BP={config.backpack_interval_h}h / BN={config.binance_interval_h}h intervals)",
+        f"{len(common)} common markets | {len(opps)} opps ≥{config.min_spread_apr_pct}% APR",
+        "",
+    ]
+    if top3:
+        for r in top3:
+            lines.append(
+                f"  {r['Asset']:8s}  BP={r['BP APR']:>9s}  BN={r['BN APR']:>9s}"
+                f"  spread={r['Spread APR']:>9s}  → {r['Trade']}"
+            )
+    else:
+        lines.append("  No opportunities above threshold.")
+    lines.append(f"\nReport: {report_id}")
+
+    return RoutineResult(
+        text="\n".join(lines),
+        table_data=clean_top[:10],
+        table_columns=table_cols,
+    )
diff --git a/agents/backpack_mm/routines/backpack_funding_compare.py b/agents/backpack_mm/routines/backpack_funding_compare.py
new file mode 100644
index 00000000..e69de29b
diff --git a/agents/backpack_mm/routines/backpack_mm_volume_analysis.py b/agents/backpack_mm/routines/backpack_mm_volume_analysis.py
new file mode 100644
index 00000000..e69de29b
diff --git a/agents/backpack_mm/routines/backpack_volume_scan.py b/agents/backpack_mm/routines/backpack_volume_scan.py
new file mode 100644
index 00000000..5d737343
--- /dev/null
+++ b/agents/backpack_mm/routines/backpack_volume_scan.py
@@ -0,0 +1,257 @@
+"""Scan Backpack Exchange perp markets: 24h volume, MM program thresholds, and tractability ranking."""
+
+import logging
+
+import aiohttp
+from pydantic import BaseModel, Field
+from telegram.ext import ContextTypes
+
+from condor.reports import ReportBuilder
+from routines.base import RoutineResult
+
+logger = logging.getLogger(__name__)
+
+CATEGORY = "Market Data"
+
+BACKPACK_API = "https://api.backpack.exchange/api/v1"
+
+
+class Config(BaseModel):
+    """Backpack perp volume scan — MM program threshold analysis"""
+
+    target_share_pct: float = Field(
+        default=0.5, description="Target maker volume share % (e.g. 0.5 = 0.5%)"
+    )
+    min_volume_score_pct: float = Field(
+        default=1.5, description="Min Volume Score % to qualify on a market"
+    )
+
+
+async def run(config: Config, context: ContextTypes.DEFAULT_TYPE) -> str:
+    async with aiohttp.ClientSession() as session:
+        # Fetch tickers and markets in parallel
+        async with session.get(f"{BACKPACK_API}/tickers") as resp:
+            if resp.status != 200:
+                return f"Backpack API error: {resp.status}"
+            tickers = await resp.json()
+
+        async with session.get(f"{BACKPACK_API}/markets") as resp:
+            if resp.status != 200:
+                return f"Backpack markets API error: {resp.status}"
+            markets = await resp.json()
+
+    # Build market info lookup
+    market_info = {m["symbol"]: m for m in markets if m.get("marketType") == "PERP"}
+
+    # Filter perp tickers and parse volumes
+    perps = []
+    for t in tickers:
+        sym = t.get("symbol", "")
+        if not sym.endswith("_PERP"):
+            continue
+        quote_vol = float(t.get("quoteVolume", 0))
+        last_price = float(t.get("lastPrice", 0))
+        trades = int(t.get("trades", 0))
+        price_change_pct = float(t.get("priceChangePercent", 0)) * 100
+        base = sym.replace("_USDC_PERP", "").replace("k", "")
+
+        # Get margin requirements from market info
+        info = market_info.get(sym, {})
+        imf_base = float(info.get("imfFunction", {}).get("base", 0))
+        max_leverage = round(1 / imf_base, 1) if imf_base > 0 else 0
+
+        perps.append(
+            {
+                "symbol": sym,
+                "base": base,
+                "quote_volume_24h": quote_vol,
+                "last_price": last_price,
+                "trades_24h": trades,
+                "price_change_pct": round(price_change_pct, 2),
+                "max_leverage": max_leverage,
+            }
+        )
+
+    if not perps:
+        return "No perpetual markets found on Backpack"
+
+    # Sort by volume descending
+    perps.sort(key=lambda x: x["quote_volume_24h"], reverse=True)
+
+    total_volume = sum(p["quote_volume_24h"] for p in perps)
+
+    # Calculate thresholds
+    target_share = config.target_share_pct / 100
+    min_vol_score = config.min_volume_score_pct / 100
+
+    target_total_volume = total_volume * target_share  # 0.5% of total perp volume
+    monthly_target = target_total_volume * 30
+
+    # Per-market analysis
+    table_data = []
+    for p in perps:
+        vol = p["quote_volume_24h"]
+        vol_share = (vol / total_volume * 100) if total_volume > 0 else 0
+        # Volume needed for 1.5% Volume Score on this market
+        needed_for_qual = vol * min_vol_score / (1 - min_vol_score)
+        # Volume needed for target share on this market
+        needed_for_target = vol * target_share / (1 - target_share)
+
+        table_data.append(
+            {
+                "Market": p["base"],
+                "24h Vol": f"${vol:,.0f}",
+                "Vol Share": f"{vol_share:.1f}%",
+                "Trades": f"{p['trades_24h']:,}",
+                "Price": (
+                    f"${p['last_price']:,.4f}"
+                    if p["last_price"] < 1
+                    else f"${p['last_price']:,.2f}"
+                ),
+                "24h Chg": f"{p['price_change_pct']:+.1f}%",
+                "Max Lev": f"{p['max_leverage']:.0f}x",
+                "Need 1.5% VS": f"${needed_for_qual:,.0f}",
+                "Need 0.5% Total": f"${needed_for_target:,.0f}",
+                "_vol": vol,
+                "_needed_qual": needed_for_qual,
+                "_needed_target": needed_for_target,
+            }
+        )
+
+    # Build report
+    builder = ReportBuilder("Backpack Perp Volume Scan")
+    builder.source("routine", "backpack_volume_scan")
+    builder.tags(["backpack", "volume", "market-making", "perps"])
+    builder.manual_order()
+
+    builder.section("01 / PROGRAM OVERVIEW")
+    builder.kpi("Total Perp Volume (24h)", f"${total_volume:,.0f}")
+    builder.kpi("Perp Markets", str(len(perps)))
+    builder.kpi(
+        f"Target Share ({config.target_share_pct}%)", f"${target_total_volume:,.0f}/day"
+    )
+    builder.kpi("Monthly Target (30d)", f"${monthly_target:,.0f}")
+    builder.kpi("Min Vol Score Threshold", f"{config.min_volume_score_pct}%")
+
+    builder.section("02 / VOLUME BY MARKET")
+    builder.markdown(
+        "**Need 1.5% VS** = maker volume needed on that market to hit the 1.5% Volume Score minimum.\n\n"
+        f"**Need {config.target_share_pct}% Total** = maker volume needed on that market alone to reach "
+        f"{config.target_share_pct}% of total perp maker volume."
+    )
+
+    # Interactive dataset
+    dataset_rows = []
+    for p in perps:
+        vol = p["quote_volume_24h"]
+        vol_share = (vol / total_volume * 100) if total_volume > 0 else 0
+        needed_qual = vol * min_vol_score / (1 - min_vol_score)
+        needed_target = vol * target_share / (1 - target_share)
+        dataset_rows.append(
+            {
+                "market": p["base"],
+                "volume_24h": round(vol, 2),
+                "vol_share_pct": round(vol_share, 2),
+                "trades_24h": p["trades_24h"],
+                "last_price": p["last_price"],
+                "change_pct": p["price_change_pct"],
+                "max_leverage": p["max_leverage"],
+                "need_1_5_pct_vs": round(needed_qual, 2),
+                "need_target_share": round(needed_target, 2),
+            }
+        )
+
+    builder.dataset("perps", dataset_rows)
+
+    builder.chart(
+        "bar",
+        "24h Volume by Market (USD)",
+        "perps",
+        "market",
+        "volume_24h",
+        y_label="Volume (USD)",
+        x_label="Market",
+    )
+
+    # Display table (clean columns without internal fields)
+    display_cols = [
+        "Market",
+        "24h Vol",
+        "Vol Share",
+        "Trades",
+        "Price",
+        "24h Chg",
+        "Max Lev",
+        "Need 1.5% VS",
+        f"Need {config.target_share_pct}% Total",
+    ]
+    clean_table = [{k: row[k] for k in display_cols} for row in table_data]
+    builder.table(clean_table, display_cols)
+
+    builder.section("03 / TRACTABILITY RANKING")
+    builder.markdown(
+        "Markets sorted by **lowest maker volume needed** to hit 1.5% Volume Score — "
+        "these are the easiest to qualify on."
+    )
+
+    # Sort by needed_for_qual ascending (most tractable first)
+    tractable = sorted(table_data, key=lambda x: x["_needed_qual"])
+    tract_table = []
+    for i, row in enumerate(tractable[:15], 1):
+        tract_table.append(
+            {
+                "#": i,
+                "Market": row["Market"],
+                "24h Vol": row["24h Vol"],
+                "Need for 1.5% VS": row["Need 1.5% VS"],
+                "Daily @ Target": row[f"Need {config.target_share_pct}% Total"],
+            }
+        )
+    builder.table(
+        tract_table, ["#", "Market", "24h Vol", "Need for 1.5% VS", "Daily @ Target"]
+    )
+
+    builder.section("04 / STRATEGY NOTES")
+    builder.markdown(
+        f"**Reward pool**: $200k/month for perps\n\n"
+        f"**Blended Score** = (Volume Score × 0.8) + (Liquidity Score × 0.2)\n\n"
+        f"**Volume Score** = your maker vol / total maker vol on that market\n\n"
+        f"**Liquidity Score** = (Avg Order Size / Avg Spread) × Uptime\n\n"
+        f"**Minimum thresholds per market**: Volume Score ≥ 1.5%, Avg order ≥ $2,000\n\n"
+        f"**Tier Score** = max(Total Maker Share, Adjusted Maker Share) — "
+        f"lower-liquidity markets get multipliers in the adjusted calculation, "
+        f"making them more rewarding per dollar traded.\n\n"
+        f"**First month**: MM5 maker fees (best tier) regardless of volume."
+    )
+
+    report_id = await builder.save()
+
+    # Build inline summary
+    top5 = perps[:5]
+    top5_lines = "\n".join(
+        f"  {p['base']}: ${p['quote_volume_24h']:,.0f} (need ${p['quote_volume_24h'] * min_vol_score / (1 - min_vol_score):,.0f} for 1.5% VS)"
+        for p in top5
+    )
+    easiest3 = sorted(perps, key=lambda x: x["quote_volume_24h"])[:3]
+    easiest_lines = "\n".join(
+        f"  {p['base']}: need only ${p['quote_volume_24h'] * min_vol_score / (1 - min_vol_score):,.0f}/day"
+        for p in easiest3
+    )
+
+    summary = (
+        f"Backpack Perp Volume Scan\n"
+        f"Total 24h perp volume: ${total_volume:,.0f}\n"
+        f"Target ({config.target_share_pct}% share): ${target_total_volume:,.0f}/day\n\n"
+        f"Top 5 by volume:\n{top5_lines}\n\n"
+        f"Easiest to qualify (1.5% VS):\n{easiest_lines}\n\n"
+        f"Report: {report_id}"
+    )
+
+    return RoutineResult(
+        text=summary,
+        table_data=[
+            {k: row[k] for k in ["Market", "24h Vol", "Vol Share", "Need 1.5% VS"]}
+            for row in table_data[:10]
+        ],
+        table_columns=["Market", "24h Vol", "Vol Share", "Need 1.5% VS"],
+    )
diff --git a/agents/backpack_mm/skills/backpack_perp_mm_deploy/SKILL.md b/agents/backpack_mm/skills/backpack_perp_mm_deploy/SKILL.md
new file mode 100644
index 00000000..71f6619c
--- /dev/null
+++ b/agents/backpack_mm/skills/backpack_perp_mm_deploy/SKILL.md
@@ -0,0 +1,94 @@
+---
+name: backpack_perp_mm_deploy
+description: End-to-end playbook for deploying pmm_mister bots on Backpack perps optimized
+  for the MM Rewards Program — adapted aggressive config, volume targets, and program
+  compliance.
+when_to_use: When deploying, configuring, or tuning market making bots on Backpack
+  perpetuals. Also when asked about Backpack MM program compliance, order sizing,
+  or spread settings for the rewards program.
+created: '2026-08-10T21:14:30Z'
+source: agent:backpack_mm
+---
+
+# Backpack Perp MM Deploy Playbook
+
+Adapted from the market_making_expert's aggressive pmm_mister profile,
+tuned specifically for the **Backpack MM Rewards Program** on perpetuals.
+
+## Program constraints (hard requirements)
+
+- **Avg order size ≥ $2,000** — orders below this don't count
+- **Orders within 100bps from mid** — spreads must be < 0.01
+- **Volume Score ≥ 1.5%** per market to receive rewards
+- **Post-only orders** — must be LIMIT_MAKER (type 3) for maker volume
+- **Uptime matters** — Liquidity Score = (Avg Order Size / Avg Spread) × Uptime
+
+## Config template — Backpack MM Aggressive
+
+Fetch the full config from the companion file:
+```
+manage_skill(action="read_file", name="backpack_perp_mm_deploy", file="config_backpack_aggressive.md")
+```
+
+### Key adaptations vs standard aggressive profile
+
+| Parameter | Standard Aggressive | Backpack MM | Why |
+|-----------|-------------------|-------------|-----|
+| total_amount_quote | $500 | **$20,000** | Min $2K orders need larger capital |
+| levels | 2 equal | **2 weighted (2:1)** | Front-load L1 for volume, L2 for depth/Liquidity Score |
+| spreads | 8bps, 15bps | **6bps, 15bps** | Tighter L1 for fills, wide L2 for depth |
+| effectivization_time | 60s | **300s** | More time for TP to fill on thin markets → volume cycling |
+| take_profit | 8bps | **6bps** | Fast cycle, viable with MM5 fees (first month) |
+| cooldown_time | 30s | **30s** | Prevent adverse stacking on thin markets |
+| leverage | 10x | **2x** | Mid-tier perps are volatile, protect capital |
+| order_type | 3 | **3** | LIMIT_MAKER mandatory for program credit |
+
+## Deployment steps
+
+1. **Run volume scan** — `manage_routines(action="run", name="backpack_volume_scan")`
+   to get fresh 24h volume data and identify tractable markets.
+
+2. **Pick markets** — Select 3-5 mid-tier perps where needed maker volume for
+   1.5% VS is achievable ($8-15K/day range). Avoid BTC (needs $1M+/day).
+
+3. **Verify pairs exist on Backpack perps** — Before creating any config, confirm
+   each ticker actually exists as a perpetual on Backpack by checking
+   `GET https://api.backpack.exchange/api/v1/markets`. The volume scan may report
+   spot-style tickers that don't match the actual perp symbol. Known gotchas:
+   - BONK perp = **kBONK**, SHIB perp = **kSHIB** (kilo-denominated)
+   - TRX, STABLE — **no perp exists**
+   - When in doubt, fetch the markets list and grep for the symbol
+
+4. **Read config template** — fetch `config_backpack_aggressive.md` companion file.
+
+5. **Adapt per market** — substitute `trading_pair`, verify leverage is within
+   the market's max (check `imfFunction.base` from /api/v1/markets).
+
+6. **Set position mode** — Backpack perpetual **only supports ONEWAY** position
+   mode. Always set `"position_mode": "ONEWAY"`. Never use `HEDGE` — the bot
+   will error on startup if HEDGE is set.
+
+7. **Upsert configs** — one config per market via `manage_controllers(action="upsert", target="config", ...)`.
+   Name convention: `NNN_pmm_backpack_<PAIR>`.
+
+8. **Deploy single bot** with all controllers:
+   ```
+   manage_bots(action="deploy", bot_name="backpack_mm_perps_<timestamp>",
+     controllers_config=["config1", "config2", "config3"])
+   ```
+
+9. **Verify** — `manage_bots(action="status")` to confirm all controllers running.
+
+## Volume math (per controller)
+
+- Order size L1: $20K × 0.25 × (2/3) = **$3,333** ✓ (above $2K)
+- Order size L2: $20K × 0.25 × (1/3) = **$1,667** (depth, may not count for avg)
+- Per complete fill→TP cycle: 2 × $3,333 = **$6,666** maker volume
+- Need ~2-3 cycles/day per market for 1.5% VS on $900K market
+- At 300s effectivization + 30s cooldown: achievable
+
+## Monitoring
+
+- Schedule `backpack_volume_scan` daily to track volume shifts
+- Check bot PnL and fill rates via mm_bot_report
+- Watch for markets dropping below threshold — may need to rotate
diff --git a/agents/backpack_mm/skills/backpack_perp_mm_deploy/config_backpack_aggressive.md b/agents/backpack_mm/skills/backpack_perp_mm_deploy/config_backpack_aggressive.md
new file mode 100644
index 00000000..9f7790b1
--- /dev/null
+++ b/agents/backpack_mm/skills/backpack_perp_mm_deploy/config_backpack_aggressive.md
@@ -0,0 +1,94 @@
+# Backpack MM Aggressive Config Template
+
+Adapted from the MM expert's aggressive profile, tuned for Backpack MM Rewards
+Program compliance. All orders are LIMIT_MAKER (post-only) for maker credit.
+
+## Config (substitute connector/pair/amount per market)
+
+```json
+{
+  "controller_type": "generic",
+  "controller_name": "pmm_mister",
+  "connector_name": "backpack_perpetual",
+  "trading_pair": "<PAIR>-USDC",
+  "total_amount_quote": 20000,
+  "portfolio_allocation": 0.25,
+  "target_base_pct": 0.5,
+  "min_base_pct": 0.3,
+  "max_base_pct": 0.7,
+  "buy_spreads": "0.0003,0.0015",
+  "sell_spreads": "0.0003,0.0015",
+  "buy_amounts_pct": "2,1",
+  "sell_amounts_pct": "2,1",
+  "executor_refresh_time": 20,
+  "buy_cooldown_time": 30,
+  "sell_cooldown_time": 30,
+  "buy_position_effectivization_time": 300,
+  "sell_position_effectivization_time": 300,
+  "price_distance_tolerance": 0.0005,
+  "refresh_tolerance": 0.0003,
+  "tolerance_scaling": 1.1,
+  "open_order_type": 3,
+  "take_profit": 0.0006,
+  "take_profit_order_type": 3,
+  "leverage": 2,
+  "position_mode": "ONEWAY",
+  "position_side": "BUY",
+  "max_active_executors_by_level": 2,
+  "tick_mode": false,
+  "min_skew": 1.0,
+  "global_tp_enabled": false,
+  "global_sl_enabled": true,
+  "global_stop_loss": 0.05,
+  "global_sl_activation_from": "target_base",
+  "global_pnl_reference": "position"
+}
+```
+
+## Position mode — universal default
+
+**Always use `"position_mode": "ONEWAY"`** for pmm_mister configs on any connector.
+This is the universal default — not just a Backpack restriction. HEDGE should only
+be used when the user explicitly requests it.
+
+On Backpack specifically, HEDGE is not supported at all and will error on startup.
+On other connectors (Hyperliquid, Binance, etc.), ONEWAY is still the default unless
+the user says otherwise.
+
+## Parameter rationale
+
+**Order sizing** (meets $2K minimum):
+- Level 1: $20K × 0.25 × (2/3) = $3,333 per order
+- Level 2: $20K × 0.25 × (1/3) = $1,667 per order (depth)
+- Both sides quoting = continuous presence
+
+**Spreads** (within 100bps program limit):
+- L1: 3bps — very tight, maximizes fill rate and volume generation
+- L2: 15bps — passive depth, helps Liquidity Score
+
+**Effectivization** (300s):
+- After a fill, the LIMIT_MAKER TP order stays on book for 5 minutes
+- On mid-tier perps, price needs time to cycle back for TP fill
+- Complete fill→TP cycle = 2× notional in maker volume
+- 60s was too short (most positions expired to hold); 300s catches ~50%+ of TPs
+
+**Take profit** (6bps):
+- With MM5 fees (~0.02% maker), round-trip ~0.04%
+- 6bps TP gives 1.5× fee coverage — tight but viable
+- If Backpack fees are higher than expected, bump to 8bps
+
+**Leverage** (2x):
+- Mid-tier perps (ZEC, PUMP, WLD) can gap 5-10%
+- At 2x: 5% move = 10% drawdown → survivable with 5% global SL
+- At 5x: 5% move = 25% drawdown → dangerous
+
+**Cooldown** (30s):
+- Prevents stacking fills at similar prices on thin markets
+- 15s was too aggressive for $500-900K/day volume markets
+
+## Adjustments per market
+
+- **PAXG**: Gold-backed, low vol → can keep 3bps, reduce cooldown to 20s
+- **ZEC/WLD**: Moderate vol → use template as-is
+- **PUMP**: Higher vol, can gap → monitor closely with 3bps, widen to 5bps if adverse fills spike
+- **Leverage**: Always verify max leverage per market (1/imfFunction.base from API)
diff --git a/agents/backpack_mm/strategies/backpack_perp_mm/strategy.md b/agents/backpack_mm/strategies/backpack_perp_mm/strategy.md
new file mode 100644
index 00000000..35c9c1b0
--- /dev/null
+++ b/agents/backpack_mm/strategies/backpack_perp_mm/strategy.md
@@ -0,0 +1,69 @@
+---
+name: Backpack Perp MM
+description: ''
+agent_key: null
+skills: []
+default_config:
+  frequency_sec: 3600
+  total_amount_quote: 60000
+default_trading_context: ''
+created_by: 481175164
+created_at: '2026-08-10T21:16:55.078013+00:00'
+---
+
+# Backpack Perp MM Strategy
+
+Market making on Backpack perpetuals targeting the MM Rewards Program.
+Agent pinned to `local` server.
+
+## Loop playbook
+
+Each tick:
+
+1. **Volume check** — Run `backpack_volume_scan` routine to get fresh 24h volumes.
+   Compare current market volumes against previous tick. Flag markets where volume
+   dropped below qualification threshold.
+
+2. **Bot health** — Check `manage_bots(action="status")` for the running bot.
+   Verify all controllers are in `running` state. Check for errors in logs.
+
+3. **Performance assessment** — For each controller:
+   - Current PnL (realized + unrealized)
+   - Volume generated vs target (need 1.5% VS per market)
+   - Inventory balance (base_pct within min/max band)
+   - Fill rate and TP hit rate
+
+4. **Compliance check** — Verify program metrics:
+   - Are avg order sizes ≥ $2,000?
+   - Are spreads within 100bps?
+   - Is uptime acceptable for Liquidity Score?
+
+5. **Adjust if needed**:
+   - If a market's volume dropped and qualification is at risk → consider rotating
+     to a more tractable market
+   - If inventory is drifting → adjust target/min/max_base_pct live
+   - If PnL is bleeding → widen spreads or increase cooldown
+   - If volume target is not being met → tighten spreads cautiously
+
+6. **Journal** — Write a summary of the tick: volumes, PnL, compliance status,
+   any adjustments made.
+
+## Active deployment
+
+- Bot: `backpack_mm_perps_20260811-20260810-211539`
+- Controllers (all 3bps L1 / 15bps L2, 6bps TP, 2x leverage, $20K each):
+  - `001_pmm_backpack_ZEC-USDC` — ZEC perp
+  - `002_pmm_backpack_WLD-USDC` — WLD perp
+  - `003_pmm_backpack_PUMP-USDC` — PUMP perp
+
+## Risk limits
+
+- Max $20K per controller ($60K total across 3 markets)
+- 2x leverage
+- 5% global stop loss per controller
+- No global TP — let volume cycle
+
+## Skills to read
+
+- `backpack_perp_mm_deploy` — full config template and deployment steps
+- `backpack_volume_scan` routine — fresh volume data
diff --git a/agents/brigado/AGENT.md b/agents/brigado/AGENT.md
new file mode 100644
index 00000000..b81b6a9d
--- /dev/null
+++ b/agents/brigado/AGENT.md
@@ -0,0 +1,16 @@
+---
+name: Brigado
+description: BRL market making research agent. Tracks USDT-BRL spreads, BTC/fiat
+  volume dynamics, and bot performance for the Brazilian market making operation.
+agent_key: claude-acp:sonnet
+tools: []
+when_to_consult: ''
+server_required: true
+created_by: 481175164
+created_at: '2026-05-04T00:00:00+00:00'
+---
+
+## Brigado
+
+### Objective
+Research and monitoring agent for the Brazilian market making operation. Provides dashboards, volume analysis, and bot performance tracking focused on BRL pairs and fiat market dynamics.
diff --git a/agents/brigado/routines/bot_report.py b/agents/brigado/routines/bot_report.py
new file mode 100644
index 00000000..561257be
--- /dev/null
+++ b/agents/brigado/routines/bot_report.py
@@ -0,0 +1,1752 @@
+"""Bot Performance Report — Clean 2-message report with USD values and rebate tracking."""
+
+CATEGORY = "Bot Analysis"
+
+import asyncio
+import logging
+import os
+import re
+from collections import defaultdict
+from datetime import datetime, timezone
+
+import plotly.graph_objects as go
+from plotly.subplots import make_subplots
+from pydantic import BaseModel, Field
+from telegram.ext import ContextTypes
+
+from config_manager import get_client, get_config_manager
+
+logger = logging.getLogger(__name__)
+
+REBATE_RATE = 0.00015  # 0.015% of volume — only applies to BRL-quoted pairs
+
+# Config analysis constants
+_CONFIG_SKIP_PARAMS = {
+    "id",
+    "controller_type",
+    "controller_name",
+    "manual_kill_switch",
+    "_config_name",
+}
+_CONFIG_KEY_PARAMS = {
+    "buy_spreads",
+    "sell_spreads",
+    "buy_amounts_pct",
+    "sell_amounts_pct",
+    "total_amount_quote",
+    "stop_loss",
+    "take_profit",
+    "time_limit",
+    "executor_refresh_time",
+    "cooldown_time",
+    "leverage",
+    "dca_spreads",
+    "dca_amounts",
+    "trailing_stop",
+    "executor_activation_bounds",
+    "top_executor_refresh_time",
+    "position_rebalance_threshold_pct",
+}
+
+
+def _pair_has_rebate(pair: str, quote_currency: str) -> bool:
+    """Rebate only applies to pairs quoted in the rebate currency (BRL)."""
+    if not pair or "-" not in pair:
+        return False
+    return pair.split("-")[-1].upper() == quote_currency.upper()
+
+
+class Config(BaseModel):
+    """Generate a formatted performance report for all active bots."""
+
+    quote_currency: str = Field(
+        default="BRL",
+        description="Quote currency of the bots (for USD conversion)",
+    )
+    target_chat_id: int | None = Field(
+        default=None,
+        description="Send report to this chat ID instead of the current chat (e.g. a group chat)",
+    )
+    server_name: str = Field(
+        default="brigado_2",
+        description="Server to connect to for bot data (bots run on this server)",
+    )
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _fmt(n: float, decimals: int = 2) -> str:
+    if abs(n) >= 1_000:
+        return f"{n:,.{decimals}f}"
+    return f"{n:.{decimals}f}"
+
+
+def _sign(n: float) -> str:
+    return "+" if n >= 0 else "-"
+
+
+def _emoji(n: float) -> str:
+    return "🟢" if n > 0 else "🔴" if n < 0 else "⚪"
+
+
+def _md_escape(text: str) -> str:
+    """Escape special characters for Telegram MarkdownV2."""
+    special = r"_*[]()~`>#+-=|{}.!"
+    result = []
+    for ch in text:
+        if ch in special:
+            result.append(f"\\{ch}")
+        else:
+            result.append(ch)
+    return "".join(result)
+
+
+# ---------------------------------------------------------------------------
+# Data fetching
+# ---------------------------------------------------------------------------
+
+
+async def _get_bots_data(client) -> dict:
+    data = await client.bot_orchestration.get_active_bots_status()
+    if isinstance(data, dict) and "data" in data:
+        return data["data"]
+    return {}
+
+
+async def _get_bot_runs(client) -> dict:
+    runs = {}
+    try:
+        data = await client.bot_orchestration.get_bot_runs()
+        if isinstance(data, dict) and "data" in data:
+            for run in data["data"]:
+                if run.get("deployment_status") == "DEPLOYED" and run.get(
+                    "deployed_at"
+                ):
+                    runs[run["bot_name"]] = run["deployed_at"]
+    except Exception:
+        pass
+    return runs
+
+
+async def _get_prices(client, connector: str, pairs: list[str]) -> dict[str, float]:
+    try:
+        result = await client.market_data.get_prices(
+            connector_name=connector, trading_pairs=",".join(pairs)
+        )
+        return result.get("prices", {}) if result else {}
+    except Exception as e:
+        logger.warning(f"Failed to get prices: {e}")
+        return {}
+
+
+async def _get_balances(client) -> dict:
+    """Fetch portfolio balances from all accounts."""
+    try:
+        return await client.portfolio.get_state(refresh=False)
+    except Exception as e:
+        logger.warning(f"Failed to get balances: {e}")
+        return {}
+
+
+async def _get_market_volume_since(
+    client, connector: str, pair: str, since_dt: datetime | None
+) -> tuple[float, float]:
+    """Return (base_volume, quote_volume) accumulated from candles since *since_dt*.
+
+    Uses 1h candles spanning from *since_dt* to now so the market volume window
+    matches the bot's runtime, giving an accurate market-share calculation.
+    Falls back to a single 1d candle when *since_dt* is unavailable.
+    """
+    try:
+        if since_dt:
+            now = datetime.now(timezone.utc)
+            days = max(1, int((now - since_dt).total_seconds() / 86400) + 1)
+            candles = await client.market_data.get_candles_last_days(
+                connector_name=connector,
+                trading_pair=pair,
+                days=days,
+                interval="1h",
+            )
+        else:
+            candles = await client.market_data.get_candles(
+                connector_name=connector,
+                trading_pair=pair,
+                interval="1d",
+                max_records=1,
+            )
+
+        if candles:
+            data = candles if isinstance(candles, list) else candles.get("data", [])
+            if not data:
+                return 0.0, 0.0
+
+            since_ts = since_dt.timestamp() if since_dt else 0
+            total_base = 0.0
+            total_quote = 0.0
+            for row in data:
+                # Only count candles that start at or after the deploy time
+                ts = float(row.get("timestamp", 0) or 0)
+                # Normalise ms → s if needed
+                if ts > 1e12:
+                    ts /= 1000
+                if ts >= since_ts:
+                    total_base += float(row.get("volume", 0) or 0)
+                    total_quote += float(row.get("quote_asset_volume", 0) or 0)
+            return total_base, total_quote
+    except Exception as e:
+        logger.warning(f"Failed to get volume for {pair}: {e}")
+    return 0.0, 0.0
+
+
+# ---------------------------------------------------------------------------
+# Chart builders (Plotly)
+# ---------------------------------------------------------------------------
+
+_DARK_BG = "#1a1a2e"
+_DARK_PAPER = "#16213e"
+_GREEN = "#00d4aa"
+_RED = "#ff6b6b"
+_BLUE = "#58a6ff"
+_YELLOW = "#ffdd57"
+_COLORS = [
+    "#58a6ff",
+    "#00d4aa",
+    "#ff6b6b",
+    "#ffdd57",
+    "#c084fc",
+    "#fb923c",
+    "#38bdf8",
+    "#f472b6",
+]
+
+
+def _chart_layout(title: str, **kwargs) -> dict:
+    base = dict(
+        title=dict(text=title, font=dict(color="#e6edf3", size=14), x=0.5),
+        paper_bgcolor=_DARK_PAPER,
+        plot_bgcolor=_DARK_BG,
+        font=dict(color="#ccc", size=11),
+        margin=dict(l=60, r=80, t=50, b=80),
+        width=1100,
+        height=450,
+    )
+    base.update(kwargs)
+    return base
+
+
+def _quote_is_usd(pair: str) -> bool:
+    """Check if a pair's quote currency is a USD stablecoin."""
+    if not pair or "-" not in pair:
+        return False
+    return pair.split("-")[-1].upper() in ("USD", "USDT", "USDC", "BUSD", "FDUSD")
+
+
+def _vol_to_usd(ctrl: dict, to_usd: float) -> float:
+    """Convert controller volume to USD based on the pair's quote currency."""
+    if _quote_is_usd(ctrl.get("pair", "")):
+        return ctrl["vol"]
+    return ctrl["vol"] * to_usd
+
+
+def _amount_quote_to_usd(ctrl: dict, to_usd: float) -> float:
+    """Convert total_amount_quote to USD based on the pair's quote currency."""
+    amt = ctrl.get("total_amount_quote", 0)
+    if _quote_is_usd(ctrl.get("pair", "")):
+        return amt
+    return amt * to_usd
+
+
+def _market_vol_to_usd(
+    pair: str,
+    vol_base: float,
+    vol_quote: float,
+    to_usd: float,
+    prices: dict[str, float],
+) -> float:
+    """Convert market candle volume to USD for any pair."""
+    base = pair.split("-")[0].upper() if "-" in pair else ""
+    quote = pair.split("-")[-1].upper() if "-" in pair else ""
+
+    # If base is a stablecoin, vol_base is already ~USD
+    if base in ("USDT", "USDC", "BUSD", "DAI", "FDUSD"):
+        return vol_base
+
+    # If quote is USD stablecoin, vol_quote is already USD
+    if quote in ("USD", "USDT", "USDC", "BUSD", "FDUSD"):
+        return (
+            vol_quote
+            if vol_quote > 0
+            else vol_base * (prices.get(f"{base}-USDT", 0) or 0)
+        )
+
+    # Non-USD quote (e.g. BRL) — convert quote volume, or use base price
+    if vol_quote > 0:
+        return vol_quote * to_usd
+    bp = prices.get(f"{base}-USDT", 0) or prices.get(f"{base}-USD", 0)
+    return vol_base * bp if bp else 0
+
+
+def _short_chart_name(ctrl_id: str, pair: str = "") -> str:
+    """Clean controller name for chart labels."""
+    name = ctrl_id
+    # Strip common prefixes
+    name = re.sub(r"^mm_", "", name)
+    name = re.sub(r"pmm_?mister_?", "", name)
+    # Strip connector prefixes (binance_, binance_perpetual_, etc.)
+    name = re.sub(r"^(binance|okx|bybit|kucoin)(_perpetual)?_", "", name)
+    # Strip pair fragment
+    if pair:
+        pair_frag = pair.replace("-", "_")
+        name = name.replace(pair_frag, "").replace(pair, "")
+    while "__" in name:
+        name = name.replace("__", "_")
+    name = name.strip("_")
+    name = re.sub(r"config[_]?(\d+)", r"c\1", name)
+    return name or ctrl_id[:20]
+
+
+def _build_pnl_chart(
+    controllers: list[dict],
+    to_usd: float,
+    quote_currency: str = "BRL",
+    ctrl_configs: dict | None = None,
+) -> go.Figure:
+    """Horizontal bar chart: PnL breakdown, Total PnL, and Vol/Capital by controller."""
+    # Sort by net PnL
+    sorted_ctrls = sorted(controllers, key=lambda c: c["net"] * to_usd)
+    names = [_short_chart_name(c["id"], c["pair"]) for c in sorted_ctrls]
+    realized = [c["realized"] * to_usd for c in sorted_ctrls]
+    unrealized = [c["unrealized"] * to_usd for c in sorted_ctrls]
+    rebates = [
+        (
+            c["vol"] * to_usd * REBATE_RATE
+            if _pair_has_rebate(c["pair"], quote_currency)
+            else 0
+        )
+        for c in sorted_ctrls
+    ]
+    totals = [r + u + rb for r, u, rb in zip(realized, unrealized, rebates)]
+    volumes = [_vol_to_usd(c, to_usd) for c in sorted_ctrls]
+
+    # Capital from configs (converted to USD)
+    has_capital = False
+    capitals = []
+    if ctrl_configs:
+        for c in sorted_ctrls:
+            cfg = ctrl_configs.get(c["id"], {})
+            amt = float(cfg.get("total_amount_quote", 0) or 0)
+            ctrl_for_conv = {"total_amount_quote": amt, "pair": c["pair"]}
+            capitals.append(_amount_quote_to_usd(ctrl_for_conv, to_usd))
+            if amt > 0:
+                has_capital = True
+
+    # Vol/Capital turnover ratio
+    vol_cap_ratios = []
+    if has_capital:
+        for v, cap in zip(volumes, capitals):
+            vol_cap_ratios.append(v / cap if cap > 0 else 0)
+
+    ncols = 3 if has_capital else 2
+    col_widths = [0.40, 0.30, 0.30] if has_capital else [0.55, 0.45]
+    subtitles = (
+        ["PnL Breakdown (USD)", "Total PnL (USD)", "Vol / Capital"]
+        if has_capital
+        else ["PnL Breakdown (USD)", "Total PnL (USD)"]
+    )
+
+    fig = make_subplots(
+        rows=1,
+        cols=ncols,
+        shared_yaxes=True,
+        column_widths=col_widths,
+        horizontal_spacing=0.03,
+        subplot_titles=subtitles,
+    )
+
+    # Col 1: PnL breakdown (stacked)
+    fig.add_trace(
+        go.Bar(
+            y=names,
+            x=realized,
+            orientation="h",
+            name="Realized",
+            marker_color=_GREEN,
+            opacity=0.85,
+        ),
+        row=1,
+        col=1,
+    )
+    fig.add_trace(
+        go.Bar(
+            y=names,
+            x=unrealized,
+            orientation="h",
+            name="Unrealized",
+            marker_color=_BLUE,
+            opacity=0.85,
+        ),
+        row=1,
+        col=1,
+    )
+    fig.add_trace(
+        go.Bar(
+            y=names,
+            x=rebates,
+            orientation="h",
+            name="Rebate",
+            marker_color=_YELLOW,
+            opacity=0.7,
+        ),
+        row=1,
+        col=1,
+    )
+
+    # Col 2: Total PnL (single bar per controller)
+    total_colors = [_GREEN if t >= 0 else _RED for t in totals]
+    fig.add_trace(
+        go.Bar(
+            y=names,
+            x=totals,
+            orientation="h",
+            name="Total",
+            marker_color=total_colors,
+            opacity=0.9,
+            text=[f"{'+'if t>=0 else ''}{t:.1f}" for t in totals],
+            textposition="inside",
+            textfont=dict(size=10, color="white"),
+            insidetextanchor="middle",
+            showlegend=False,
+        ),
+        row=1,
+        col=2,
+    )
+
+    # Col 3: Vol/Capital turnover
+    if has_capital:
+        fig.add_trace(
+            go.Bar(
+                y=names,
+                x=vol_cap_ratios,
+                orientation="h",
+                name="Vol/Capital",
+                marker_color="#8b5cf6",
+                opacity=0.85,
+                text=[f"{r:.0f}x" if r > 0 else "-" for r in vol_cap_ratios],
+                textposition="outside",
+                textfont=dict(size=10),
+                showlegend=False,
+            ),
+            row=1,
+            col=3,
+        )
+
+    height = max(350, len(names) * 40 + 100)
+    fig.update_layout(
+        **_chart_layout("PnL Breakdown · Total · Vol/Capital", height=height),
+        barmode="relative",
+        legend=dict(orientation="h", y=-0.12, x=0.5, xanchor="center"),
+    )
+    fig.update_xaxes(gridcolor="#2a2a4a", title="USD", row=1, col=1)
+    fig.update_xaxes(gridcolor="#2a2a4a", title="USD", row=1, col=2)
+    if has_capital:
+        fig.update_xaxes(gridcolor="#2a2a4a", title="Turnover (x)", row=1, col=3)
+    fig.update_yaxes(gridcolor="#2a2a4a", row=1, col=1)
+    # Fix subplot title colors
+    for ann in fig.layout.annotations:
+        ann.font = dict(color="#aaa", size=11)
+    return fig
+
+
+def _build_pair_overview_chart(
+    controllers: list[dict],
+    to_usd: float,
+    volumes_since: dict[str, tuple[float, float]],
+    prices: dict[str, float],
+    quote_currency: str = "BRL",
+) -> go.Figure:
+    """Unified horizontal bar chart: PnL, Volume, and Market Share by pair."""
+    # Aggregate data per pair
+    pair_data: dict[str, dict] = defaultdict(
+        lambda: {"realized": 0, "unrealized": 0, "vol": 0}
+    )
+    for c in controllers:
+        key = c["pair"] or "unknown"
+        pair_data[key]["realized"] += c["realized"] * to_usd
+        pair_data[key]["unrealized"] += c["unrealized"] * to_usd
+        pair_data[key]["vol"] += _vol_to_usd(c, to_usd)
+
+    # Sort pairs by total volume (highest at top)
+    pairs = sorted(pair_data.keys(), key=lambda p: pair_data[p]["vol"])
+
+    # Compute market share data
+    pair_market: dict[str, dict] = {}
+    for pair in pairs:
+        vol_data = volumes_since.get(pair, (0, 0))
+        vol_base, vol_quote = vol_data if isinstance(vol_data, tuple) else (vol_data, 0)
+        mkt_usd = (
+            _market_vol_to_usd(pair, vol_base, vol_quote, to_usd, prices)
+            if (vol_base > 0 or vol_quote > 0)
+            else 0
+        )
+        our_vol = pair_data[pair]["vol"]
+        share = (our_vol / mkt_usd * 100) if mkt_usd > 0 else 0
+        pair_market[pair] = {"market": mkt_usd, "ours": our_vol, "share": share}
+
+    has_market = any(d["market"] > 0 for d in pair_market.values())
+    ncols = 3 if has_market else 2
+    col_widths = [0.4, 0.35, 0.25] if has_market else [0.5, 0.5]
+    subtitles = (
+        ["PnL (USD)", "Volume (USD)", "Market Share"]
+        if has_market
+        else ["PnL (USD)", "Volume (USD)"]
+    )
+
+    fig = make_subplots(
+        rows=1,
+        cols=ncols,
+        shared_yaxes=True,
+        column_widths=col_widths,
+        horizontal_spacing=0.04,
+        subplot_titles=subtitles,
+    )
+
+    # Col 1: PnL (realized + unrealized + rebate)
+    fig.add_trace(
+        go.Bar(
+            y=pairs,
+            x=[pair_data[p]["realized"] for p in pairs],
+            orientation="h",
+            name="Realized",
+            marker_color=_GREEN,
+            opacity=0.85,
+        ),
+        row=1,
+        col=1,
+    )
+    fig.add_trace(
+        go.Bar(
+            y=pairs,
+            x=[pair_data[p]["unrealized"] for p in pairs],
+            orientation="h",
+            name="Unrealized",
+            marker_color=_BLUE,
+            opacity=0.85,
+        ),
+        row=1,
+        col=1,
+    )
+    fig.add_trace(
+        go.Bar(
+            y=pairs,
+            x=[
+                (
+                    pair_data[p]["vol"] * REBATE_RATE
+                    if _pair_has_rebate(p, quote_currency)
+                    else 0
+                )
+                for p in pairs
+            ],
+            orientation="h",
+            name="Rebate",
+            marker_color=_YELLOW,
+            opacity=0.7,
+        ),
+        row=1,
+        col=1,
+    )
+
+    # Col 2: Volume
+    fig.add_trace(
+        go.Bar(
+            y=pairs,
+            x=[pair_data[p]["vol"] for p in pairs],
+            orientation="h",
+            name="Volume",
+            marker_color="#8b5cf6",
+            opacity=0.8,
+        ),
+        row=1,
+        col=2,
+    )
+
+    # Col 3: Market Share as percentage bar
+    if has_market:
+        shares = [pair_market[p]["share"] for p in pairs]
+        fig.add_trace(
+            go.Bar(
+                y=pairs,
+                x=shares,
+                orientation="h",
+                name="Market Share",
+                marker_color=[_BLUE if s > 0 else "#30363d" for s in shares],
+                opacity=0.85,
+                text=[f"{s:.2f}%" if s > 0 else "N/A" for s in shares],
+                textposition="outside",
+                textfont=dict(size=11, color=_BLUE),
+                hovertemplate="%{y}<br>Share: %{x:.2f}%<br>"
+                "Ours: $%{customdata[0]:,.0f}<br>"
+                "Market: $%{customdata[1]:,.0f}<extra></extra>",
+                customdata=[
+                    [pair_market[p]["ours"], pair_market[p]["market"]] for p in pairs
+                ],
+            ),
+            row=1,
+            col=ncols,
+        )
+
+    height = max(350, len(pairs) * 55 + 120)
+    fig.update_layout(
+        **_chart_layout("Pair Overview: PnL · Volume · Market Share", height=height),
+        barmode="relative",
+        legend=dict(orientation="h", y=-0.12, x=0.5, xanchor="center"),
+    )
+    for col in range(1, ncols + 1):
+        fig.update_xaxes(gridcolor="#2a2a4a", row=1, col=col)
+    if has_market:
+        fig.update_xaxes(title="%", row=1, col=ncols)
+    fig.update_yaxes(gridcolor="#2a2a4a", row=1, col=1)
+    # Fix subplot title colors
+    for ann in fig.layout.annotations:
+        ann.font = dict(color="#aaa", size=11)
+    return fig
+
+
+# ---------------------------------------------------------------------------
+# Config analysis helpers
+# ---------------------------------------------------------------------------
+
+
+def _cfg_fmt_value(v) -> str:
+    if v is None:
+        return "—"
+    if isinstance(v, bool):
+        return "✓" if v else "✗"
+    if isinstance(v, float):
+        if v < 0.001:
+            return f"{v:.5f}"
+        if v < 0.01:
+            return f"{v:.4f}"
+        return f"{v:.3f}" if v < 10 else f"{v:.1f}"
+    if isinstance(v, list):
+        return ", ".join(_cfg_fmt_value(x) for x in v)
+    if isinstance(v, dict):
+        return " | ".join(f"{k}={_cfg_fmt_value(vv)}" for k, vv in v.items())
+    return str(v)
+
+
+def _cfg_normalize(v):
+    if v is None:
+        return None
+    if isinstance(v, str):
+        try:
+            return float(v)
+        except ValueError:
+            return v.strip().lower()
+    if isinstance(v, list):
+        return [_cfg_normalize(x) for x in v]
+    if isinstance(v, dict):
+        return {k: _cfg_normalize(vv) for k, vv in v.items()}
+    return v
+
+
+def _build_config_parallel_coords(
+    all_configs: dict, running_ids: set
+) -> go.Figure | None:
+    NUMERIC_AXES = [
+        ("total_amount_quote", "Capital", None),
+        (
+            "buy_spreads",
+            "Buy Spread L1 %",
+            lambda v: (v[0] if isinstance(v, list) and v else v) if v else None,
+        ),
+        (
+            "sell_spreads",
+            "Sell Spread L1 %",
+            lambda v: (v[0] if isinstance(v, list) and v else v) if v else None,
+        ),
+        (
+            "buy_spreads",
+            "Buy Spread L2 %",
+            lambda v: (
+                (v[1] if isinstance(v, list) and len(v) > 1 else None) if v else None
+            ),
+        ),
+        (
+            "sell_spreads",
+            "Sell Spread L2 %",
+            lambda v: (
+                (v[1] if isinstance(v, list) and len(v) > 1 else None) if v else None
+            ),
+        ),
+        ("executor_refresh_time", "Refresh Time", None),
+        ("cooldown_time", "Cooldown", None),
+        ("leverage", "Leverage", None),
+        ("stop_loss", "Stop Loss", None),
+        ("take_profit", "Take Profit", None),
+        ("time_limit", "Time Limit", None),
+        ("top_executor_refresh_time", "Top Refresh", None),
+        (
+            "dca_spreads",
+            "DCA Spread L1",
+            lambda v: (v[0] if isinstance(v, list) and v else v) if v else None,
+        ),
+        (
+            "dca_amounts",
+            "DCA Amt L1",
+            lambda v: (v[0] if isinstance(v, list) and v else v) if v else None,
+        ),
+        (
+            "trailing_stop",
+            "Trail Stop",
+            lambda v: (
+                (v.get("activation_price_delta") if isinstance(v, dict) else v)
+                if v
+                else None
+            ),
+        ),
+        (
+            "executor_activation_bounds",
+            "Activation Bounds",
+            lambda v: (v[0] if isinstance(v, list) and v else v) if v else None,
+        ),
+    ]
+
+    rows = []
+    labels = []
+    for label, cfg in all_configs.items():
+        clean_label = label.replace("\U0001f7e2 ", "").replace("\U0001f535 ", "")
+        is_running = clean_label in running_ids or label.startswith("\U0001f7e2")
+        pair = cfg.get("trading_pair", "unknown")
+        row = {"_running": 1 if is_running else 0, "_pair": pair}
+        for param, axis_name, extractor in NUMERIC_AXES:
+            raw = cfg.get(param)
+            val = extractor(raw) if extractor else raw
+            try:
+                row[axis_name] = float(val) if val is not None else None
+            except (TypeError, ValueError):
+                row[axis_name] = None
+        rows.append(row)
+        labels.append(_short_chart_name(clean_label, pair))
+
+    if len(rows) < 2:
+        return None
+
+    valid_axes = []
+    for _, axis_name, _ in NUMERIC_AXES:
+        vals = [r[axis_name] for r in rows if r[axis_name] is not None]
+        if len(vals) >= 2 and len(set(vals)) > 1:
+            valid_axes.append(axis_name)
+
+    if len(valid_axes) < 2:
+        return None
+
+    unique_pairs = sorted(set(r["_pair"] for r in rows))
+    pair_to_idx = {p: i for i, p in enumerate(unique_pairs)}
+    color_values = [pair_to_idx[r["_pair"]] for r in rows]
+
+    n_pairs = len(unique_pairs)
+    if n_pairs == 1:
+        colorscale = [[0, _BLUE], [1, _BLUE]]
+    else:
+        colorscale = [
+            [i / (n_pairs - 1), _COLORS[i % len(_COLORS)]] for i in range(n_pairs)
+        ]
+
+    for axis_name in valid_axes:
+        vals = [r[axis_name] for r in rows if r[axis_name] is not None]
+        fill = min(vals) if vals else 0
+        for r in rows:
+            if r[axis_name] is None:
+                r[axis_name] = fill
+
+    dimensions = []
+    for axis_name in valid_axes:
+        vals = [r[axis_name] for r in rows]
+        if "%" in axis_name:
+            vals = [v * 100 for v in vals]
+        dimensions.append(
+            dict(
+                label=axis_name,
+                values=vals,
+                range=(
+                    [min(vals), max(vals)]
+                    if min(vals) != max(vals)
+                    else [min(vals) - 1, max(vals) + 1]
+                ),
+            )
+        )
+
+    fig = go.Figure(
+        data=go.Parcoords(
+            line=dict(color=color_values, colorscale=colorscale, showscale=False),
+            dimensions=dimensions,
+            customdata=labels,
+        )
+    )
+    for i, pair in enumerate(unique_pairs):
+        fig.add_trace(
+            go.Scatter(
+                x=[None],
+                y=[None],
+                mode="markers",
+                marker=dict(size=10, color=_COLORS[i % len(_COLORS)]),
+                name=pair,
+                showlegend=True,
+            )
+        )
+    fig.update_layout(
+        **_chart_layout(
+            f"Config Parameter Space ({len(rows)} configs, {len(valid_axes)} axes)",
+            width=1400,
+            height=600,
+        ),
+        legend=dict(
+            orientation="h", y=-0.05, x=0.5, xanchor="center", font=dict(size=12)
+        ),
+    )
+    return fig
+
+
+def _build_config_spread_chart(all_configs: dict) -> go.Figure | None:
+    def _to_list(v) -> list:
+        if v is None:
+            return []
+        if isinstance(v, (int, float)):
+            return [float(v)]
+        if isinstance(v, list):
+            return [float(x) for x in v]
+        return []
+
+    items = []
+    for label, cfg in all_configs.items():
+        buy = _to_list(cfg.get("buy_spreads"))
+        sell = _to_list(cfg.get("sell_spreads"))
+        if buy or sell:
+            short = _short_chart_name(
+                label.replace("\U0001f7e2 ", "").replace("\U0001f535 ", ""),
+                cfg.get("trading_pair", ""),
+            )
+            items.append(
+                {
+                    "name": short,
+                    "pair": cfg.get("trading_pair", ""),
+                    "buy_l1": buy[0] * 100 if len(buy) >= 1 else 0,
+                    "sell_l1": sell[0] * 100 if len(sell) >= 1 else 0,
+                    "buy_l2": buy[1] * 100 if len(buy) >= 2 else 0,
+                    "sell_l2": sell[1] * 100 if len(sell) >= 2 else 0,
+                }
+            )
+
+    if not items:
+        return None
+
+    items.sort(key=lambda c: (c["pair"], c["name"]))
+    names = [c["name"] for c in items]
+
+    fig = go.Figure()
+    fig.add_trace(
+        go.Bar(
+            x=names,
+            y=[c["buy_l1"] for c in items],
+            name="Buy L1",
+            marker_color=_GREEN,
+            opacity=0.9,
+        )
+    )
+    fig.add_trace(
+        go.Bar(
+            x=names,
+            y=[c["sell_l1"] for c in items],
+            name="Sell L1",
+            marker_color=_RED,
+            opacity=0.9,
+        )
+    )
+    if any(c["buy_l2"] > 0 or c["sell_l2"] > 0 for c in items):
+        fig.add_trace(
+            go.Bar(
+                x=names,
+                y=[c["buy_l2"] for c in items],
+                name="Buy L2",
+                marker_color=_GREEN,
+                opacity=0.5,
+            )
+        )
+        fig.add_trace(
+            go.Bar(
+                x=names,
+                y=[c["sell_l2"] for c in items],
+                name="Sell L2",
+                marker_color=_RED,
+                opacity=0.5,
+            )
+        )
+
+    fig.update_layout(
+        **_chart_layout("Spread Levels by Controller (%)", width=1200, height=500),
+        barmode="group",
+        yaxis=dict(gridcolor="#2a2a4a", title="Spread %"),
+        xaxis=dict(gridcolor="#2a2a4a", tickangle=-45),
+        legend=dict(orientation="h", y=1.1, x=0.5, xanchor="center"),
+    )
+    fig.update_layout(margin=dict(l=60, r=40, t=60, b=120))
+    return fig
+
+
+def _build_config_capital_chart(all_configs: dict) -> go.Figure | None:
+    data = []
+    for label, cfg in all_configs.items():
+        amt = float(cfg.get("total_amount_quote", 0) or 0)
+        if amt <= 0:
+            continue
+        short = _short_chart_name(
+            label.replace("\U0001f7e2 ", "").replace("\U0001f535 ", ""),
+            cfg.get("trading_pair", ""),
+        )
+        data.append({"name": short, "pair": cfg.get("trading_pair", ""), "amount": amt})
+
+    if not data:
+        return None
+
+    data.sort(key=lambda d: (d["pair"], d["amount"]))
+    unique_pairs = list(dict.fromkeys(d["pair"] for d in data))
+    pair_colors = {p: _COLORS[i % len(_COLORS)] for i, p in enumerate(unique_pairs)}
+
+    fig = go.Figure()
+    for pair in unique_pairs:
+        pair_data = [d for d in data if d["pair"] == pair]
+        fig.add_trace(
+            go.Bar(
+                y=[d["name"] for d in pair_data],
+                x=[d["amount"] for d in pair_data],
+                orientation="h",
+                name=pair,
+                marker_color=pair_colors[pair],
+                opacity=0.85,
+                text=[f"{d['amount']:,.0f}" for d in pair_data],
+                textposition="auto",
+            )
+        )
+
+    height = max(400, len(data) * 22 + 100)
+    fig.update_layout(
+        **_chart_layout(
+            "Capital Allocation by Controller (quote)", width=1200, height=height
+        ),
+        barmode="stack",
+        xaxis=dict(gridcolor="#2a2a4a", title="Amount (quote)"),
+        yaxis=dict(gridcolor="#2a2a4a"),
+        legend=dict(orientation="h", y=1.05, x=0.5, xanchor="center"),
+    )
+    fig.update_layout(margin=dict(l=150, r=40, t=60, b=50))
+    return fig
+
+
+# ---------------------------------------------------------------------------
+# Report builder
+# ---------------------------------------------------------------------------
+
+
+def _build_report(
+    bots_data: dict,
+    bot_runs: dict,
+    prices: dict[str, float],
+    volumes_since: dict[str, tuple[float, float]],
+    quote_usd_rate: float,
+    quote_currency: str = "BRL",
+    ctrl_configs: dict | None = None,
+    balances: dict | None = None,
+) -> list[str]:
+    ctrl_configs = ctrl_configs or {}
+
+    # ---- Parse controller data ----
+    controllers = []
+
+    for bot_name, bot_data in bots_data.items():
+        if isinstance(bot_data, str):
+            continue
+
+        performance = {}
+        if isinstance(bot_data, dict):
+            performance = bot_data.get("performance", {})
+        elif isinstance(bot_data, list):
+            performance = {
+                f"ctrl_{i}": {"performance": c} for i, c in enumerate(bot_data)
+            }
+
+        for ctrl_name, ctrl_data in performance.items():
+            if not isinstance(ctrl_data, dict):
+                continue
+            perf = ctrl_data.get("performance", ctrl_data)
+            cfg = ctrl_configs.get(ctrl_name, {})
+            trading_pair = cfg.get("trading_pair", "") or perf.get("trading_pair", "")
+
+            vol = float(perf.get("volume_traded", 0) or 0)
+            realized = float(perf.get("realized_pnl_quote", 0) or 0)
+            unrealized = float(perf.get("unrealized_pnl_quote", 0) or 0)
+            total_amount_quote = float(cfg.get("total_amount_quote", 0) or 0)
+
+            controllers.append(
+                {
+                    "id": ctrl_name,
+                    "bot": bot_name,
+                    "pair": trading_pair,
+                    "vol": vol,
+                    "realized": realized,
+                    "unrealized": unrealized,
+                    "net": realized + unrealized,
+                    "total_amount_quote": total_amount_quote,
+                }
+            )
+
+    if not controllers:
+        return ["No controller data found\\."]
+
+    # ---- Runtime ----
+    earliest_dt = None
+    for bn in {c["bot"] for c in controllers}:
+        ts = bot_runs.get(bn)
+        if ts:
+            try:
+                ts_str = str(ts)
+                if ts_str.endswith("Z"):
+                    ts_str = ts_str[:-1] + "+00:00"
+                dt = datetime.fromisoformat(ts_str)
+                if earliest_dt is None or dt < earliest_dt:
+                    earliest_dt = dt
+            except (ValueError, TypeError):
+                pass
+
+    now_dt = datetime.now(timezone.utc)
+    runtime_h = (now_dt - earliest_dt).total_seconds() / 3600 if earliest_dt else 0
+    if earliest_dt:
+        start_str = earliest_dt.strftime("%b %d, %H:%M UTC")
+    else:
+        start_str = "N/A"
+
+    # ---- Totals ----
+    total_vol_q = sum(c["vol"] for c in controllers)
+    total_realized_q = sum(c["realized"] for c in controllers)
+    total_unrealized_q = sum(c["unrealized"] for c in controllers)
+    total_net_q = total_realized_q + total_unrealized_q
+
+    to_usd = quote_usd_rate
+    total_vol = sum(_vol_to_usd(c, to_usd) for c in controllers)
+    total_realized = total_realized_q * to_usd
+    total_unrealized = total_unrealized_q * to_usd
+    total_net = total_net_q * to_usd
+    total_rebate_vol = sum(
+        _vol_to_usd(c, to_usd)
+        for c in controllers
+        if _pair_has_rebate(c["pair"], quote_currency)
+    )
+    total_rebate = total_rebate_vol * REBATE_RATE
+
+    vol_hr = total_vol / runtime_h if runtime_h > 0 else 0
+    realized_hr = total_realized / runtime_h if runtime_h > 0 else 0
+    rebate_hr = total_rebate / runtime_h if runtime_h > 0 else 0
+    net_after_rebate = total_net + total_rebate
+
+    # ---- Market volumes ----
+    unique_pairs = {c["pair"] for c in controllers if c["pair"]}
+    market_lines = []
+    for pair in sorted(unique_pairs):
+        vol_data = volumes_since.get(pair, (0, 0))
+        vol_24h_base, vol_24h_quote = (
+            vol_data if isinstance(vol_data, tuple) else (vol_data, 0)
+        )
+        if vol_24h_base <= 0 and vol_24h_quote <= 0:
+            continue
+        mkt_usd = _market_vol_to_usd(pair, vol_24h_base, vol_24h_quote, to_usd, prices)
+        our_vol = sum(_vol_to_usd(c, to_usd) for c in controllers if c["pair"] == pair)
+        share = (our_vol / mkt_usd * 100) if mkt_usd > 0 else 0
+        market_lines.append(
+            f"  {_md_escape(pair)}: mkt \\${_md_escape(_fmt(mkt_usd))} "
+            f"\\| ours \\${_md_escape(_fmt(our_vol))} \\({_md_escape(f'{share:.2f}')}%\\)"
+        )
+
+    # ---- FX rate display ----
+    qc = quote_currency.upper()
+    if qc not in ("USD", "USDT"):
+        fx_val = _fmt(1 / to_usd if to_usd > 0 else 0)
+        fx_display = f"1 USD \\= {_md_escape(fx_val)} {_md_escape(qc)}"
+    else:
+        fx_display = ""
+
+    # ---- MSG 1: Overview ----
+    num_bots = len({c["bot"] for c in controllers})
+    num_ctrls = len(controllers)
+
+    # ---- Balance summary ----
+    balance_lines = []
+    total_balance_usd = 0.0
+    if balances:
+        token_totals: dict[str, float] = defaultdict(float)
+        token_values: dict[str, float] = defaultdict(float)
+        for account_data in balances.values():
+            for connector_balances in account_data.values():
+                if not isinstance(connector_balances, list):
+                    continue
+                for b in connector_balances:
+                    token = b.get("token", "")
+                    value = float(b.get("value", 0) or 0)
+                    units = float(b.get("units", 0) or 0)
+                    if value > 0:
+                        token_totals[token] += units
+                        token_values[token] += value
+        total_balance_usd = sum(token_values.values())
+        # Top tokens by value
+        sorted_tokens = sorted(token_values.items(), key=lambda x: x[1], reverse=True)
+        for token, value in sorted_tokens[:5]:
+            pct = (value / total_balance_usd * 100) if total_balance_usd > 0 else 0
+            balance_lines.append(
+                f"  {_md_escape(token)}: \\${_md_escape(_fmt(value))} \\({_md_escape(f'{pct:.0f}')}%\\)"
+            )
+
+    msg1_parts = [
+        f"*📊 TRADING REPORT*",
+        f"━━━━━━━━━━━━━━━━━━━━━━━━",
+        f"",
+        f"⏱ {_md_escape(f'{runtime_h:.1f}')}h runtime \\(since {_md_escape(start_str)}\\)",
+        f"🤖 {num_bots} bots \\| {num_ctrls} controllers",
+    ]
+    if fx_display:
+        msg1_parts.append(f"💱 {fx_display}")
+
+    if balance_lines:
+        msg1_parts += [
+            f"",
+            f"💰 *Balance: \\${_md_escape(_fmt(total_balance_usd))}*",
+        ] + balance_lines
+
+    msg1_parts += [
+        f"",
+        f"{_emoji(total_net)} *Performance \\(USD\\)*",
+        f"Volume: \\${_md_escape(_fmt(total_vol))}",
+        f"Realized: {_md_escape(_sign(total_realized))}\\${_md_escape(_fmt(abs(total_realized)))}",
+        f"Unrealized: {_md_escape(_sign(total_unrealized))}\\${_md_escape(_fmt(abs(total_unrealized)))}",
+        f"Net PnL: {_md_escape(_sign(total_net))}\\${_md_escape(_fmt(abs(total_net)))}",
+        f"Rebate: \\+\\${_md_escape(_fmt(total_rebate))}",
+        f"Net\\+Rebate: {_md_escape(_sign(net_after_rebate))}\\${_md_escape(_fmt(abs(net_after_rebate)))}",
+        f"",
+        f"⏳ *Hourly Rates*",
+        f"Vol/hr: \\${_md_escape(_fmt(vol_hr))}",
+        f"Realized/hr: {_md_escape(_sign(realized_hr))}\\${_md_escape(_fmt(abs(realized_hr)))}",
+        f"Rebate/hr: \\+\\${_md_escape(_fmt(rebate_hr))}",
+    ]
+
+    if market_lines:
+        msg1_parts += [f"", f"📈 *Market Share*"] + market_lines
+
+    # ---- MSG 2: Controllers grouped by pair ----
+    msg2_parts = [
+        f"*📋 CONTROLLERS BY PAIR*",
+        f"━━━━━━━━━━━━━━━━━━━━━━━━",
+    ]
+
+    pair_groups: dict[str, list[dict]] = defaultdict(list)
+    for c in controllers:
+        pair_groups[c["pair"] or "unknown"].append(c)
+
+    sorted_pairs = sorted(
+        pair_groups.items(), key=lambda x: sum(c["vol"] for c in x[1]), reverse=True
+    )
+
+    for pair, ctrls in sorted_pairs:
+        grp_vol = sum(_vol_to_usd(c, to_usd) for c in ctrls)
+        grp_realized = sum(c["realized"] for c in ctrls) * to_usd
+        grp_unrealized = sum(c["unrealized"] for c in ctrls) * to_usd
+        grp_net = grp_realized + grp_unrealized
+        grp_rebate = (
+            grp_vol * REBATE_RATE if _pair_has_rebate(pair, quote_currency) else 0
+        )
+        grp_adj = grp_net + grp_rebate
+
+        pair_escaped = _md_escape(pair)
+        msg2_parts.append(f"")
+        msg2_parts.append(
+            f"▸ *{pair_escaped}* \\({len(ctrls)} ctrls\\) "
+            f"{_emoji(grp_adj)} {_md_escape(_sign(grp_adj))}\\${_md_escape(_fmt(abs(grp_adj)))}"
+        )
+
+        # Build controller table rows
+        sorted_ctrls = sorted(ctrls, key=lambda c: c["vol"], reverse=True)
+
+        def _short_name(ctrl_id: str, pair: str) -> str:
+            name = ctrl_id
+            if name.startswith("mm_"):
+                name = name[3:]
+            # Strip all variations of pmm_mister prefix
+            name = re.sub(r"pmm_?mister_?", "", name)
+            pair_frag = pair.replace("-", "_") if pair else ""
+            if pair_frag:
+                name = name.replace(pair_frag, "").replace(pair, "")
+            while "__" in name:
+                name = name.replace("__", "_")
+            name = name.strip("_")
+            name = re.sub(r"config[_]?(\d+)", r"c\1", name)
+            return name or ctrl_id[:20]
+
+        rows = []
+        for c in sorted_ctrls:
+            vol_usd = _vol_to_usd(c, to_usd)
+            net_usd = c["net"] * to_usd
+            reb_usd = (
+                vol_usd * REBATE_RATE if _pair_has_rebate(pair, quote_currency) else 0
+            )
+            adj_usd = net_usd + reb_usd
+            short = _short_name(c["id"], pair)
+            rows.append((short, vol_usd, net_usd, adj_usd))
+
+        # Calculate column widths
+        name_w = max(len(r[0]) for r in rows)
+        vol_strs = [f"${_fmt(r[1])}" for r in rows]
+        pnl_strs = [f"{_sign(r[2])}${_fmt(abs(r[2]))}" for r in rows]
+        adj_strs = [f"{_sign(r[3])}${_fmt(abs(r[3]))}" for r in rows]
+
+        vol_w = max(len(s) for s in vol_strs)
+        pnl_w = max(len(s) for s in pnl_strs)
+        adj_w = max(len(s) for s in adj_strs)
+
+        # Header + separator + rows inside a code block
+        hdr = (
+            f"{'Name':<{name_w}}  {'Vol':>{vol_w}}  {'PnL':>{pnl_w}}  {'Adj':>{adj_w}}"
+        )
+        sep = "─" * len(hdr)
+
+        table_lines = [hdr, sep]
+        for i, (short, vol_usd, net_usd, adj_usd) in enumerate(rows):
+            e = "+" if adj_usd >= 0 else "-"
+            table_lines.append(
+                f"{short:<{name_w}}  {vol_strs[i]:>{vol_w}}  {pnl_strs[i]:>{pnl_w}}  {adj_strs[i]:>{adj_w}}"
+            )
+
+        # Pair subtotal row
+        sub_vol = f"${_fmt(grp_vol)}"
+        sub_pnl = f"{_sign(grp_net)}${_fmt(abs(grp_net))}"
+        sub_adj = f"{_sign(grp_adj)}${_fmt(abs(grp_adj))}"
+        table_lines.append(sep)
+        table_lines.append(
+            f"{'TOTAL':<{name_w}}  {sub_vol:>{vol_w}}  {sub_pnl:>{pnl_w}}  {sub_adj:>{adj_w}}"
+        )
+
+        msg2_parts.append("```")
+        msg2_parts.extend(table_lines)
+        msg2_parts.append("```")
+
+    return ["\n".join(msg1_parts), "\n".join(msg2_parts)]
+
+
+# ---------------------------------------------------------------------------
+# Telegram HTTP fallback (when context.bot is unavailable)
+# ---------------------------------------------------------------------------
+
+
+async def _send_telegram_http(
+    chat_id: int, text: str, parse_mode: str = "MarkdownV2"
+) -> bool:
+    """Send a message via Telegram HTTP API directly. Used as fallback."""
+    token = os.environ.get("TELEGRAM_BOT_TOKEN", "")
+    if not token:
+        logger.error("TELEGRAM_BOT_TOKEN not set, cannot send via HTTP fallback")
+        return False
+    try:
+        import httpx
+
+        url = f"https://api.telegram.org/bot{token}/sendMessage"
+        payload = {"chat_id": chat_id, "text": text, "parse_mode": parse_mode}
+        async with httpx.AsyncClient(timeout=10) as http_client:
+            resp = await http_client.post(url, json=payload)
+            data = resp.json()
+            if data.get("ok"):
+                return True
+            # Retry without parse_mode if formatting fails
+            if "can't parse" in data.get("description", "").lower():
+                payload.pop("parse_mode")
+                resp = await http_client.post(url, json=payload)
+                data = resp.json()
+                if data.get("ok"):
+                    return True
+            logger.error(f"Telegram HTTP send failed: {data.get('description')}")
+    except Exception as e:
+        logger.error(f"Telegram HTTP fallback error: {e}")
+    return False
+
+
+# ---------------------------------------------------------------------------
+# Main entry point
+# ---------------------------------------------------------------------------
+
+
+async def run(config: Config, context: ContextTypes.DEFAULT_TYPE) -> str:
+    chat_id = context._chat_id if hasattr(context, "_chat_id") else None
+    if not chat_id:
+        return "No chat_id available"
+
+    # Auto-resolve target_chat_id from notes if not explicitly set
+    send_to = config.target_chat_id
+    if not send_to:
+        try:
+            from condor.preferences import get_note
+
+            user_data = context.user_data if hasattr(context, "user_data") else {}
+            # Look up note for the active server's group chat
+            server_name = (
+                config.server_name
+                or get_config_manager().get_chat_default_server(chat_id)
+            )
+            if server_name:
+                note_val = get_note(user_data, f"server.{server_name}.group_chat_id")
+                if note_val:
+                    send_to = int(note_val)
+        except Exception:
+            pass
+    if not send_to:
+        # Fallback to CONDOR_CHAT_ID env var (the invoking user's chat)
+        env_chat = os.environ.get("CONDOR_CHAT_ID", "")
+        send_to = int(env_chat) if env_chat else chat_id
+
+    # Connect to the specified server (default: brigado_2 where bots run)
+    if config.server_name:
+        client = await get_config_manager().get_client(config.server_name)
+    else:
+        client = await get_client(chat_id, context=context)
+    if not client:
+        return "Could not connect to API server"
+
+    bots_data, bot_runs, balances = await asyncio.gather(
+        _get_bots_data(client),
+        _get_bot_runs(client),
+        _get_balances(client),
+    )
+
+    if not bots_data:
+        await context.bot.send_message(chat_id=send_to, text="No active bots found.")
+        return "No active bots"
+
+    # Fetch controller configs for trading_pair
+    ctrl_configs = {}
+    for bot_name in bots_data:
+        try:
+            configs = await client.controllers.get_bot_controller_configs(bot_name)
+            if isinstance(configs, list):
+                for cfg in configs:
+                    cid = cfg.get("id") or cfg.get("controller_id", "")
+                    if cid:
+                        ctrl_configs[cid] = cfg
+        except Exception:
+            pass
+
+    # Determine trading pairs and connector
+    trading_pairs = set()
+    connector = "binance"
+    for bot_data in bots_data.values():
+        if not isinstance(bot_data, dict):
+            continue
+        for ctrl_name, ctrl_data in bot_data.get("performance", {}).items():
+            if not isinstance(ctrl_data, dict):
+                continue
+            cfg = ctrl_configs.get(ctrl_name, {})
+            perf = ctrl_data.get("performance", ctrl_data)
+            pair = cfg.get("trading_pair", "") or perf.get("trading_pair", "")
+            if pair:
+                trading_pairs.add(pair)
+            conn = cfg.get("connector_name", "") or perf.get("connector_name", "")
+            if conn:
+                connector = conn.split("_")[0]
+
+    # Build price pairs for USD conversion
+    price_pairs = list(trading_pairs)
+    for bt in {p.split("-")[0] for p in trading_pairs if "-" in p}:
+        if f"{bt}-USDT" not in price_pairs:
+            price_pairs.append(f"{bt}-USDT")
+    for qt in {p.split("-")[-1] for p in trading_pairs if "-" in p}:
+        if qt not in ("USDT", "USD") and f"USDT-{qt}" not in price_pairs:
+            price_pairs.append(f"USDT-{qt}")
+
+    prices = await _get_prices(client, connector, price_pairs)
+
+    # FX rate fallback
+    qc = config.quote_currency.upper()
+    fx_pair = f"USDT-{qc}" if qc not in ("USD", "USDT") else ""
+    if fx_pair and not prices.get(fx_pair):
+        fx_prices = await _get_prices(client, "binance", [fx_pair])
+        prices.update(fx_prices)
+
+    # Market volumes since deploy
+    earliest_dt = None
+    for bn in bots_data:
+        ts = bot_runs.get(bn)
+        if ts:
+            try:
+                ts_str = str(ts)
+                if ts_str.endswith("Z"):
+                    ts_str = ts_str[:-1] + "+00:00"
+                dt = datetime.fromisoformat(ts_str)
+                if earliest_dt is None or dt < earliest_dt:
+                    earliest_dt = dt
+            except (ValueError, TypeError):
+                pass
+
+    volumes_since = {}
+    vol_tasks = {
+        pair: _get_market_volume_since(client, connector, pair, earliest_dt)
+        for pair in trading_pairs
+    }
+    vol_results = await asyncio.gather(*vol_tasks.values())
+    for pair, vol_tuple in zip(vol_tasks.keys(), vol_results):
+        volumes_since[pair] = vol_tuple
+
+    # Quote → USD rate
+    quote_usd_rate = 1.0
+    if qc not in ("USD", "USDT"):
+        usdt_quote = prices.get(f"USDT-{qc}", 0)
+        if usdt_quote and usdt_quote > 0:
+            quote_usd_rate = 1.0 / usdt_quote
+        else:
+            quote_usdt = prices.get(f"{qc}-USDT", 0)
+            if quote_usdt and quote_usdt > 0:
+                quote_usd_rate = quote_usdt
+
+    # Build and send
+    messages = _build_report(
+        bots_data,
+        bot_runs,
+        prices,
+        volumes_since,
+        quote_usd_rate,
+        quote_currency=qc,
+        ctrl_configs=ctrl_configs,
+        balances=balances,
+    )
+
+    sent = 0
+    for i, msg in enumerate(messages):
+        if i > 0:
+            await asyncio.sleep(1)
+        for attempt in range(3):
+            try:
+                await context.bot.send_message(
+                    chat_id=send_to,
+                    text=msg,
+                    parse_mode="MarkdownV2",
+                )
+                sent += 1
+                break
+            except Exception as e:
+                err = str(e).lower()
+                if "flood control" in err or "retry in" in err:
+                    match = re.search(r"retry in (\d+)", err)
+                    wait = int(match.group(1)) + 1 if match else 10
+                    await asyncio.sleep(wait)
+                else:
+                    logger.error(f"Failed to send msg {i} via bot: {e}")
+                    # Fallback: send via HTTP directly to Telegram API
+                    if await _send_telegram_http(send_to, msg):
+                        sent += 1
+                    break
+
+    # Strip MarkdownV2 escaping for plain-text return
+    def _strip_md(text: str) -> str:
+        return text.replace("\\", "")
+
+    plain_report = "\n\n".join(_strip_md(m) for m in messages)
+
+    from condor.reports import ReportBuilder
+
+    builder = ReportBuilder("Trading Report")
+    builder.source("routine", "bot_report").tags(["bots", "performance"])
+    builder.manual_order()
+
+    # ---- Parse controller data for charts ----
+    controllers_parsed = []
+    for bot_name, bot_data in bots_data.items():
+        if isinstance(bot_data, str):
+            continue
+        performance = {}
+        if isinstance(bot_data, dict):
+            performance = bot_data.get("performance", {})
+        elif isinstance(bot_data, list):
+            performance = {
+                f"ctrl_{i}": {"performance": c} for i, c in enumerate(bot_data)
+            }
+        for ctrl_name, ctrl_data in performance.items():
+            if not isinstance(ctrl_data, dict):
+                continue
+            perf = ctrl_data.get("performance", ctrl_data)
+            cfg = ctrl_configs.get(ctrl_name, {})
+            trading_pair = cfg.get("trading_pair", "") or perf.get("trading_pair", "")
+            vol = float(perf.get("volume_traded", 0) or 0)
+            realized = float(perf.get("realized_pnl_quote", 0) or 0)
+            unrealized = float(perf.get("unrealized_pnl_quote", 0) or 0)
+            total_amount_quote = float(cfg.get("total_amount_quote", 0) or 0)
+            controllers_parsed.append(
+                {
+                    "id": ctrl_name,
+                    "bot": bot_name,
+                    "pair": trading_pair,
+                    "vol": vol,
+                    "realized": realized,
+                    "unrealized": unrealized,
+                    "net": realized + unrealized,
+                    "total_amount_quote": total_amount_quote,
+                }
+            )
+
+    # ---- Compute totals for KPIs ----
+    total_vol_usd = sum(_vol_to_usd(c, quote_usd_rate) for c in controllers_parsed)
+    total_realized_usd = sum(c["realized"] for c in controllers_parsed) * quote_usd_rate
+    total_unrealized_usd = (
+        sum(c["unrealized"] for c in controllers_parsed) * quote_usd_rate
+    )
+    total_net_usd = total_realized_usd + total_unrealized_usd
+    rebate_vol_usd = sum(
+        _vol_to_usd(c, quote_usd_rate)
+        for c in controllers_parsed
+        if _pair_has_rebate(c["pair"], qc)
+    )
+    total_rebate_usd = rebate_vol_usd * REBATE_RATE
+    net_after_rebate_usd = total_net_usd + total_rebate_usd
+    num_bots = len({c["bot"] for c in controllers_parsed})
+    num_ctrls = len(controllers_parsed)
+
+    # Runtime
+    earliest_deploy = None
+    for bn in {c["bot"] for c in controllers_parsed}:
+        ts = bot_runs.get(bn)
+        if ts:
+            try:
+                ts_str = str(ts)
+                if ts_str.endswith("Z"):
+                    ts_str = ts_str[:-1] + "+00:00"
+                dt = datetime.fromisoformat(ts_str)
+                if earliest_deploy is None or dt < earliest_deploy:
+                    earliest_deploy = dt
+            except (ValueError, TypeError):
+                pass
+    now_utc = datetime.now(timezone.utc)
+    runtime_h = (
+        (now_utc - earliest_deploy).total_seconds() / 3600 if earliest_deploy else 0
+    )
+
+    # Balance
+    total_balance_usd = 0.0
+    if balances:
+        for account_data in balances.values():
+            for connector_balances in account_data.values():
+                if not isinstance(connector_balances, list):
+                    continue
+                for b in connector_balances:
+                    total_balance_usd += float(b.get("value", 0) or 0)
+
+    # ---- KPI cards ----
+    pnl_trend = "up" if net_after_rebate_usd >= 0 else "down"
+    builder.kpi(
+        "Net PnL + Rebate",
+        f"{'+'if net_after_rebate_usd>=0 else ''}${_fmt(abs(net_after_rebate_usd))}",
+        delta=f"${_fmt(abs(net_after_rebate_usd / runtime_h) if runtime_h else 0)}/hr",
+        trend=pnl_trend,
+    )
+    total_capital_usd = sum(
+        _amount_quote_to_usd(c, quote_usd_rate) for c in controllers_parsed
+    )
+    builder.kpi(
+        "Volume",
+        f"${_fmt(total_vol_usd)}",
+        delta=f"${_fmt(total_vol_usd / runtime_h if runtime_h else 0)}/hr",
+    )
+    builder.kpi(
+        "Rebate",
+        f"${_fmt(total_rebate_usd)}",
+        delta=f"${_fmt(total_rebate_usd / runtime_h if runtime_h else 0)}/hr",
+        trend="up",
+    )
+    if total_capital_usd > 0:
+        builder.kpi(
+            "Capital Deployed",
+            f"${_fmt(total_capital_usd)}",
+            delta=f"{num_ctrls} controllers",
+        )
+    builder.kpi("Balance", f"${_fmt(total_balance_usd)}")
+    builder.kpi(
+        "Runtime",
+        f"{runtime_h:.1f}h",
+        delta=f"{num_bots} bots, {num_ctrls} controllers",
+    )
+
+    # ---- Charts ----
+    if controllers_parsed:
+        builder.plotly(
+            _build_pair_overview_chart(
+                controllers_parsed, quote_usd_rate, volumes_since, prices, qc
+            )
+        )
+        builder.plotly(
+            _build_pnl_chart(controllers_parsed, quote_usd_rate, qc, ctrl_configs)
+        )
+
+    # ---- Controller details table ----
+    ctrl_rows = []
+    for c in sorted(
+        controllers_parsed, key=lambda x: x["net"] * quote_usd_rate, reverse=True
+    ):
+        vol_usd = _vol_to_usd(c, quote_usd_rate)
+        net_usd = c["net"] * quote_usd_rate
+        reb_usd = vol_usd * REBATE_RATE if _pair_has_rebate(c["pair"], qc) else 0
+        adj_usd = net_usd + reb_usd
+        cap_usd = _amount_quote_to_usd(c, quote_usd_rate)
+        ctrl_rows.append(
+            {
+                "Controller": _short_chart_name(c["id"], c["pair"]),
+                "Pair": c["pair"],
+                "Capital": f"${_fmt(cap_usd)}" if cap_usd > 0 else "-",
+                "Volume": f"${_fmt(vol_usd)}",
+                "Realized": f"{'+'if c['realized']*quote_usd_rate>=0 else '-'}${_fmt(abs(c['realized']*quote_usd_rate))}",
+                "Unrealized": f"{'+'if c['unrealized']*quote_usd_rate>=0 else '-'}${_fmt(abs(c['unrealized']*quote_usd_rate))}",
+                "Rebate": f"+${_fmt(reb_usd)}",
+                "Total": f"{'+'if adj_usd>=0 else '-'}${_fmt(abs(adj_usd))}",
+            }
+        )
+    if ctrl_rows:
+        builder.table(ctrl_rows)
+
+    # ---- Pair summary table ----
+    pair_groups: dict[str, list[dict]] = defaultdict(list)
+    for c in controllers_parsed:
+        pair_groups[c["pair"] or "unknown"].append(c)
+    pair_rows = []
+    for pair, ctrls in sorted(
+        pair_groups.items(), key=lambda x: sum(c["vol"] for c in x[1]), reverse=True
+    ):
+        grp_vol = sum(_vol_to_usd(c, quote_usd_rate) for c in ctrls)
+        grp_realized = sum(c["realized"] for c in ctrls) * quote_usd_rate
+        grp_unrealized = sum(c["unrealized"] for c in ctrls) * quote_usd_rate
+        grp_net = grp_realized + grp_unrealized
+        grp_rebate = grp_vol * REBATE_RATE if _pair_has_rebate(pair, qc) else 0
+        grp_adj = grp_net + grp_rebate
+        # Market share
+        vol_data = volumes_since.get(pair, (0, 0))
+        vol_base, vol_quote = vol_data if isinstance(vol_data, tuple) else (vol_data, 0)
+        mkt_usd = _market_vol_to_usd(pair, vol_base, vol_quote, quote_usd_rate, prices)
+        share = f"{grp_vol / mkt_usd * 100:.2f}%" if mkt_usd > 0 else "N/A"
+        grp_capital = sum(_amount_quote_to_usd(c, quote_usd_rate) for c in ctrls)
+        pair_rows.append(
+            {
+                "Pair": pair,
+                "Controllers": str(len(ctrls)),
+                "Capital": f"${_fmt(grp_capital)}" if grp_capital > 0 else "-",
+                "Volume": f"${_fmt(grp_vol)}",
+                "Realized": f"{'+'if grp_realized>=0 else '-'}${_fmt(abs(grp_realized))}",
+                "Net PnL": f"{'+'if grp_net>=0 else '-'}${_fmt(abs(grp_net))}",
+                "Rebate": f"+${_fmt(grp_rebate)}",
+                "Adjusted": f"{'+'if grp_adj>=0 else '-'}${_fmt(abs(grp_adj))}",
+                "Mkt Share": share,
+            }
+        )
+    if pair_rows:
+        builder.table(pair_rows)
+
+    # ---- Balance table ----
+    if balances:
+        token_totals: dict[str, float] = defaultdict(float)
+        token_values: dict[str, float] = defaultdict(float)
+        for account_data in balances.values():
+            for connector_balances in account_data.values():
+                if not isinstance(connector_balances, list):
+                    continue
+                for b in connector_balances:
+                    token = b.get("token", "")
+                    value = float(b.get("value", 0) or 0)
+                    units = float(b.get("units", 0) or 0)
+                    if value > 0:
+                        token_totals[token] += units
+                        token_values[token] += value
+        if token_values:
+            bal_rows = []
+            for token, value in sorted(
+                token_values.items(), key=lambda x: x[1], reverse=True
+            ):
+                pct = (value / total_balance_usd * 100) if total_balance_usd > 0 else 0
+                bal_rows.append(
+                    {
+                        "Token": token,
+                        "Amount": _fmt(token_totals[token], 4),
+                        "Value (USD)": f"${_fmt(value)}",
+                        "Weight": f"{pct:.1f}%",
+                    }
+                )
+            builder.table(bal_rows)
+
+    # ---- Config Analysis section ----
+    if len(ctrl_configs) > 1:
+        all_params = set()
+        for cfg in ctrl_configs.values():
+            all_params.update(cfg.keys())
+        all_params -= _CONFIG_SKIP_PARAMS
+        sorted_params = sorted(
+            all_params, key=lambda p: (0 if p in _CONFIG_KEY_PARAMS else 1, p)
+        )
+
+        # Group configs by pair
+        cfg_pair_groups: dict[str, dict] = defaultdict(dict)
+        for cid, cfg in ctrl_configs.items():
+            pair = cfg.get("trading_pair", "unknown")
+            cfg_pair_groups[pair][cid] = cfg
+
+        # Count total diffs
+        total_diffs = 0
+        pair_sections = []
+        for pair, pair_cfgs in sorted(
+            cfg_pair_groups.items(), key=lambda x: -len(x[1])
+        ):
+            if len(pair_cfgs) < 2:
+                continue
+            labels = list(pair_cfgs.keys())
+            shorts = [_short_chart_name(l, pair) for l in labels]
+
+            diff_rows = []
+            for param in sorted_params:
+                values = [_cfg_normalize(pair_cfgs[l].get(param)) for l in labels]
+                non_none = [v for v in values if v is not None]
+                if len(non_none) < 2 or len(set(str(v) for v in non_none)) <= 1:
+                    continue
+                is_key = param in _CONFIG_KEY_PARAMS
+                row = {"Parameter": f"{'🔴 ' if is_key else '🟡 '}{param}"}
+                for short, label in zip(shorts, labels):
+                    row[short] = _cfg_fmt_value(pair_cfgs[label].get(param))
+                diff_rows.append(row)
+
+            if diff_rows:
+                total_diffs += len(diff_rows)
+                pair_sections.append((pair, len(pair_cfgs), diff_rows))
+
+        if pair_sections:
+            builder.markdown(
+                "## Config Analysis\n\nParameter differences across running controllers. 🔴 = key tuning param, 🟡 = other."
+            )
+            for pair, n_cfgs, rows in pair_sections:
+                builder.markdown(
+                    f"### {pair} — {len(rows)} diffs across {n_cfgs} controllers"
+                )
+                builder.table(rows)
+
+        # Config charts
+        labeled_configs = {f"\U0001f7e2 {k}": v for k, v in ctrl_configs.items()}
+        running_ids = set(ctrl_configs.keys())
+
+        fig_pc = _build_config_parallel_coords(labeled_configs, running_ids)
+        if fig_pc:
+            if not pair_sections:
+                builder.markdown("## Config Analysis")
+            builder.plotly(fig_pc)
+
+        fig_spread = _build_config_spread_chart(labeled_configs)
+        if fig_spread:
+            builder.plotly(fig_spread)
+
+    await builder.save()
+
+    return f"Report sent: {sent}/{len(messages)} messages\n\n{plain_report}"
diff --git a/agents/brigado/routines/brl_dashboard.py b/agents/brigado/routines/brl_dashboard.py
new file mode 100644
index 00000000..69184400
--- /dev/null
+++ b/agents/brigado/routines/brl_dashboard.py
@@ -0,0 +1,573 @@
+"""Multi-timeframe USDT-BRL technical dashboard with Plotly chart."""
+
+CATEGORY = "Market Data"
+
+import asyncio
+import io
+import logging
+from datetime import datetime, timezone
+
+import numpy as np
+import pandas as pd
+import plotly.graph_objects as go
+from plotly.subplots import make_subplots
+from pydantic import BaseModel, Field
+from telegram.ext import ContextTypes
+
+from config_manager import get_client
+from routines.base import RoutineResult
+
+logger = logging.getLogger(__name__)
+
+
+class Config(BaseModel):
+    """USDT-BRL multi-timeframe dashboard: intraday, weekly, monthly, quarterly."""
+
+    trading_pair: str = Field(default="USDT-BRL", description="Trading pair")
+    connector_name: str = Field(default="binance", description="Exchange connector")
+
+
+# ---------------------------------------------------------------------------
+# Indicators
+# ---------------------------------------------------------------------------
+
+
+def compute_sma(series: pd.Series, period: int) -> pd.Series:
+    return series.rolling(window=period, min_periods=period).mean()
+
+
+def compute_ema(series: pd.Series, period: int) -> pd.Series:
+    return series.ewm(span=period, adjust=False).mean()
+
+
+def compute_rsi(series: pd.Series, period: int = 14) -> pd.Series:
+    delta = series.diff()
+    gain = delta.where(delta > 0, 0.0)
+    loss = (-delta).where(delta < 0, 0.0)
+    avg_gain = gain.ewm(alpha=1 / period, min_periods=period).mean()
+    avg_loss = loss.ewm(alpha=1 / period, min_periods=period).mean()
+    rs = avg_gain / avg_loss.replace(0, np.nan)
+    rsi = 100 - (100 / (1 + rs))
+    return rsi.fillna(50)
+
+
+def find_sr_levels(
+    highs: pd.Series, lows: pd.Series, window: int = 20
+) -> tuple[list[float], list[float]]:
+    """Find support/resistance using rolling min/max pivots."""
+    n = len(highs)
+    if n < window * 2:
+        return [], []
+
+    h = highs.values
+    l = lows.values
+    close = float(highs.iloc[-1] + lows.iloc[-1]) / 2
+
+    levels: dict[float, int] = {}
+    for w in (window, window * 2):
+        if w >= n // 2:
+            continue
+        for i in range(w, n - w):
+            if l[i] == min(l[i - w : i + w + 1]):
+                lv = round(float(l[i]), 4)
+                levels[lv] = levels.get(lv, 0) + 1
+            if h[i] == max(h[i - w : i + w + 1]):
+                lv = round(float(h[i]), 4)
+                levels[lv] = levels.get(lv, 0) + 1
+
+    if not levels:
+        return [], []
+
+    # Cluster nearby levels (within 0.3%)
+    sorted_levels = sorted(levels.items())
+    clusters: list[list[tuple[float, int]]] = [[sorted_levels[0]]]
+    for price, hits in sorted_levels[1:]:
+        cluster_avg = np.mean([p for p, _ in clusters[-1]])
+        if abs(price - cluster_avg) / cluster_avg < 0.003:
+            clusters[-1].append((price, hits))
+        else:
+            clusters.append([(price, hits)])
+
+    merged = []
+    for cluster in clusters:
+        total_hits = sum(h for _, h in cluster)
+        avg_price = np.average([p for p, _ in cluster], weights=[h for _, h in cluster])
+        merged.append((round(float(avg_price), 4), total_hits))
+
+    supports = sorted([lv for lv, _ in merged if lv < close], reverse=True)[:3]
+    resistances = sorted([lv for lv, _ in merged if lv >= close])[:3]
+    return supports, resistances
+
+
+# ---------------------------------------------------------------------------
+# Data fetching & processing
+# ---------------------------------------------------------------------------
+
+TIMEFRAMES = [
+    {"label": "Intraday (1m)", "interval": "1m", "days": 1, "short_label": "1D"},
+    {"label": "Semanal (15m)", "interval": "15m", "days": 7, "short_label": "1W"},
+    {"label": "Mensual (1h)", "interval": "1h", "days": 30, "short_label": "1M"},
+    {"label": "Trimestral (1d)", "interval": "1d", "days": 90, "short_label": "3M"},
+]
+
+
+async def fetch_candles(
+    client, connector: str, pair: str, interval: str, days: int
+) -> pd.DataFrame:
+    """Fetch candles and return as DataFrame."""
+    result = await client.market_data.get_candles_last_days(
+        connector, pair, days=days, interval=interval
+    )
+    # API returns a list directly, or a dict with "candles"/"data" key
+    if isinstance(result, list):
+        records = result
+    elif isinstance(result, dict):
+        records = result.get("data", result.get("candles", []))
+    else:
+        records = []
+    if not records:
+        return pd.DataFrame()
+
+    df = pd.DataFrame(records)
+    for col in ("open", "high", "low", "close", "volume"):
+        df[col] = pd.to_numeric(df[col], errors="coerce")
+
+    ts_col = df["timestamp"]
+    unit = "s" if ts_col.iloc[0] > 1e12 / 1000 else "ms"
+    df["datetime"] = pd.to_datetime(ts_col, unit=unit, utc=True)
+    df = df.sort_values("datetime").reset_index(drop=True)
+    return df
+
+
+def compute_indicators(df: pd.DataFrame) -> dict:
+    """Compute all indicators for a timeframe."""
+    close = df["close"]
+    sma20 = compute_sma(close, 20)
+    sma50 = compute_sma(close, 50)
+    ema9 = compute_ema(close, 9)
+    ema21 = compute_ema(close, 21)
+    rsi = compute_rsi(close, 14)
+
+    current = float(close.iloc[-1])
+    open_price = float(close.iloc[0])
+    change_pct = (current - open_price) / open_price * 100
+
+    high = float(df["high"].max())
+    low = float(df["low"].min())
+
+    supports, resistances = find_sr_levels(df["high"], df["low"])
+
+    # Trend direction
+    sma20_now = sma20.iloc[-1]
+    sma50_now = sma50.iloc[-1]
+    if pd.notna(sma20_now) and pd.notna(sma50_now):
+        if current > sma20_now > sma50_now:
+            trend = "ALCISTA"
+        elif current < sma20_now < sma50_now:
+            trend = "BAJISTA"
+        else:
+            trend = "LATERAL"
+    else:
+        trend = "N/A"
+
+    return {
+        "sma20": sma20,
+        "sma50": sma50,
+        "ema9": ema9,
+        "ema21": ema21,
+        "rsi": rsi,
+        "current": current,
+        "change_pct": change_pct,
+        "high": high,
+        "low": low,
+        "supports": supports,
+        "resistances": resistances,
+        "trend": trend,
+        "rsi_now": float(rsi.iloc[-1]) if pd.notna(rsi.iloc[-1]) else 50,
+        "sma20_now": float(sma20_now) if pd.notna(sma20_now) else current,
+        "sma50_now": float(sma50_now) if pd.notna(sma50_now) else current,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Chart
+# ---------------------------------------------------------------------------
+
+COLORS = {
+    "bg_paper": "#0d1117",
+    "bg_plot": "#161b22",
+    "grid": "#21262d",
+    "text": "#c9d1d9",
+    "text_dim": "#8b949e",
+    "green": "#3fb950",
+    "red": "#f85149",
+    "sma20": "#f0883e",
+    "sma50": "#58a6ff",
+    "rsi_line": "#bc8cff",
+    "support": "#3fb950",
+    "resistance": "#f85149",
+}
+
+
+def build_chart(timeframe_data: list[dict], pair: str) -> io.BytesIO:
+    """Build a 4x2 dashboard: candlestick+SMA (left col), RSI (right col) per timeframe."""
+    fig = make_subplots(
+        rows=4,
+        cols=2,
+        column_widths=[0.78, 0.22],
+        row_heights=[0.25, 0.25, 0.25, 0.25],
+        vertical_spacing=0.045,
+        horizontal_spacing=0.03,
+        subplot_titles=(
+            [
+                item["label"]
+                for item in timeframe_data
+                for _ in range(2)  # one title per subplot pair
+            ]
+            if False
+            else None
+        ),  # We'll add custom titles
+    )
+
+    current_price = timeframe_data[0]["indicators"]["current"] if timeframe_data else 0
+
+    for i, item in enumerate(timeframe_data):
+        row = i + 1
+        df = item["df"]
+        ind = item["indicators"]
+        tf = item["tf"]
+        dates = df["datetime"]
+
+        # --- Candlestick ---
+        fig.add_trace(
+            go.Candlestick(
+                x=dates,
+                open=df["open"],
+                high=df["high"],
+                low=df["low"],
+                close=df["close"],
+                increasing_line_color=COLORS["green"],
+                decreasing_line_color=COLORS["red"],
+                increasing_fillcolor=COLORS["green"],
+                decreasing_fillcolor=COLORS["red"],
+                showlegend=False,
+                name=tf["short_label"],
+            ),
+            row=row,
+            col=1,
+        )
+
+        # SMA20
+        sma20_valid = ind["sma20"].dropna()
+        if len(sma20_valid) > 0:
+            fig.add_trace(
+                go.Scatter(
+                    x=dates.iloc[sma20_valid.index],
+                    y=sma20_valid,
+                    line=dict(color=COLORS["sma20"], width=1.2),
+                    showlegend=(i == 0),
+                    name="SMA 20",
+                ),
+                row=row,
+                col=1,
+            )
+
+        # SMA50
+        sma50_valid = ind["sma50"].dropna()
+        if len(sma50_valid) > 0:
+            fig.add_trace(
+                go.Scatter(
+                    x=dates.iloc[sma50_valid.index],
+                    y=sma50_valid,
+                    line=dict(color=COLORS["sma50"], width=1.2),
+                    showlegend=(i == 0),
+                    name="SMA 50",
+                ),
+                row=row,
+                col=1,
+            )
+
+        # Support lines
+        t0, t1 = dates.iloc[0], dates.iloc[-1]
+        for s in ind["supports"]:
+            fig.add_shape(
+                type="line",
+                x0=t0,
+                x1=t1,
+                y0=s,
+                y1=s,
+                line=dict(color=COLORS["support"], width=0.7, dash="dot"),
+                opacity=0.5,
+                row=row,
+                col=1,
+            )
+
+        # Resistance lines
+        for r in ind["resistances"]:
+            fig.add_shape(
+                type="line",
+                x0=t0,
+                x1=t1,
+                y0=r,
+                y1=r,
+                line=dict(color=COLORS["resistance"], width=0.7, dash="dot"),
+                opacity=0.5,
+                row=row,
+                col=1,
+            )
+
+        # --- RSI panel ---
+        rsi_valid = ind["rsi"].dropna()
+        if len(rsi_valid) > 0:
+            fig.add_trace(
+                go.Scatter(
+                    x=dates.iloc[rsi_valid.index],
+                    y=rsi_valid,
+                    line=dict(color=COLORS["rsi_line"], width=1.5),
+                    fill="tozeroy",
+                    fillcolor="rgba(188,140,255,0.08)",
+                    showlegend=False,
+                ),
+                row=row,
+                col=2,
+            )
+
+            # Overbought/oversold bands
+            fig.add_hline(
+                y=70,
+                line_dash="dot",
+                line_color=COLORS["red"],
+                opacity=0.4,
+                row=row,
+                col=2,
+            )
+            fig.add_hline(
+                y=30,
+                line_dash="dot",
+                line_color=COLORS["green"],
+                opacity=0.4,
+                row=row,
+                col=2,
+            )
+
+        # --- Row label annotation ---
+        trend_color = COLORS["green"] if ind["change_pct"] >= 0 else COLORS["red"]
+        arrow = "+" if ind["change_pct"] >= 0 else ""
+        label_text = (
+            f"<b>{tf['short_label']}</b> {tf['label'].split('(')[1].rstrip(')')}"
+            f"  |  {ind['current']:.3f}"
+            f"  |  <span style='color:{trend_color}'>{arrow}{ind['change_pct']:.2f}%</span>"
+            f"  |  RSI: {ind['rsi_now']:.0f}"
+            f"  |  {ind['trend']}"
+        )
+        fig.add_annotation(
+            text=label_text,
+            xref="paper",
+            yref="paper",
+            x=0,
+            y=1 - (i * 0.25) + 0.005,
+            showarrow=False,
+            font=dict(size=11, color=COLORS["text"]),
+            xanchor="left",
+            yanchor="bottom",
+        )
+
+    # --- Header ---
+    # Get quarterly change
+    q_change = (
+        timeframe_data[3]["indicators"]["change_pct"] if len(timeframe_data) > 3 else 0
+    )
+    m_change = (
+        timeframe_data[2]["indicators"]["change_pct"] if len(timeframe_data) > 2 else 0
+    )
+    w_change = (
+        timeframe_data[1]["indicators"]["change_pct"] if len(timeframe_data) > 1 else 0
+    )
+    d_change = timeframe_data[0]["indicators"]["change_pct"] if timeframe_data else 0
+
+    title_text = (
+        f"<b>{pair}</b>  |  {current_price:.3f}"
+        f"  |  D: {d_change:+.2f}%  W: {w_change:+.2f}%  M: {m_change:+.2f}%  3M: {q_change:+.2f}%"
+    )
+
+    # --- Layout ---
+    fig.update_layout(
+        title=dict(text=title_text, font=dict(color=COLORS["text"], size=14), x=0.5),
+        paper_bgcolor=COLORS["bg_paper"],
+        plot_bgcolor=COLORS["bg_plot"],
+        font=dict(color=COLORS["text_dim"], size=9),
+        legend=dict(
+            orientation="h",
+            yanchor="bottom",
+            y=1.05,
+            xanchor="center",
+            x=0.4,
+            font=dict(size=10, color=COLORS["text"]),
+            bgcolor="rgba(0,0,0,0)",
+        ),
+        margin=dict(l=55, r=30, t=100, b=30),
+        width=1300,
+        height=1400,
+        xaxis_rangeslider_visible=False,
+        xaxis3_rangeslider_visible=False,
+        xaxis5_rangeslider_visible=False,
+        xaxis7_rangeslider_visible=False,
+    )
+
+    # Style axes
+    for row in range(1, 5):
+        # Price axis
+        fig.update_yaxes(
+            gridcolor=COLORS["grid"],
+            zerolinecolor=COLORS["grid"],
+            tickformat=".3f",
+            row=row,
+            col=1,
+        )
+        fig.update_xaxes(
+            gridcolor=COLORS["grid"], showticklabels=(row == 4), row=row, col=1
+        )
+        # RSI axis
+        fig.update_yaxes(
+            gridcolor=COLORS["grid"],
+            range=[0, 100],
+            tickvals=[30, 50, 70],
+            row=row,
+            col=2,
+        )
+        fig.update_xaxes(gridcolor=COLORS["grid"], showticklabels=False, row=row, col=2)
+
+    buf = io.BytesIO()
+    fig.write_image(buf, format="png", scale=2)
+    buf.seek(0)
+    return buf, fig
+
+
+# ---------------------------------------------------------------------------
+# Text summary
+# ---------------------------------------------------------------------------
+
+
+def format_summary(timeframe_data: list[dict], pair: str) -> str:
+    lines = [f"Dashboard {pair}"]
+    for item in timeframe_data:
+        ind = item["indicators"]
+        tf = item["tf"]
+        arrow = "+" if ind["change_pct"] >= 0 else ""
+        sup_str = ", ".join(f"{s:.3f}" for s in ind["supports"][:2]) or "N/A"
+        res_str = ", ".join(f"{r:.3f}" for r in ind["resistances"][:2]) or "N/A"
+        lines.append(
+            f"\n{tf['label']}:"
+            f"\n  Precio: {ind['current']:.3f} ({arrow}{ind['change_pct']:.2f}%)"
+            f"\n  Tendencia: {ind['trend']} | RSI: {ind['rsi_now']:.0f}"
+            f"\n  SMA20: {ind['sma20_now']:.3f} | SMA50: {ind['sma50_now']:.3f}"
+            f"\n  Soporte: {sup_str} | Resistencia: {res_str}"
+            f"\n  Rango: {ind['low']:.3f} - {ind['high']:.3f}"
+        )
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Telegram photo fallback
+# ---------------------------------------------------------------------------
+
+
+async def _send_photo_http(chat_id: int, buf: io.BytesIO, caption: str) -> None:
+    import os
+
+    import httpx
+
+    token = os.environ.get("TELEGRAM_BOT_TOKEN") or os.environ.get("TELEGRAM_TOKEN", "")
+    if not token:
+        return
+
+    url = f"https://api.telegram.org/bot{token}/sendPhoto"
+    buf.seek(0)
+    async with httpx.AsyncClient(timeout=30) as http_client:
+        resp = await http_client.post(
+            url,
+            data={"chat_id": chat_id, "caption": caption},
+            files={"photo": ("dashboard.png", buf, "image/png")},
+        )
+        if not resp.json().get("ok"):
+            logger.warning(f"sendPhoto failed: {resp.text}")
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+
+async def run(config: Config, context: ContextTypes.DEFAULT_TYPE) -> str:
+    chat_id = context._chat_id if hasattr(context, "_chat_id") else None
+    client = await get_client(chat_id, context=context)
+    if not client:
+        return "No server available"
+
+    # Fetch all timeframes in parallel
+    fetch_tasks = [
+        fetch_candles(
+            client,
+            config.connector_name,
+            config.trading_pair,
+            tf["interval"],
+            tf["days"],
+        )
+        for tf in TIMEFRAMES
+    ]
+    results = await asyncio.gather(*fetch_tasks, return_exceptions=True)
+
+    timeframe_data = []
+    for tf, result in zip(TIMEFRAMES, results):
+        if isinstance(result, Exception):
+            logger.warning(f"Failed to fetch {tf['label']}: {result}")
+            continue
+        if result.empty or len(result) < 10:
+            logger.warning(f"Not enough data for {tf['label']}: {len(result)} candles")
+            continue
+
+        indicators = compute_indicators(result)
+        timeframe_data.append(
+            {
+                "tf": tf,
+                "label": tf["label"],
+                "df": result,
+                "indicators": indicators,
+            }
+        )
+
+    if not timeframe_data:
+        return "No candle data available for any timeframe"
+
+    # Generate chart
+    chart_bytes: bytes | None = None
+    plotly_fig = None
+    try:
+        buf, plotly_fig = build_chart(timeframe_data, config.trading_pair)
+        chart_bytes = buf.getvalue()
+        caption = f"{config.trading_pair} Multi-Timeframe Dashboard"
+        if chat_id:
+            buf.seek(0)
+            if context.bot:
+                await context.bot.send_photo(
+                    chat_id=chat_id, photo=buf, caption=caption
+                )
+            else:
+                await _send_photo_http(chat_id, buf, caption)
+    except Exception as e:
+        logger.warning(f"Chart generation/send failed: {e}")
+
+    text = format_summary(timeframe_data, config.trading_pair)
+
+    from condor.reports import ReportBuilder
+
+    builder = ReportBuilder(f"Dashboard: {config.trading_pair}")
+    builder.source("routine", "brl_dashboard").tags(["dashboard", config.trading_pair])
+    builder.markdown(text)
+    if plotly_fig is not None:
+        builder.plotly(plotly_fig)
+    await builder.save()
+
+    if context.bot and chart_bytes:
+        return RoutineResult(text=text, chart_image=chart_bytes)
+    return text
diff --git a/agents/brigado/routines/btc_brl_arbitrage.py b/agents/brigado/routines/btc_brl_arbitrage.py
new file mode 100644
index 00000000..a51e3ccd
--- /dev/null
+++ b/agents/brigado/routines/btc_brl_arbitrage.py
@@ -0,0 +1,608 @@
+"""BTC-BRL arbitrage: spread analysis + quoting strategy simulation."""
+
+CATEGORY = "Market Data"
+
+import asyncio
+import io
+import logging
+
+import numpy as np
+import pandas as pd
+import plotly.graph_objects as go
+from plotly.subplots import make_subplots
+from pydantic import BaseModel, Field
+from telegram.ext import ContextTypes
+
+from config_manager import get_client
+from routines.base import RoutineResult
+
+logger = logging.getLogger(__name__)
+
+COLORS = {
+    "bg_paper": "#0d1117",
+    "bg_plot": "#161b22",
+    "grid": "#21262d",
+    "text": "#c9d1d9",
+    "text_dim": "#8b949e",
+    "usdt": "#f0b90b",
+    "brl": "#3fb950",
+    "spread": "#bc8cff",
+    "long": "#3fb950",
+    "short": "#f85149",
+    "pnl": "#58a6ff",
+    "fees": "#f78166",
+}
+
+LAYOUT_BASE = dict(
+    paper_bgcolor=COLORS["bg_paper"],
+    plot_bgcolor=COLORS["bg_plot"],
+    font=dict(color=COLORS["text_dim"], size=10),
+    legend=dict(
+        orientation="h",
+        yanchor="bottom",
+        y=1.05,
+        xanchor="center",
+        x=0.5,
+        font=dict(size=10, color=COLORS["text"]),
+        bgcolor="rgba(0,0,0,0)",
+    ),
+    margin=dict(l=60, r=30, t=100, b=40),
+)
+
+
+class Config(BaseModel):
+    """BTC-BRL arbitrage: spread analysis + quoting strategy simulation."""
+
+    connector_name: str = Field(default="binance", description="Exchange connector")
+    lookback_seconds: int = Field(
+        default=3600, description="1s candles to fetch (3600=1h)"
+    )
+    trade_size_usdt: float = Field(
+        default=100.0, description="Notional per trade in USDT"
+    )
+    fee_bps: float = Field(
+        default=10.0, description="Round-trip fee in bps (maker+taker)"
+    )
+    min_spread_bps: float = Field(default=2.0, description="Min spread to enter (bps)")
+    max_position_usdt: float = Field(
+        default=5000.0, description="Max accumulated position (USDT)"
+    )
+
+
+async def _fetch_candles(
+    client, connector: str, pair: str, interval: str, max_records: int
+) -> pd.DataFrame:
+    result = await client.market_data.get_candles(
+        connector, pair, interval=interval, max_records=max_records
+    )
+    if isinstance(result, list):
+        records = result
+    elif isinstance(result, dict):
+        records = result.get("data", result.get("candles", []))
+    else:
+        records = []
+    if not records:
+        return pd.DataFrame()
+    df = pd.DataFrame(records)
+    for col in ("open", "high", "low", "close", "volume", "quote_asset_volume"):
+        if col in df.columns:
+            df[col] = pd.to_numeric(df[col], errors="coerce")
+    ts = df["timestamp"]
+    unit = "s" if ts.iloc[0] > 1e12 / 1000 else "ms"
+    df["datetime"] = pd.to_datetime(ts, unit=unit, utc=True)
+    return df.sort_values("datetime").reset_index(drop=True)
+
+
+def _style_axes(fig, rows):
+    for row in range(1, rows + 1):
+        fig.update_yaxes(
+            gridcolor=COLORS["grid"], zerolinecolor=COLORS["grid"], row=row, col=1
+        )
+        fig.update_xaxes(gridcolor=COLORS["grid"], row=row, col=1)
+
+
+def _merge_spread(
+    price_usdt: pd.DataFrame, price_brl: pd.DataFrame, usdtbrl: pd.DataFrame
+) -> pd.DataFrame:
+    """Merge 1s candles and compute spread %."""
+    for df in (price_usdt, price_brl, usdtbrl):
+        df["ts"] = df["datetime"].dt.floor("s")
+
+    merged = pd.merge(
+        price_usdt[["ts", "close"]].rename(columns={"close": "btc_usdt"}),
+        price_brl[["ts", "close"]].rename(columns={"close": "btc_brl"}),
+        on="ts",
+        how="inner",
+    )
+    merged = pd.merge(
+        merged,
+        usdtbrl[["ts", "close"]].rename(columns={"close": "usdt_brl_rate"}),
+        on="ts",
+        how="inner",
+    )
+    merged["btc_brl_usd"] = merged["btc_brl"] / merged["usdt_brl_rate"]
+    merged["spread_pct"] = (
+        (merged["btc_brl_usd"] - merged["btc_usdt"]) / merged["btc_usdt"]
+    ) * 100
+    merged["spread_bps"] = merged["spread_pct"] * 100
+    return merged.sort_values("ts").reset_index(drop=True)
+
+
+def simulate_quoting(
+    merged: pd.DataFrame,
+    trade_size_usdt: float,
+    fee_bps: float,
+    min_spread_bps: float,
+    max_position_usdt: float,
+) -> pd.DataFrame:
+    """Simulate a one-sided quoting strategy that captures spread.
+
+    Logic:
+    - When BRL premium (spread > min_spread): sell on BRL side (capture premium)
+      → accumulate short BRL / long USDT exposure
+    - When USDT premium (spread < -min_spread): sell on USDT side (capture premium)
+      → accumulate short USDT / long BRL exposure
+    - Position flips naturally as spread oscillates
+    - Fee deducted on each trade
+    """
+    n = len(merged)
+    fee_pct = fee_bps / 10000
+
+    # Track state
+    position_usdt = np.zeros(
+        n
+    )  # net position in USDT terms (+ = long BRL, - = short BRL)
+    cum_captured = np.zeros(n)  # cumulative spread captured (before fees)
+    cum_fees = np.zeros(n)  # cumulative fees paid
+    cum_pnl = np.zeros(n)  # net PnL (captured - fees)
+    trade_count = np.zeros(n, dtype=int)
+    actions = [""] * n
+
+    pos = 0.0
+    captured = 0.0
+    fees = 0.0
+    trades = 0
+
+    for i in range(n):
+        spread_bps = merged["spread_bps"].iloc[i]
+        abs_spread = abs(spread_bps)
+
+        if abs_spread > min_spread_bps:
+            # Check position limits
+            if spread_bps > 0 and pos > -max_position_usdt:
+                # BRL premium → sell on BRL (go short BRL exposure)
+                trade_pnl = (abs_spread / 10000) * trade_size_usdt
+                trade_fee = fee_pct * trade_size_usdt
+                captured += trade_pnl
+                fees += trade_fee
+                pos -= trade_size_usdt
+                trades += 1
+                actions[i] = "sell_brl"
+            elif spread_bps < 0 and pos < max_position_usdt:
+                # USDT premium → sell on USDT (go long BRL exposure)
+                trade_pnl = (abs_spread / 10000) * trade_size_usdt
+                trade_fee = fee_pct * trade_size_usdt
+                captured += trade_pnl
+                fees += trade_fee
+                pos += trade_size_usdt
+                trades += 1
+                actions[i] = "sell_usdt"
+
+        position_usdt[i] = pos
+        cum_captured[i] = captured
+        cum_fees[i] = fees
+        cum_pnl[i] = captured - fees
+        trade_count[i] = trades
+
+    merged = merged.copy()
+    merged["position_usdt"] = position_usdt
+    merged["cum_captured"] = cum_captured
+    merged["cum_fees"] = cum_fees
+    merged["cum_pnl"] = cum_pnl
+    merged["trade_count"] = trade_count
+    merged["action"] = actions
+
+    # Mark-to-market: unrealized PnL from position * current spread change
+    # Position was entered at various spreads; approximate with running avg
+    merged["unrealized"] = 0.0
+    avg_entry_spread = 0.0
+    total_pos = 0.0
+    for i in range(n):
+        if actions[i]:
+            entry_spread = merged["spread_bps"].iloc[i]
+            trade_pos = (
+                trade_size_usdt if actions[i] == "sell_usdt" else -trade_size_usdt
+            )
+            if abs(total_pos + trade_pos) > 0.01:
+                avg_entry_spread = (
+                    avg_entry_spread * total_pos + entry_spread * trade_pos
+                ) / (total_pos + trade_pos)
+            total_pos += trade_pos
+        current_spread = merged["spread_bps"].iloc[i]
+        # If short BRL (pos < 0), we profit when spread decreases
+        # If long BRL (pos > 0), we profit when spread increases
+        spread_change = current_spread - avg_entry_spread
+        merged.loc[merged.index[i], "unrealized"] = (spread_change / 10000) * total_pos
+
+    merged["total_pnl"] = merged["cum_pnl"] + merged["unrealized"]
+
+    return merged
+
+
+def build_spread_chart(merged: pd.DataFrame) -> go.Figure:
+    """Chart 1: Raw spread analysis."""
+    avg_spread = merged["spread_pct"].mean()
+    curr_spread = merged["spread_pct"].iloc[-1]
+    std_spread = merged["spread_pct"].std()
+    max_spread = merged["spread_pct"].max()
+    min_spread = merged["spread_pct"].min()
+    current_btc = float(merged["btc_usdt"].iloc[-1])
+
+    fig = make_subplots(
+        rows=2,
+        cols=1,
+        row_heights=[0.55, 0.45],
+        vertical_spacing=0.08,
+        subplot_titles=[
+            "BTC: USDT vs BRL→USD (1s)",
+            f"Spread % — avg {avg_spread:+.4f}%, std {std_spread:.4f}%",
+        ],
+    )
+
+    fig.add_trace(
+        go.Scatter(
+            x=merged["ts"],
+            y=merged["btc_usdt"],
+            line=dict(color=COLORS["usdt"], width=1.5),
+            name="BTC-USDT",
+        ),
+        row=1,
+        col=1,
+    )
+    fig.add_trace(
+        go.Scatter(
+            x=merged["ts"],
+            y=merged["btc_brl_usd"],
+            line=dict(color=COLORS["brl"], width=1.5),
+            name="BTC-BRL (USD)",
+        ),
+        row=1,
+        col=1,
+    )
+
+    # Spread with color fill
+    fig.add_trace(
+        go.Scatter(
+            x=merged["ts"],
+            y=merged["spread_pct"],
+            line=dict(color=COLORS["spread"], width=1.2),
+            fill="tozeroy",
+            fillcolor="rgba(188,140,255,0.08)",
+            name="Spread %",
+        ),
+        row=2,
+        col=1,
+    )
+    fig.add_hline(y=0, line_color=COLORS["grid"], row=2, col=1)
+    fig.add_hline(
+        y=avg_spread,
+        line_dash="dash",
+        line_color=COLORS["text_dim"],
+        opacity=0.6,
+        row=2,
+        col=1,
+        annotation_text=f"avg {avg_spread:+.4f}%",
+        annotation_font_color=COLORS["text_dim"],
+    )
+
+    fig.update_layout(
+        **LAYOUT_BASE,
+        title=dict(
+            text=(
+                f"<b>BTC-BRL Spread</b>  |  BTC: ${current_btc:,.0f}"
+                f"  |  Now: {curr_spread:+.4f}%"
+                f"  |  Range: [{min_spread:+.4f}%, {max_spread:+.4f}%]"
+            ),
+            font=dict(color=COLORS["text"], size=13),
+            x=0.5,
+        ),
+        width=1300,
+        height=700,
+    )
+    fig.update_yaxes(title_text="USD", tickformat=",.0f", row=1, col=1)
+    fig.update_yaxes(title_text="%", tickformat=".4f", row=2, col=1)
+    for ann in fig.layout.annotations:
+        ann.font = dict(color=COLORS["text_dim"], size=11)
+    _style_axes(fig, 2)
+    return fig
+
+
+def build_strategy_chart(
+    sim: pd.DataFrame, fee_bps: float, min_spread_bps: float, trade_size_usdt: float
+) -> go.Figure:
+    """Chart 2: Strategy simulation results."""
+    total_trades = int(sim["trade_count"].iloc[-1])
+    final_pnl = sim["cum_pnl"].iloc[-1]
+    final_captured = sim["cum_captured"].iloc[-1]
+    final_fees = sim["cum_fees"].iloc[-1]
+    final_position = sim["position_usdt"].iloc[-1]
+    final_total = sim["total_pnl"].iloc[-1]
+    duration_min = (sim["ts"].iloc[-1] - sim["ts"].iloc[0]).total_seconds() / 60
+
+    fig = make_subplots(
+        rows=3,
+        cols=1,
+        row_heights=[0.4, 0.3, 0.3],
+        vertical_spacing=0.06,
+        subplot_titles=[
+            f"Cumulative PnL — {total_trades} trades in {duration_min:.0f}min",
+            f"Net Position (max ${sim['position_usdt'].abs().max():,.0f})",
+            "Spread (bps) + Trade Signals",
+        ],
+    )
+
+    # Row 1: PnL breakdown
+    fig.add_trace(
+        go.Scatter(
+            x=sim["ts"],
+            y=sim["cum_captured"],
+            line=dict(color=COLORS["brl"], width=1.5),
+            name="Captured (gross)",
+            fill="tozeroy",
+            fillcolor="rgba(63,185,80,0.08)",
+        ),
+        row=1,
+        col=1,
+    )
+    fig.add_trace(
+        go.Scatter(
+            x=sim["ts"],
+            y=sim["cum_fees"],
+            line=dict(color=COLORS["fees"], width=1, dash="dot"),
+            name="Fees paid",
+        ),
+        row=1,
+        col=1,
+    )
+    fig.add_trace(
+        go.Scatter(
+            x=sim["ts"],
+            y=sim["cum_pnl"],
+            line=dict(color=COLORS["pnl"], width=2),
+            name="Net PnL (realized)",
+        ),
+        row=1,
+        col=1,
+    )
+    fig.add_trace(
+        go.Scatter(
+            x=sim["ts"],
+            y=sim["total_pnl"],
+            line=dict(color=COLORS["spread"], width=1.5, dash="dash"),
+            name="Total PnL (realized + unrealized)",
+        ),
+        row=1,
+        col=1,
+    )
+
+    # Row 2: Position
+    pos_colors = [
+        COLORS["long"] if v >= 0 else COLORS["short"] for v in sim["position_usdt"]
+    ]
+    fig.add_trace(
+        go.Scatter(
+            x=sim["ts"],
+            y=sim["position_usdt"],
+            line=dict(color=COLORS["pnl"], width=1.5),
+            fill="tozeroy",
+            fillcolor="rgba(88,166,255,0.08)",
+            name="Position (USDT)",
+            showlegend=True,
+        ),
+        row=2,
+        col=1,
+    )
+    fig.add_hline(y=0, line_color=COLORS["grid"], row=2, col=1)
+
+    # Row 3: Spread + signals
+    fig.add_trace(
+        go.Scatter(
+            x=sim["ts"],
+            y=sim["spread_bps"],
+            line=dict(color=COLORS["spread"], width=1),
+            name="Spread (bps)",
+            showlegend=True,
+        ),
+        row=3,
+        col=1,
+    )
+    fig.add_hline(
+        y=min_spread_bps,
+        line_dash="dash",
+        line_color=COLORS["brl"],
+        opacity=0.5,
+        row=3,
+        col=1,
+    )
+    fig.add_hline(
+        y=-min_spread_bps,
+        line_dash="dash",
+        line_color=COLORS["brl"],
+        opacity=0.5,
+        row=3,
+        col=1,
+    )
+    fig.add_hline(y=0, line_color=COLORS["grid"], row=3, col=1)
+
+    # Trade markers
+    sells_brl = sim[sim["action"] == "sell_brl"]
+    sells_usdt = sim[sim["action"] == "sell_usdt"]
+    if not sells_brl.empty:
+        fig.add_trace(
+            go.Scatter(
+                x=sells_brl["ts"],
+                y=sells_brl["spread_bps"],
+                mode="markers",
+                marker=dict(color=COLORS["short"], size=3, symbol="triangle-down"),
+                name="Sell BRL",
+                showlegend=True,
+            ),
+            row=3,
+            col=1,
+        )
+    if not sells_usdt.empty:
+        fig.add_trace(
+            go.Scatter(
+                x=sells_usdt["ts"],
+                y=sells_usdt["spread_bps"],
+                mode="markers",
+                marker=dict(color=COLORS["long"], size=3, symbol="triangle-up"),
+                name="Sell USDT",
+                showlegend=True,
+            ),
+            row=3,
+            col=1,
+        )
+
+    fig.update_layout(
+        **LAYOUT_BASE,
+        title=dict(
+            text=(
+                f"<b>Quoting Strategy Sim</b>"
+                f"  |  ${trade_size_usdt:.0f}/trade"
+                f"  |  fee: {fee_bps:.0f}bps"
+                f"  |  min: {min_spread_bps:.0f}bps"
+                f"  |  PnL: ${final_pnl:+.2f}"
+                f"  |  Pos: ${final_position:+,.0f}"
+            ),
+            font=dict(color=COLORS["text"], size=12),
+            x=0.5,
+        ),
+        width=1300,
+        height=900,
+    )
+    fig.update_yaxes(title_text="USDT", tickformat=",.2f", row=1, col=1)
+    fig.update_yaxes(title_text="USDT", tickformat=",.0f", row=2, col=1)
+    fig.update_yaxes(title_text="bps", row=3, col=1)
+    for ann in fig.layout.annotations:
+        ann.font = dict(color=COLORS["text_dim"], size=11)
+    _style_axes(fig, 3)
+    return fig
+
+
+async def run(config: Config, context: ContextTypes.DEFAULT_TYPE) -> RoutineResult:
+    chat_id = context._chat_id
+    client = await get_client(chat_id, context=context)
+    if not client:
+        return RoutineResult(text="No server available")
+
+    # Fetch 1s candles in parallel
+    btc_usdt, btc_brl, usdt_brl = await asyncio.gather(
+        _fetch_candles(
+            client, config.connector_name, "BTC-USDT", "1s", config.lookback_seconds
+        ),
+        _fetch_candles(
+            client, config.connector_name, "BTC-BRL", "1s", config.lookback_seconds
+        ),
+        _fetch_candles(
+            client, config.connector_name, "USDT-BRL", "1s", config.lookback_seconds
+        ),
+    )
+
+    for name, df in [
+        ("BTC-USDT", btc_usdt),
+        ("BTC-BRL", btc_brl),
+        ("USDT-BRL", usdt_brl),
+    ]:
+        if df.empty:
+            return RoutineResult(text=f"No 1s data for {name}")
+
+    # Compute spread
+    merged = _merge_spread(btc_usdt, btc_brl, usdt_brl)
+    if merged.empty:
+        return RoutineResult(text="No overlapping data between pairs")
+
+    # Run strategy simulation
+    sim = simulate_quoting(
+        merged,
+        trade_size_usdt=config.trade_size_usdt,
+        fee_bps=config.fee_bps,
+        min_spread_bps=config.min_spread_bps,
+        max_position_usdt=config.max_position_usdt,
+    )
+
+    # Build charts
+    spread_fig = build_spread_chart(merged)
+    strategy_fig = build_strategy_chart(
+        sim, config.fee_bps, config.min_spread_bps, config.trade_size_usdt
+    )
+
+    # Summary stats
+    duration_min = (merged["ts"].iloc[-1] - merged["ts"].iloc[0]).total_seconds() / 60
+    avg_spread = merged["spread_pct"].mean()
+    std_spread = merged["spread_pct"].std()
+    curr_spread = merged["spread_pct"].iloc[-1]
+    total_trades = int(sim["trade_count"].iloc[-1])
+    final_captured = sim["cum_captured"].iloc[-1]
+    final_fees = sim["cum_fees"].iloc[-1]
+    final_pnl = sim["cum_pnl"].iloc[-1]
+    final_position = sim["position_usdt"].iloc[-1]
+    final_total = sim["total_pnl"].iloc[-1]
+
+    # Spread distribution
+    above_thresh = (merged["spread_bps"].abs() > config.min_spread_bps).mean() * 100
+    time_positive = (merged["spread_pct"] > 0).mean() * 100
+
+    # Annualize PnL
+    hours = duration_min / 60
+    if hours > 0:
+        pnl_per_hour = final_pnl / hours
+        projected_daily = pnl_per_hour * 24
+        projected_monthly = projected_daily * 30
+    else:
+        pnl_per_hour = projected_daily = projected_monthly = 0
+
+    text = "\n".join(
+        [
+            "BTC-BRL Arbitrage Analysis",
+            f"Window: {duration_min:.0f} min ({len(merged):,} ticks)",
+            "",
+            "Spread Stats:",
+            f"  Current: {curr_spread:+.4f}%  ({curr_spread*100:+.2f} bps)",
+            f"  Average: {avg_spread:+.4f}%",
+            f"  Std Dev: {std_spread:.4f}%",
+            f"  Time |spread| > {config.min_spread_bps:.0f}bps: {above_thresh:.1f}%",
+            f"  Time BRL premium: {time_positive:.1f}%",
+            "",
+            f"Strategy Sim (${config.trade_size_usdt:.0f}/trade, {config.fee_bps:.0f}bps fee, >{config.min_spread_bps:.0f}bps):",
+            f"  Trades: {total_trades}",
+            f"  Gross captured: ${final_captured:.2f}",
+            f"  Fees paid: ${final_fees:.2f}",
+            f"  Net realized PnL: ${final_pnl:+.2f}",
+            f"  Current position: ${final_position:+,.0f}",
+            f"  Total PnL (incl. unrealized): ${final_total:+.2f}",
+            "",
+            "Projections (if conditions persist):",
+            f"  Per hour: ${pnl_per_hour:+.2f}",
+            f"  Per day: ${projected_daily:+.2f}",
+            f"  Per month: ${projected_monthly:+.2f}",
+        ]
+    )
+
+    # Export primary chart
+    img_bytes = spread_fig.to_image(format="png", width=1300, height=700, scale=2)
+    chart = io.BytesIO(img_bytes)
+
+    # Report
+    from condor.reports import ReportBuilder
+
+    builder = ReportBuilder("BTC-BRL Arbitrage")
+    builder.source("routine", "btc_brl_arbitrage").tags(
+        ["btc", "brl", "arbitrage", "strategy"]
+    )
+    builder.markdown(text)
+    builder.plotly(spread_fig)
+    builder.plotly(strategy_fig)
+    await builder.save()
+
+    return RoutineResult(text=text, chart_image=chart)
diff --git a/agents/brigado/routines/config_analyzer.py b/agents/brigado/routines/config_analyzer.py
new file mode 100644
index 00000000..ca811cd0
--- /dev/null
+++ b/agents/brigado/routines/config_analyzer.py
@@ -0,0 +1,772 @@
+"""PMM Config Analyzer — Compare controller configs side by side, highlight differences."""
+
+CATEGORY = "Bot Analysis"
+
+import asyncio
+import logging
+import re
+from collections import defaultdict
+
+import plotly.graph_objects as go
+from pydantic import BaseModel, Field
+from telegram.ext import ContextTypes
+
+from config_manager import get_config_manager
+
+logger = logging.getLogger(__name__)
+
+_DARK_BG = "#1a1a2e"
+_DARK_PAPER = "#16213e"
+_GREEN = "#00d4aa"
+_RED = "#ff6b6b"
+_BLUE = "#58a6ff"
+_YELLOW = "#ffdd57"
+_COLORS = [
+    "#58a6ff",
+    "#00d4aa",
+    "#ff6b6b",
+    "#ffdd57",
+    "#c084fc",
+    "#fb923c",
+    "#38bdf8",
+    "#f472b6",
+]
+
+# Parameters to always skip in comparison (noise)
+SKIP_PARAMS = {"id", "controller_type", "controller_name", "manual_kill_switch"}
+
+# Parameters to highlight when different (key tuning params)
+KEY_PARAMS = {
+    "buy_spreads",
+    "sell_spreads",
+    "buy_amounts_pct",
+    "sell_amounts_pct",
+    "total_amount_quote",
+    "stop_loss",
+    "take_profit",
+    "time_limit",
+    "executor_refresh_time",
+    "cooldown_time",
+    "leverage",
+    "dca_spreads",
+    "dca_amounts",
+    "trailing_stop",
+    "executor_activation_bounds",
+    "top_executor_refresh_time",
+    "position_rebalance_threshold_pct",
+}
+
+
+class Config(BaseModel):
+    """Analyze and compare PMM controller configs — saved vs running bots."""
+
+    server_name: str = Field(
+        default="brigado_2",
+        description="Server to connect to",
+    )
+    controller_type: str = Field(
+        default="",
+        description="Filter by controller type (e.g. 'market_making'). Empty = all types.",
+    )
+    controller_filter: str = Field(
+        default="pmm_mister",
+        description="Filter by config name or controller_name containing this string. Empty = all.",
+    )
+    pair_filter: str = Field(
+        default="",
+        description="Filter by trading pair (e.g. 'BRL', 'BTC-BRL'). Empty = all.",
+    )
+    running_only: bool = Field(
+        default=False,
+        description="Show only configs that are currently running in active bots.",
+    )
+    show_common: bool = Field(
+        default=False,
+        description="Include parameters that are the same across all configs (verbose mode).",
+    )
+
+
+def _short_name(config_name: str) -> str:
+    """Shorten config name for display."""
+    name = config_name
+    name = re.sub(r"^mm_", "", name)
+    name = re.sub(r"pmm_?mister_?", "pm_", name)
+    name = re.sub(r"^(binance|okx|bybit|kucoin)(_perpetual)?_", "", name)
+    name = re.sub(r"config[_]?(\d+)", r"c\1", name)
+    while "__" in name:
+        name = name.replace("__", "_")
+    return name.strip("_") or config_name[:25]
+
+
+def _fmt_value(v) -> str:
+    """Format a config value for display."""
+    if v is None:
+        return "—"
+    if isinstance(v, bool):
+        return "✓" if v else "✗"
+    if isinstance(v, float):
+        if v < 0.001:
+            return f"{v:.5f}"
+        if v < 0.01:
+            return f"{v:.4f}"
+        return f"{v:.3f}" if v < 10 else f"{v:.1f}"
+    if isinstance(v, list):
+        return ", ".join(_fmt_value(x) for x in v)
+    if isinstance(v, dict):
+        parts = [f"{k}={_fmt_value(vv)}" for k, vv in v.items()]
+        return " | ".join(parts)
+    return str(v)
+
+
+def _normalize_value(v):
+    """Normalize values for comparison."""
+    if v is None:
+        return None
+    if isinstance(v, str):
+        try:
+            return float(v)
+        except ValueError:
+            return v.strip().lower()
+    if isinstance(v, list):
+        return [_normalize_value(x) for x in v]
+    if isinstance(v, dict):
+        return {k: _normalize_value(vv) for k, vv in v.items()}
+    return v
+
+
+async def run(config: Config, context: ContextTypes.DEFAULT_TYPE) -> str:
+    # Connect to server
+    client = await get_config_manager().get_client(config.server_name)
+    if not client:
+        return f"Could not connect to server '{config.server_name}'"
+
+    # Fetch all data in parallel
+    all_configs_list, bots_data = await asyncio.gather(
+        client.controllers.list_controller_configs(),
+        _get_bots_data(client),
+    )
+
+    # --- Saved configs ---
+    saved_configs = {}
+    filt = config.controller_filter.lower() if config.controller_filter else ""
+    for cfg_meta in all_configs_list or []:
+        cname = cfg_meta.get("id") or cfg_meta.get("config_name", "")
+        ctype = cfg_meta.get("controller_type", "")
+        ctrl_name = cfg_meta.get("controller_name", "")
+
+        if (
+            config.controller_type
+            and config.controller_type.lower() not in ctype.lower()
+        ):
+            continue
+        if filt and filt not in cname.lower() and filt not in ctrl_name.lower():
+            continue
+
+        try:
+            cfg_data = await client.controllers.get_controller_config(cname)
+            # Also check controller_name inside the full config data
+            if filt and filt not in cname.lower():
+                inner_ctrl = cfg_data.get("controller_name", "")
+                if filt not in inner_ctrl.lower():
+                    continue
+            if config.pair_filter:
+                pair = cfg_data.get("trading_pair", "")
+                if config.pair_filter.upper() not in pair.upper():
+                    continue
+            saved_configs[cname] = cfg_data
+        except Exception as e:
+            logger.warning(f"Failed to fetch config {cname}: {e}")
+
+    # --- Running bot configs ---
+    running_config_ids = set()
+    running_configs = {}
+    for bot_name in bots_data or {}:
+        try:
+            bot_cfgs = await client.controllers.get_bot_controller_configs(bot_name)
+            if isinstance(bot_cfgs, list):
+                for cfg in bot_cfgs:
+                    cid = cfg.get("id") or cfg.get("controller_id", "")
+                    ctype = cfg.get("controller_type", "")
+                    if (
+                        config.controller_type
+                        and config.controller_type.lower() not in ctype.lower()
+                    ):
+                        continue
+                    ctrl_name_inner = cfg.get("controller_name", "")
+                    if (
+                        filt
+                        and filt not in cid.lower()
+                        and filt not in ctrl_name_inner.lower()
+                    ):
+                        continue
+                    if config.pair_filter:
+                        pair = cfg.get("trading_pair", "")
+                        if config.pair_filter.upper() not in pair.upper():
+                            continue
+                    running_configs[cid] = cfg
+                    running_config_ids.add(cid)
+        except Exception as e:
+            logger.warning(f"Failed to fetch bot configs for {bot_name}: {e}")
+
+    # Merge all configs with status prefix
+    all_configs = {}
+    for name, cfg in saved_configs.items():
+        prefix = "🟢" if name in running_config_ids else "🔵"
+        all_configs[f"{prefix} {name}"] = cfg
+    for cid, cfg in running_configs.items():
+        if cid not in saved_configs:
+            all_configs[f"🟢 {cid}"] = cfg
+
+    # Filter to running only if requested
+    if config.running_only:
+        all_configs = {
+            k: v for k, v in all_configs.items() if k.startswith("\U0001f7e2")
+        }
+
+    if not all_configs:
+        filters = []
+        if config.controller_type:
+            filters.append(f"type={config.controller_type}")
+        if config.controller_filter:
+            filters.append(f"filter={config.controller_filter}")
+        if config.pair_filter:
+            filters.append(f"pair={config.pair_filter}")
+        return f"No configs found matching: {', '.join(filters) if filters else 'any'}"
+
+    # --- Build comparison ---
+    all_params = set()
+    for cfg in all_configs.values():
+        all_params.update(cfg.keys())
+    all_params -= SKIP_PARAMS
+
+    # Sort: key params first, then alphabetical
+    sorted_params = sorted(all_params, key=lambda p: (0 if p in KEY_PARAMS else 1, p))
+
+    # Find which params differ
+    diff_params = set()
+    for param in sorted_params:
+        values = [_normalize_value(cfg.get(param)) for cfg in all_configs.values()]
+        non_none = [v for v in values if v is not None]
+        if len(set(str(v) for v in non_none)) > 1:
+            diff_params.add(param)
+
+    # Group configs by trading pair
+    pair_groups = defaultdict(dict)
+    for label, cfg in all_configs.items():
+        pair = cfg.get("trading_pair", "unknown")
+        pair_groups[pair][label] = cfg
+
+    num_running = sum(1 for l in all_configs if l.startswith("🟢"))
+
+    # --- Build HTML report ---
+    from condor.reports import ReportBuilder
+
+    builder = ReportBuilder("PMM Config Analyzer")
+    builder.source("routine", "config_analyzer").tags(["configs", "pmm", "analysis"])
+    builder.manual_order()
+
+    # KPIs
+    builder.kpi("Total Configs", str(len(all_configs)))
+    builder.kpi("Running", str(num_running), trend="up" if num_running else "neutral")
+    builder.kpi("Saved Only", str(len(all_configs) - num_running))
+    builder.kpi(
+        "Diffs Found",
+        str(len(diff_params)),
+        delta=f"of {len(sorted_params)} params",
+    )
+    builder.kpi("Trading Pairs", str(len(pair_groups)))
+
+    # --- Per-pair comparison tables ---
+    for pair, pair_cfgs in sorted(pair_groups.items(), key=lambda x: -len(x[1])):
+        n_running = sum(1 for l in pair_cfgs if l.startswith("🟢"))
+
+        labels = list(pair_cfgs.keys())
+        shorts = [_short_name(l.replace("🟢 ", "").replace("🔵 ", "")) for l in labels]
+
+        # Find pair-level diffs
+        pair_diff_params = set()
+        for param in sorted_params:
+            values = [_normalize_value(pair_cfgs[l].get(param)) for l in labels]
+            non_none = [v for v in values if v is not None]
+            if len(non_none) > 0 and len(set(str(v) for v in non_none)) > 1:
+                pair_diff_params.add(param)
+
+        heading_md = f"## {pair} ({len(pair_cfgs)} configs, {n_running} running)"
+
+        if len(labels) == 1:
+            # Single config — show full params
+            label = labels[0]
+            cfg = pair_cfgs[label]
+            rows = []
+            for param in sorted_params:
+                val = cfg.get(param)
+                if val is not None:
+                    is_key = "⚡ " if param in KEY_PARAMS else ""
+                    rows.append(
+                        {
+                            "Parameter": f"{is_key}{param}",
+                            "Value": _fmt_value(val),
+                        }
+                    )
+            builder.markdown(f"{heading_md}\n\n**{label}** — single config")
+            if rows:
+                builder.table(rows)
+        else:
+            # Multiple configs — comparison view
+            rows = []
+            for param in sorted_params:
+                values = [pair_cfgs[l].get(param) for l in labels]
+                non_none = [v for v in values if v is not None]
+                if not non_none:
+                    continue
+
+                is_diff = param in pair_diff_params
+                if not config.show_common and not is_diff:
+                    continue
+
+                prefix = (
+                    "🔴 "
+                    if is_diff and param in KEY_PARAMS
+                    else "🟡 " if is_diff else ""
+                )
+                row = {"Parameter": f"{prefix}{param}"}
+                for short, val in zip(shorts, values):
+                    row[short] = _fmt_value(val)
+                rows.append(row)
+
+            note = (
+                f"Showing {len(rows)} differing params. 🔴 = key, 🟡 = other."
+                if not config.show_common
+                else ""
+            )
+            if not rows and not config.show_common:
+                builder.markdown(
+                    f"{heading_md}\n\nAll parameters identical across these configs."
+                )
+            else:
+                builder.markdown(f"{heading_md}\n\n{note}" if note else heading_md)
+                if rows:
+                    builder.table(rows)
+
+    # --- Cross-pair key differences summary ---
+    if len(pair_groups) > 1 and diff_params:
+        cross_sections = []
+        for param in sorted_params:
+            if param not in diff_params or param not in KEY_PARAMS:
+                continue
+            value_groups = defaultdict(list)
+            for label, cfg in all_configs.items():
+                val = _fmt_value(cfg.get(param))
+                short = _short_name(label.replace("🟢 ", "").replace("🔵 ", ""))
+                value_groups[val].append(short)
+            if len(value_groups) <= 1:
+                continue
+            rows = []
+            for val, names in sorted(value_groups.items(), key=lambda x: -len(x[1])):
+                rows.append(
+                    {
+                        "Value": val,
+                        "Count": str(len(names)),
+                        "Configs": ", ".join(names[:8])
+                        + (f" (+{len(names)-8})" if len(names) > 8 else ""),
+                    }
+                )
+            cross_sections.append((param, rows))
+
+        if cross_sections:
+            builder.markdown(
+                "## Cross-Pair Key Differences\n\nKey tuning parameters grouped by distinct values across all configs."
+            )
+            for param, rows in cross_sections:
+                builder.markdown(f"**`{param}`** — {len(rows)} distinct values:")
+                builder.table(rows)
+
+    # --- Charts ---
+    if len(all_configs) > 1:
+        fig_pc = _build_parallel_coords(all_configs, running_config_ids)
+        if fig_pc:
+            builder.plotly(fig_pc)
+
+        fig = _build_spread_chart(all_configs)
+        if fig:
+            builder.plotly(fig)
+
+        fig2 = _build_capital_chart(all_configs)
+        if fig2:
+            builder.plotly(fig2)
+
+    await builder.save()
+
+    # --- Concise plain text summary ---
+    lines = [f"**PMM Config Analyzer** — {config.server_name}", ""]
+    lines.append(
+        f"Found **{len(all_configs)}** configs ({num_running} running, {len(all_configs) - num_running} saved-only)"
+    )
+    lines.append(f"**{len(diff_params)}** parameters differ across configs")
+    lines.append(
+        f"**{len(pair_groups)}** pairs: {', '.join(sorted(pair_groups.keys()))}"
+    )
+    lines.append("")
+
+    for pair, pair_cfgs in sorted(pair_groups.items(), key=lambda x: -len(x[1])):
+        n_r = sum(1 for l in pair_cfgs if l.startswith("🟢"))
+        lines.append(f"- **{pair}**: {len(pair_cfgs)} configs ({n_r} running)")
+
+    lines.append("")
+    lines.append("Full comparison report available in the dashboard.")
+
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+async def _get_bots_data(client) -> dict:
+    try:
+        data = await client.bot_orchestration.get_active_bots_status()
+        if isinstance(data, dict) and "data" in data:
+            return data["data"]
+    except Exception:
+        pass
+    return {}
+
+
+def _build_parallel_coords(all_configs: dict, running_ids: set) -> go.Figure | None:
+    """Parallel coordinates plot (HiPlot-style) for numeric config parameters."""
+    # Extract numeric axes from key params
+    NUMERIC_AXES = [
+        ("total_amount_quote", "Capital", None),
+        (
+            "buy_spreads",
+            "Buy Spread L1 %",
+            lambda v: (v[0] if isinstance(v, list) and v else v) if v else None,
+        ),
+        (
+            "sell_spreads",
+            "Sell Spread L1 %",
+            lambda v: (v[0] if isinstance(v, list) and v else v) if v else None,
+        ),
+        (
+            "buy_spreads",
+            "Buy Spread L2 %",
+            lambda v: (
+                (v[1] if isinstance(v, list) and len(v) > 1 else None) if v else None
+            ),
+        ),
+        (
+            "sell_spreads",
+            "Sell Spread L2 %",
+            lambda v: (
+                (v[1] if isinstance(v, list) and len(v) > 1 else None) if v else None
+            ),
+        ),
+        ("executor_refresh_time", "Refresh Time", None),
+        ("cooldown_time", "Cooldown", None),
+        ("leverage", "Leverage", None),
+        ("stop_loss", "Stop Loss", None),
+        ("take_profit", "Take Profit", None),
+        ("time_limit", "Time Limit", None),
+        ("top_executor_refresh_time", "Top Refresh", None),
+        (
+            "dca_spreads",
+            "DCA Spread L1",
+            lambda v: (v[0] if isinstance(v, list) and v else v) if v else None,
+        ),
+        (
+            "dca_amounts",
+            "DCA Amt L1",
+            lambda v: (v[0] if isinstance(v, list) and v else v) if v else None,
+        ),
+        (
+            "trailing_stop",
+            "Trail Stop",
+            lambda v: (
+                (v.get("activation_price_delta") if isinstance(v, dict) else v)
+                if v
+                else None
+            ),
+        ),
+        (
+            "executor_activation_bounds",
+            "Activation Bounds",
+            lambda v: (v[0] if isinstance(v, list) and v else v) if v else None,
+        ),
+    ]
+
+    # Collect data rows
+    rows = []
+    labels = []
+    for label, cfg in all_configs.items():
+        clean_label = label.replace("\U0001f7e2 ", "").replace("\U0001f535 ", "")
+        is_running = clean_label in running_ids or label.startswith("\U0001f7e2")
+        pair = cfg.get("trading_pair", "unknown")
+        row = {"_running": 1 if is_running else 0, "_pair": pair}
+        for param, axis_name, extractor in NUMERIC_AXES:
+            raw = cfg.get(param)
+            if extractor:
+                val = extractor(raw)
+            else:
+                val = raw
+            try:
+                row[axis_name] = float(val) if val is not None else None
+            except (TypeError, ValueError):
+                row[axis_name] = None
+        rows.append(row)
+        labels.append(_short_name(clean_label))
+
+    if len(rows) < 2:
+        return None
+
+    # Filter axes that have at least 2 distinct non-None values
+    valid_axes = []
+    for _, axis_name, _ in NUMERIC_AXES:
+        vals = [r[axis_name] for r in rows if r[axis_name] is not None]
+        if len(vals) >= 2 and len(set(vals)) > 1:
+            valid_axes.append(axis_name)
+
+    if len(valid_axes) < 2:
+        return None
+
+    # Build color by pair
+    unique_pairs = sorted(set(r["_pair"] for r in rows))
+    pair_to_idx = {p: i for i, p in enumerate(unique_pairs)}
+    color_values = [pair_to_idx[r["_pair"]] for r in rows]
+
+    # Build colorscale from our palette
+    n_pairs = len(unique_pairs)
+    if n_pairs == 1:
+        colorscale = [[0, _BLUE], [1, _BLUE]]
+    else:
+        colorscale = []
+        for i in range(n_pairs):
+            pos = i / (n_pairs - 1)
+            colorscale.append([pos, _COLORS[i % len(_COLORS)]])
+
+    # Fill None values with axis min (so lines don't break)
+    for axis_name in valid_axes:
+        vals = [r[axis_name] for r in rows if r[axis_name] is not None]
+        fill = min(vals) if vals else 0
+        for r in rows:
+            if r[axis_name] is None:
+                r[axis_name] = fill
+
+    # Build dimensions
+    dimensions = []
+    for axis_name in valid_axes:
+        vals = [r[axis_name] for r in rows]
+        # Multiply spread values by 100 for readability
+        if "%" in axis_name:
+            vals = [v * 100 for v in vals]
+        dimensions.append(
+            dict(
+                label=axis_name,
+                values=vals,
+                range=(
+                    [min(vals), max(vals)]
+                    if min(vals) != max(vals)
+                    else [min(vals) - 1, max(vals) + 1]
+                ),
+            )
+        )
+
+    fig = go.Figure(
+        data=go.Parcoords(
+            line=dict(
+                color=color_values,
+                colorscale=colorscale,
+                showscale=False,
+            ),
+            dimensions=dimensions,
+            customdata=labels,
+        )
+    )
+
+    # Add pair legend via invisible scatter traces
+    for i, pair in enumerate(unique_pairs):
+        fig.add_trace(
+            go.Scatter(
+                x=[None],
+                y=[None],
+                mode="markers",
+                marker=dict(size=10, color=_COLORS[i % len(_COLORS)]),
+                name=pair,
+                showlegend=True,
+            )
+        )
+
+    fig.update_layout(
+        title=dict(
+            text=f"Config Parameter Space ({len(rows)} configs, {len(valid_axes)} axes)",
+            font=dict(color="#e6edf3", size=14),
+            x=0.5,
+        ),
+        paper_bgcolor=_DARK_PAPER,
+        plot_bgcolor=_DARK_BG,
+        font=dict(color="#ccc", size=11),
+        margin=dict(l=80, r=80, t=80, b=40),
+        width=1400,
+        height=600,
+        legend=dict(
+            orientation="h", y=-0.05, x=0.5, xanchor="center", font=dict(size=12)
+        ),
+    )
+    return fig
+
+
+def _build_spread_chart(all_configs: dict) -> go.Figure | None:
+    """Grouped bar chart comparing buy/sell spreads across configs."""
+
+    def _to_list(v) -> list:
+        if v is None:
+            return []
+        if isinstance(v, (int, float)):
+            return [float(v)]
+        if isinstance(v, list):
+            return [float(x) for x in v]
+        return []
+
+    configs_with_spreads = []
+    for label, cfg in all_configs.items():
+        buy = _to_list(cfg.get("buy_spreads"))
+        sell = _to_list(cfg.get("sell_spreads"))
+        if buy or sell:
+            short = _short_name(label.replace("🟢 ", "").replace("🔵 ", ""))
+            pair = cfg.get("trading_pair", "")
+            configs_with_spreads.append(
+                {
+                    "name": short,
+                    "pair": pair,
+                    "buy_l1": buy[0] * 100 if len(buy) >= 1 else 0,
+                    "sell_l1": sell[0] * 100 if len(sell) >= 1 else 0,
+                    "buy_l2": buy[1] * 100 if len(buy) >= 2 else 0,
+                    "sell_l2": sell[1] * 100 if len(sell) >= 2 else 0,
+                }
+            )
+
+    if not configs_with_spreads:
+        return None
+
+    configs_with_spreads.sort(key=lambda c: (c["pair"], c["name"]))
+    names = [c["name"] for c in configs_with_spreads]
+
+    fig = go.Figure()
+    fig.add_trace(
+        go.Bar(
+            x=names,
+            y=[c["buy_l1"] for c in configs_with_spreads],
+            name="Buy L1",
+            marker_color=_GREEN,
+            opacity=0.9,
+        )
+    )
+    fig.add_trace(
+        go.Bar(
+            x=names,
+            y=[c["sell_l1"] for c in configs_with_spreads],
+            name="Sell L1",
+            marker_color=_RED,
+            opacity=0.9,
+        )
+    )
+
+    has_l2 = any(c["buy_l2"] > 0 or c["sell_l2"] > 0 for c in configs_with_spreads)
+    if has_l2:
+        fig.add_trace(
+            go.Bar(
+                x=names,
+                y=[c["buy_l2"] for c in configs_with_spreads],
+                name="Buy L2",
+                marker_color=_GREEN,
+                opacity=0.5,
+            )
+        )
+        fig.add_trace(
+            go.Bar(
+                x=names,
+                y=[c["sell_l2"] for c in configs_with_spreads],
+                name="Sell L2",
+                marker_color=_RED,
+                opacity=0.5,
+            )
+        )
+
+    fig.update_layout(
+        title=dict(
+            text="Spread Levels by Config (%)",
+            font=dict(color="#e6edf3", size=14),
+            x=0.5,
+        ),
+        paper_bgcolor=_DARK_PAPER,
+        plot_bgcolor=_DARK_BG,
+        font=dict(color="#ccc", size=10),
+        barmode="group",
+        yaxis=dict(gridcolor="#2a2a4a", title="Spread %"),
+        xaxis=dict(gridcolor="#2a2a4a", tickangle=-45),
+        legend=dict(orientation="h", y=1.1, x=0.5, xanchor="center"),
+        margin=dict(l=60, r=40, t=60, b=120),
+        width=1200,
+        height=500,
+    )
+    return fig
+
+
+def _build_capital_chart(all_configs: dict) -> go.Figure | None:
+    """Horizontal bar chart: capital allocation per config, colored by pair."""
+    data = []
+    for label, cfg in all_configs.items():
+        amt = float(cfg.get("total_amount_quote", 0) or 0)
+        if amt <= 0:
+            continue
+        short = _short_name(label.replace("🟢 ", "").replace("🔵 ", ""))
+        pair = cfg.get("trading_pair", "")
+        is_running = label.startswith("🟢")
+        data.append({"name": short, "pair": pair, "amount": amt, "running": is_running})
+
+    if not data:
+        return None
+
+    data.sort(key=lambda d: (d["pair"], d["amount"]))
+
+    unique_pairs = list(dict.fromkeys(d["pair"] for d in data))
+    pair_colors = {p: _COLORS[i % len(_COLORS)] for i, p in enumerate(unique_pairs)}
+
+    fig = go.Figure()
+    for pair in unique_pairs:
+        pair_data = [d for d in data if d["pair"] == pair]
+        fig.add_trace(
+            go.Bar(
+                y=[d["name"] for d in pair_data],
+                x=[d["amount"] for d in pair_data],
+                orientation="h",
+                name=pair,
+                marker_color=pair_colors[pair],
+                opacity=0.85,
+                text=[
+                    f"{'🟢' if d['running'] else ''} {d['amount']:,.0f}"
+                    for d in pair_data
+                ],
+                textposition="auto",
+            )
+        )
+
+    height = max(400, len(data) * 22 + 100)
+    fig.update_layout(
+        title=dict(
+            text="Capital Allocation by Config (quote currency)",
+            font=dict(color="#e6edf3", size=14),
+            x=0.5,
+        ),
+        paper_bgcolor=_DARK_PAPER,
+        plot_bgcolor=_DARK_BG,
+        font=dict(color="#ccc", size=10),
+        barmode="stack",
+        xaxis=dict(gridcolor="#2a2a4a", title="Amount (quote)"),
+        yaxis=dict(gridcolor="#2a2a4a"),
+        legend=dict(orientation="h", y=1.05, x=0.5, xanchor="center"),
+        margin=dict(l=150, r=40, t=60, b=50),
+        width=1200,
+        height=height,
+    )
+    return fig
diff --git a/agents/brigado/routines/spot_markets.py b/agents/brigado/routines/spot_markets.py
new file mode 100644
index 00000000..a3795b99
--- /dev/null
+++ b/agents/brigado/routines/spot_markets.py
@@ -0,0 +1,458 @@
+"""Spot market discovery — top markets by volume across quote currencies with rebate focus."""
+
+CATEGORY = "Market Data"
+
+import asyncio
+import logging
+from typing import Any
+
+import aiohttp
+import pandas as pd
+import plotly.graph_objects as go
+from plotly.subplots import make_subplots
+from pydantic import BaseModel, Field
+from telegram.ext import ContextTypes
+
+from config_manager import get_client
+from routines.base import RoutineResult
+
+logger = logging.getLogger(__name__)
+
+BINANCE_SPOT_TICKER = "https://api.binance.com/api/v3/ticker/24hr"
+
+# Quote currencies we care about
+REBATE_QUOTES = {
+    "BRL",
+    "ARS",
+    "MXN",
+    "EUR",
+    "PLN",
+    "JPY",
+    "TRY",
+    "RON",
+    "UAH",
+    "ZAR",
+    "NGN",
+    "COP",
+}
+STABLE_QUOTES = {"USDT", "USDC", "BUSD", "FDUSD", "TUSD"}
+
+# Stablecoins / wrapped tokens to exclude as base
+EXCLUDED_BASES = {"USDT", "USDC", "BUSD", "TUSD", "FDUSD", "DAI", "BFUSD"}
+
+COLORS = {
+    "bg_paper": "#0d1117",
+    "bg_plot": "#161b22",
+    "grid": "#21262d",
+    "text": "#c9d1d9",
+    "text_dim": "#8b949e",
+    "green": "#3fb950",
+    "red": "#f85149",
+    "blue": "#58a6ff",
+    "yellow": "#f0b90b",
+    "purple": "#bc8cff",
+    "orange": "#f78166",
+}
+
+QUOTE_COLORS = {
+    "BRL": "#3fb950",
+    "USDT": "#e6e6e6",
+    "FDUSD": "#58a6ff",
+    "USDC": "#2775ca",
+    "ARS": "#75b5f0",
+    "MXN": "#f0b90b",
+    "EUR": "#f78166",
+    "PLN": "#bc8cff",
+    "JPY": "#ff7b72",
+    "TRY": "#d2a8ff",
+    "RON": "#7ee787",
+    "UAH": "#79c0ff",
+    "ZAR": "#ffa657",
+    "NGN": "#56d364",
+    "COP": "#e3b341",
+}
+
+
+class Config(BaseModel):
+    """Spot market discovery — top pairs by volume, FIAT rebate markets, and USDT leaders."""
+
+    top_n: int = Field(default=50, description="Top N markets per section")
+    min_volume_usd: float = Field(
+        default=100_000, description="Min 24h volume (USD) for FIAT pairs"
+    )
+    min_volume_usdt: float = Field(
+        default=5_000_000, description="Min 24h volume (USD) for USDT pairs"
+    )
+    focus_quote: str = Field(
+        default="BRL", description="Primary FIAT quote to highlight"
+    )
+
+
+def _parse_quote(symbol: str, known_quotes: set[str]) -> tuple[str, str] | None:
+    """Parse a Binance symbol into (base, quote) using known quote list."""
+    for q in sorted(known_quotes, key=len, reverse=True):
+        if symbol.endswith(q):
+            base = symbol[: -len(q)]
+            if base:
+                return base, q
+    return None
+
+
+async def fetch_spot_tickers() -> list[dict]:
+    """Fetch all 24h tickers from Binance spot."""
+    async with aiohttp.ClientSession() as session:
+        async with session.get(BINANCE_SPOT_TICKER) as resp:
+            resp.raise_for_status()
+            return await resp.json()
+
+
+def categorize_tickers(tickers: list[dict]) -> dict[str, list[dict]]:
+    """Parse and categorize tickers by quote currency."""
+    all_quotes = REBATE_QUOTES | STABLE_QUOTES | {"BTC", "ETH", "BNB"}
+    by_quote: dict[str, list[dict]] = {}
+
+    for t in tickers:
+        symbol = t.get("symbol", "")
+        parsed = _parse_quote(symbol, all_quotes)
+        if not parsed:
+            continue
+        base, quote = parsed
+        if base in EXCLUDED_BASES:
+            continue
+
+        quote_vol = float(t.get("quoteVolume", 0))
+        if quote_vol <= 0:
+            continue
+
+        entry = {
+            "symbol": symbol,
+            "base": base,
+            "quote": quote,
+            "trading_pair": f"{base}-{quote}",
+            "price": float(t.get("lastPrice", 0)),
+            "price_change_pct": float(t.get("priceChangePercent", 0)),
+            "volume_24h": float(t.get("volume", 0)),
+            "quote_volume_24h": quote_vol,
+            "trades_24h": int(t.get("count", 0)),
+        }
+        by_quote.setdefault(quote, []).append(entry)
+
+    # Sort each group by quote volume
+    for q in by_quote:
+        by_quote[q].sort(key=lambda x: x["quote_volume_24h"], reverse=True)
+
+    return by_quote
+
+
+async def _fetch_usdt_rates(tickers: list[dict]) -> dict[str, float]:
+    """Extract USDT rates for fiat currencies from ticker data."""
+    rates = {"USDT": 1.0, "USDC": 1.0, "FDUSD": 1.0, "BUSD": 1.0, "TUSD": 1.0}
+    # BTC-USDT price for cross-conversion
+    btc_usdt = 0.0
+    for t in tickers:
+        sym = t.get("symbol", "")
+        price = float(t.get("lastPrice", 0))
+        if sym == "BTCUSDT":
+            btc_usdt = price
+        # Direct USDT/FIAT pairs (e.g., USDTBRL → 1 USDT = X BRL)
+        if sym.startswith("USDT") and price > 0:
+            fiat = sym[4:]
+            if fiat in REBATE_QUOTES:
+                rates[fiat] = 1.0 / price  # BRL per USDT → USDT per BRL
+    # Also check FIAT/USDT pairs (unlikely on Binance but just in case)
+    for t in tickers:
+        sym = t.get("symbol", "")
+        price = float(t.get("lastPrice", 0))
+        if sym.endswith("USDT") and price > 0:
+            base = sym[:-4]
+            if base in REBATE_QUOTES and base not in rates:
+                rates[base] = price
+    return rates
+
+
+def format_volume(v: float) -> str:
+    if v >= 1_000_000_000:
+        return f"${v / 1_000_000_000:.1f}B"
+    if v >= 1_000_000:
+        return f"${v / 1_000_000:.1f}M"
+    if v >= 1_000:
+        return f"${v / 1_000:.0f}K"
+    return f"${v:.0f}"
+
+
+def _build_report(
+    by_quote: dict[str, list[dict]],
+    usdt_rates: dict[str, float],
+    config: Config,
+) -> tuple[str, go.Figure, list[dict]]:
+    """Build text summary, chart, and table data."""
+
+    # --- Section 1: Focus FIAT quote (BRL by default) ---
+    focus = config.focus_quote.upper()
+    focus_pairs = by_quote.get(focus, [])
+    focus_rate = usdt_rates.get(focus, 0)
+
+    # --- Section 2: All FIAT markets summary ---
+    fiat_summary = []
+    for q in sorted(REBATE_QUOTES):
+        pairs = by_quote.get(q, [])
+        if not pairs:
+            continue
+        rate = usdt_rates.get(q, 0)
+        total_vol_usdt = (
+            sum(p["quote_volume_24h"] * rate for p in pairs) if rate > 0 else 0
+        )
+        fiat_summary.append(
+            {
+                "quote": q,
+                "pair_count": len(pairs),
+                "total_volume_usdt": total_vol_usdt,
+                "top_pair": pairs[0]["trading_pair"] if pairs else "-",
+                "top_volume": (
+                    pairs[0]["quote_volume_24h"] * rate if pairs and rate > 0 else 0
+                ),
+            }
+        )
+    fiat_summary.sort(key=lambda x: x["total_volume_usdt"], reverse=True)
+
+    # --- Section 3: Top USDT pairs ---
+    usdt_pairs = [
+        p
+        for p in by_quote.get("USDT", [])
+        if p["quote_volume_24h"] >= config.min_volume_usdt
+    ]
+    usdt_top = usdt_pairs[: config.top_n]
+
+    # --- Build text ---
+    lines = []
+
+    # FIAT overview
+    lines.append("FIAT MARKETS OVERVIEW (Rebate Eligible)")
+    lines.append("-" * 45)
+    total_fiat_vol = sum(f["total_volume_usdt"] for f in fiat_summary)
+    lines.append(f"Total FIAT volume: {format_volume(total_fiat_vol)} USDT equiv.")
+    lines.append("")
+    for f in fiat_summary:
+        lines.append(
+            f"  {f['quote']:>4s}: {f['pair_count']:3d} pairs | "
+            f"Vol: {format_volume(f['total_volume_usdt']):>8s} | "
+            f"Top: {f['top_pair']}"
+        )
+
+    # Focus FIAT detail
+    if focus_pairs and focus_rate > 0:
+        filtered = [
+            p
+            for p in focus_pairs
+            if p["quote_volume_24h"] * focus_rate >= config.min_volume_usd
+        ]
+        lines.append("")
+        lines.append(f"TOP {focus}-QUOTED MARKETS (Rebates)")
+        lines.append("-" * 45)
+        for i, p in enumerate(filtered[: config.top_n], 1):
+            vol_usdt = p["quote_volume_24h"] * focus_rate
+            chg = p["price_change_pct"]
+            chg_s = f"+{chg:.1f}%" if chg >= 0 else f"{chg:.1f}%"
+            lines.append(
+                f"  {i:2d}. {p['trading_pair']:<12s} "
+                f"Vol: {format_volume(vol_usdt):>8s}  "
+                f"24h: {chg_s:>7s}  "
+                f"Trades: {p['trades_24h']:,}"
+            )
+
+    # Top USDT
+    lines.append("")
+    lines.append(f"TOP {config.top_n} USDT-QUOTED MARKETS")
+    lines.append("-" * 45)
+    for i, p in enumerate(usdt_top, 1):
+        chg = p["price_change_pct"]
+        chg_s = f"+{chg:.1f}%" if chg >= 0 else f"{chg:.1f}%"
+        lines.append(
+            f"  {i:2d}. {p['trading_pair']:<12s} "
+            f"Vol: {format_volume(p['quote_volume_24h']):>8s}  "
+            f"24h: {chg_s:>7s}  "
+            f"Trades: {p['trades_24h']:,}"
+        )
+
+    text = "\n".join(lines)
+
+    # --- Chart: two panels ---
+    fig = make_subplots(
+        rows=2,
+        cols=1,
+        subplot_titles=[
+            f"FIAT Market Volume (USDT equiv.)",
+            f"Top 30 USDT Markets — Volume vs 24h Change",
+        ],
+        row_heights=[0.35, 0.65],
+        vertical_spacing=0.12,
+    )
+
+    # Panel 1: FIAT volume bar chart
+    if fiat_summary:
+        quotes = [f["quote"] for f in fiat_summary]
+        volumes = [f["total_volume_usdt"] for f in fiat_summary]
+        bar_colors = [QUOTE_COLORS.get(q, "#8b949e") for q in quotes]
+        fig.add_trace(
+            go.Bar(
+                x=quotes,
+                y=volumes,
+                marker_color=bar_colors,
+                text=[format_volume(v) for v in volumes],
+                textposition="outside",
+                textfont=dict(size=9, color=COLORS["text"]),
+                hovertemplate="%{x}: %{y:,.0f} USDT<extra></extra>",
+                showlegend=False,
+            ),
+            row=1,
+            col=1,
+        )
+
+    # Panel 2: Scatter — volume vs price change for top USDT
+    scatter_data = usdt_top[:30]
+    if scatter_data:
+        volumes_s = [p["quote_volume_24h"] for p in scatter_data]
+        changes = [p["price_change_pct"] for p in scatter_data]
+        labels = [p["base"] for p in scatter_data]
+        scatter_colors = [COLORS["green"] if c >= 0 else COLORS["red"] for c in changes]
+
+        fig.add_trace(
+            go.Scatter(
+                x=changes,
+                y=volumes_s,
+                mode="markers+text",
+                marker=dict(
+                    color=scatter_colors,
+                    size=[max(8, min(25, v / max(volumes_s) * 25)) for v in volumes_s],
+                    line=dict(width=1, color=COLORS["bg_paper"]),
+                ),
+                text=labels,
+                textposition="top center",
+                textfont=dict(size=8, color=COLORS["text_dim"]),
+                hovertemplate="%{text}<br>Vol: %{y:,.0f}<br>Chg: %{x:.1f}%<extra></extra>",
+                showlegend=False,
+            ),
+            row=2,
+            col=1,
+        )
+
+    fig.update_layout(
+        paper_bgcolor=COLORS["bg_paper"],
+        plot_bgcolor=COLORS["bg_plot"],
+        font=dict(color=COLORS["text_dim"], size=10),
+        margin=dict(l=60, r=30, t=60, b=40),
+        height=800,
+    )
+    for i in range(1, 3):
+        fig.update_xaxes(gridcolor=COLORS["grid"], row=i, col=1)
+        fig.update_yaxes(gridcolor=COLORS["grid"], row=i, col=1)
+    fig.update_yaxes(type="log", title="Volume (USDT)", row=1, col=1)
+    fig.update_yaxes(type="log", title="Volume 24h (USDT)", row=2, col=1)
+    fig.update_xaxes(title="24h Change (%)", row=2, col=1)
+
+    # Annotation styling for subplot titles
+    for ann in fig.layout.annotations:
+        ann.font = dict(size=12, color=COLORS["text"])
+
+    # --- Table data for report ---
+    table_rows = []
+
+    # FIAT summary table
+    for f in fiat_summary:
+        table_rows.append(
+            {
+                "Section": "FIAT Overview",
+                "Quote": f["quote"],
+                "Pairs": f["pair_count"],
+                "Total Volume": format_volume(f["total_volume_usdt"]),
+                "Top Pair": f["top_pair"],
+            }
+        )
+
+    # Focus pairs table
+    if focus_pairs and focus_rate > 0:
+        for p in focus_pairs[: config.top_n]:
+            vol_usdt = p["quote_volume_24h"] * focus_rate
+            if vol_usdt < config.min_volume_usd:
+                continue
+            table_rows.append(
+                {
+                    "Section": f"{focus} Markets",
+                    "Pair": p["trading_pair"],
+                    "Volume (USDT)": format_volume(vol_usdt),
+                    "24h Change": f"{p['price_change_pct']:+.1f}%",
+                    "Trades": f"{p['trades_24h']:,}",
+                }
+            )
+
+    # USDT top pairs
+    for p in usdt_top[: config.top_n]:
+        table_rows.append(
+            {
+                "Section": "USDT Markets",
+                "Pair": p["trading_pair"],
+                "Volume (USDT)": format_volume(p["quote_volume_24h"]),
+                "24h Change": f"{p['price_change_pct']:+.1f}%",
+                "Trades": f"{p['trades_24h']:,}",
+            }
+        )
+
+    return text, fig, table_rows
+
+
+async def run(config: Config, context: ContextTypes.DEFAULT_TYPE) -> RoutineResult:
+    """Discover spot markets across quote currencies."""
+    # Fetch all tickers
+    try:
+        tickers = await fetch_spot_tickers()
+    except Exception as e:
+        return RoutineResult(text=f"Failed to fetch Binance spot tickers: {e}")
+
+    if not tickers:
+        return RoutineResult(text="No ticker data returned from Binance.")
+
+    # Categorize and get rates
+    by_quote = categorize_tickers(tickers)
+    usdt_rates = await _fetch_usdt_rates(tickers)
+
+    # Build output
+    text, fig, table_rows = _build_report(by_quote, usdt_rates, config)
+
+    # Generate report
+    from condor.reports import ReportBuilder
+
+    # Split tables by section
+    fiat_overview = [r for r in table_rows if r.get("Section") == "FIAT Overview"]
+    focus_rows = [
+        r
+        for r in table_rows
+        if r.get("Section") == f"{config.focus_quote.upper()} Markets"
+    ]
+    usdt_rows = [r for r in table_rows if r.get("Section") == "USDT Markets"]
+
+    # Clean section column
+    for rows in [fiat_overview, focus_rows, usdt_rows]:
+        for r in rows:
+            r.pop("Section", None)
+
+    builder = ReportBuilder("Spot Market Discovery")
+    builder.source("routine", "spot_markets").tags(
+        ["spot", "markets", "discovery", "fiat", "rebates"]
+    )
+    builder.plotly(fig)
+
+    builder.markdown("### FIAT Markets Overview (Rebate Eligible)")
+    if fiat_overview:
+        builder.table(fiat_overview)
+
+    if focus_rows:
+        builder.markdown(f"### Top {config.focus_quote.upper()}-Quoted Markets")
+        builder.table(focus_rows)
+
+    builder.markdown("### Top USDT-Quoted Markets")
+    if usdt_rows:
+        builder.table(usdt_rows)
+
+    await builder.save()
+
+    return RoutineResult(text=text)
diff --git a/agents/brigado/routines/toxic_flow_detector.py b/agents/brigado/routines/toxic_flow_detector.py
new file mode 100644
index 00000000..e69de29b
diff --git a/agents/brigado/strategies/brl_mm/strategy.md b/agents/brigado/strategies/brl_mm/strategy.md
new file mode 100644
index 00000000..ca1ffb6e
--- /dev/null
+++ b/agents/brigado/strategies/brl_mm/strategy.md
@@ -0,0 +1,32 @@
+---
+name: BRL MM
+description: BRL market making research agent. Tracks USDT-BRL spreads, BTC/fiat volume
+  dynamics, and bot performance for the Brazilian market making operation.
+agent_key: ollama:qwen3.5:9
+skills: []
+default_config:
+  connector_name: binance
+  quote_currency: BRL
+default_trading_context: ''
+created_by: 481175164
+created_at: '2026-05-04T00:00:00+00:00'
+---
+
+### Routines
+
+#### brl_dashboard
+Multi-timeframe technical dashboard for USDT-BRL with candlesticks, SMA, RSI, and support/resistance levels across 4 timeframes (1m, 15m, 1h, 1d).
+
+#### btc_brl_volume
+Compares BTC-USDT vs BTC-BRL volume over 7 days and analyzes 1-second price arbitrage spread to detect opportunities.
+
+#### btc_fiat_markets
+Stacked area chart of BTC trading volume across fiat pairs (BRL, ARS, MXN, EUR, JPY, PLN), normalized to USDT.
+
+#### bot_report
+Comprehensive bot performance report with volume, PnL, fees, market share, rebates, and per-controller breakdown.
+
+### Journal
+- Log market observations: BRL premium/discount trends, volume shifts
+- Track bot performance metrics over time
+- Note arbitrage windows and their duration
diff --git a/agents/orca_lp_expert/AGENT.md b/agents/orca_lp_expert/AGENT.md
new file mode 100644
index 00000000..f4694fd0
--- /dev/null
+++ b/agents/orca_lp_expert/AGENT.md
@@ -0,0 +1,66 @@
+---
+name: Orca LP Expert
+description: Specialist in concentrated liquidity LP on Orca, focused on tokenized
+  real-world assets (equities, pre-IPO, commodities) on Solana.
+agent_key: claude-code:sonnet
+tools: []
+when_to_consult: When the user wants to evaluate, open, manage, or exit an Orca CLMM
+  LP position — especially on tokenized assets like SPCX, GME, or other RWA tokens.
+  Also when assessing pool attractiveness, setting price ranges, or deciding whether
+  an open LP position should hold or exit.
+server_required: true
+server_name: ''
+created_by: 481175164
+created_at: '2026-08-14T16:53:03.026845+00:00'
+---
+
+# Orca LP Expert
+
+You are a concentrated liquidity LP specialist for **Orca CLMM pools on Solana**, with a focus on **tokenized real-world assets (RWAs)** — equities, pre-IPO names, commodities, and other off-chain assets brought on-chain (e.g. SPCX, GME, SILV, ZEC bridged assets, etc.).
+
+## Domain
+
+You handle:
+- Pool discovery and attractiveness assessment (fee tier, bin step, volume, TVL, fee/TVL ratio)
+- LP range selection for tokenized assets (wider ranges due to lower liquidity and higher volatility vs crypto-native pairs)
+- Impermanent loss analysis and break-even fee estimation
+- Position sizing given wallet balances
+- Entry / hold / exit decisions for open LP positions
+- Comparison of tokenized asset pools vs blue-chip pools (SOL-USDC, cbBTC-USDC)
+
+You do NOT handle: CEX trading, perpetuals, non-Orca DEXes (refer those to the appropriate agent), or tax advice.
+
+## Key domain knowledge
+
+### Orca CLMM mechanics
+- Bin step controls tick spacing: lower bin step (1, 4) = tighter range = more fees when in-range but higher IL risk; higher bin step (8, 16, 128) = wider range = less IL risk but fewer fees.
+- Fee tiers: 0.01% (stables), 0.04% (blue chips), 0.05% (mid vol), 0.16% (high vol / memecoins / tokenized assets), 1.00% (exotic).
+- Active bin = the bin where the current price sits. Only liquidity in the active bin earns fees.
+- When the price moves outside your range, you hold 100% of one asset (impermanent loss crystallized) and earn zero fees.
+
+### Tokenized assets (RWAs) on Solana — LP considerations
+- These trade with lower on-chain liquidity than crypto-native pairs → higher slippage and wider true bid/ask.
+- Price can gap significantly on market open/close or news events (SPCX, GME track equity sessions).
+- Prefer **wider ranges** (bin step 16+) for tokenized equity pairs to avoid being knocked out of range during market hours.
+- The 0.16% fee tier is almost always appropriate for these pairs.
+- Monitor: if the token is thinly traded, a large swap can move the price through your entire range in one transaction.
+- Correlation: some tokenized assets (gold/silver) are correlated; others (individual equities) are idiosyncratic.
+
+### Position sizing heuristics
+- For illiquid / tokenized pairs: keep individual position < 20% of on-chain pool TVL to avoid being your own slippage.
+- Pair the tokenized asset against USDC (most common), not SOL — reduces double IL exposure.
+- Typical entry split: 50/50 by value at current price, centered on the active bin.
+
+### Pool quality signals
+- fee/TVL ratio (24h) > 0.1% = good yield signal
+- Pool volume/TVL > 1x/day = active pool
+- Low TVL + low volume = avoid (wide spread, no fees earned)
+
+## How you answer
+- Lead with: **Recommendation** (open / hold / exit / avoid), then rationale.
+- Use key: value format for pool metrics, not prose paragraphs.
+- Flag IL risk explicitly when opening a position on a volatile or thinly-traded pair.
+- When unsure of current pool data, call `explore_dex_pools(connector="orca")` or `explore_geckoterminal` to fetch fresh numbers.
+- When checking wallet balances, call `get_portfolio_overview`.
+- When opening a position, use `manage_executors(executor_type="lp_executor")` and confirm with the user before executing.
+
diff --git a/agents/orca_lp_expert/routines/orca_rwa_lp_ranger.py b/agents/orca_lp_expert/routines/orca_rwa_lp_ranger.py
new file mode 100644
index 00000000..75ef1c26
--- /dev/null
+++ b/agents/orca_lp_expert/routines/orca_rwa_lp_ranger.py
@@ -0,0 +1,468 @@
+"""Orca RWA LP Ranger — picks the top 4 RWA pools and suggests an LP price range from 5m candles.
+
+Uses https://api.orca.so/v2/solana (Cloudflare-fronted; custom User-Agent required).
+GeckoTerminal provides 5-minute OHLCV candles for range computation.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from datetime import datetime, timezone
+
+import httpx
+import numpy as np
+import plotly.graph_objects as go
+from plotly.subplots import make_subplots
+from pydantic import BaseModel, Field
+from telegram.ext import ContextTypes
+
+from condor.reports import ReportBuilder
+from handlers.dex.pool_data import fetch_ohlcv
+from routines.base import RoutineResult
+
+logger = logging.getLogger(__name__)
+
+CATEGORY = "Analysis"
+
+_ORCA_BASE = "https://api.orca.so/v2/solana"
+_USER_AGENT = "condor-dex-browser/1.0 (+https://github.com/hummingbot)"
+_ORCA_TIMEOUT = httpx.Timeout(15.0, connect=5.0)
+
+
+class Config(BaseModel):
+    """Orca RWA LP Ranger — picks the top 4 RWA pools and suggests an LP price range from 5m candles."""
+
+    min_tvl: float = Field(default=1000.0, description="Minimum pool TVL in USD")
+    include_symbols: str = Field(
+        default="SPCX,GME,SILV,TSLA,AAPL,NVDA,COIN,MSFT",
+        description="Comma-separated RWA token symbols to scan",
+    )
+    candle_limit: int = Field(
+        default=200, description="Number of 5m candles to fetch per pool (max 500)"
+    )
+    atr_periods: int = Field(
+        default=14, description="ATR period for LP range calculation"
+    )
+    atr_multiplier: float = Field(
+        default=3.0, description="ATR multiplier for LP range width"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _safe_float(val, default: float = 0.0) -> float:
+    try:
+        return float(val) if val is not None else default
+    except (TypeError, ValueError):
+        return default
+
+
+def _ts_to_dt(ts) -> datetime:
+    """Convert Orca/GeckoTerminal timestamp (int s or ms) to UTC datetime."""
+    ts_f = float(ts)
+    if ts_f > 1_000_000_000_000:  # milliseconds
+        return datetime.fromtimestamp(ts_f / 1000, tz=timezone.utc)
+    return datetime.fromtimestamp(ts_f, tz=timezone.utc)  # seconds
+
+
+def _compute_atr(highs, lows, closes, period: int) -> float:
+    h = np.array(highs, dtype=float)
+    l = np.array(lows, dtype=float)
+    c = np.array(closes, dtype=float)
+    prev_c = np.roll(c, 1)
+    prev_c[0] = c[0]
+    tr = np.maximum(h - l, np.maximum(np.abs(h - prev_c), np.abs(l - prev_c)))
+    return float(np.mean(tr[-period:]))
+
+
+def _parse_pool(pool: dict) -> dict | None:
+    """Extract and normalise metrics from a raw Orca v2 whirlpool row."""
+    try:
+        address = pool.get("address") or ""
+        if not address:
+            return None
+        sym_a = (pool.get("tokenA") or {}).get("symbol") or "?"
+        sym_b = (pool.get("tokenB") or {}).get("symbol") or "?"
+        # feeRate is raw basis-points * 100 (e.g. 1600 → 0.16%)
+        fee_rate_raw = _safe_float(pool.get("feeRate"))
+        fee_tier = fee_rate_raw / 10_000
+        tvl = _safe_float(pool.get("tvlUsdc"))
+        if tvl <= 0:
+            return None
+        stats_24h = (pool.get("stats") or {}).get("24h") or {}
+        volume_24h = _safe_float(stats_24h.get("volume"))
+        fees_24h = _safe_float(stats_24h.get("fees"))
+        if fees_24h == 0.0 and fee_tier > 0.0 and volume_24h > 0.0:
+            fees_24h = volume_24h * fee_tier
+        fee_tvl_ratio = fees_24h / tvl * 100 if tvl > 0 else 0.0
+        vol_tvl_ratio = volume_24h / tvl if tvl > 0 else 0.0
+        score = fee_tvl_ratio * 0.6 + vol_tvl_ratio * 0.4
+        addr_short = f"{address[:6]}…{address[-4:]}" if len(address) >= 10 else address
+        return {
+            "address": address,
+            "address_short": addr_short,
+            "token_a_symbol": sym_a,
+            "token_b_symbol": sym_b,
+            "fee_tier": round(fee_tier, 4),
+            "tvl": round(tvl, 2),
+            "volume_24h": round(volume_24h, 2),
+            "fees_24h": round(fees_24h, 4),
+            "fee_tvl_ratio": round(fee_tvl_ratio, 6),
+            "vol_tvl_ratio": round(vol_tvl_ratio, 6),
+            "score": round(score, 6),
+        }
+    except Exception as exc:
+        logger.warning("Pool parse error %s: %s", pool.get("address", "?"), exc)
+        return None
+
+
+async def _search_symbol(
+    client: httpx.AsyncClient, sem: asyncio.Semaphore, symbol: str
+) -> list[dict]:
+    async with sem:
+        try:
+            r = await client.get("/pools/search", params={"q": symbol, "stats": "24h"})
+            r.raise_for_status()
+            body = r.json()
+            rows = (
+                body.get("data", [])
+                if isinstance(body, dict)
+                else (body if isinstance(body, list) else [])
+            )
+            sym_upper = symbol.upper()
+            return [
+                p
+                for p in rows
+                if isinstance(p, dict)
+                and (
+                    ((p.get("tokenA") or {}).get("symbol") or "")
+                    .upper()
+                    .startswith(sym_upper)
+                    or ((p.get("tokenB") or {}).get("symbol") or "")
+                    .upper()
+                    .startswith(sym_upper)
+                )
+            ]
+        except Exception as exc:
+            logger.warning("Orca search '%s' failed: %s", symbol, exc)
+            return []
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+
+async def run(config: Config, context: ContextTypes.DEFAULT_TYPE) -> RoutineResult:
+    symbols = [
+        s.strip().upper() for s in config.include_symbols.split(",") if s.strip()
+    ]
+
+    # ── Step 1: Fetch & rank RWA pools ────────────────────────────────────────
+    sem = asyncio.Semaphore(5)
+    async with httpx.AsyncClient(
+        base_url=_ORCA_BASE,
+        timeout=_ORCA_TIMEOUT,
+        headers={"User-Agent": _USER_AGENT, "Accept": "application/json"},
+    ) as orca:
+        batches = await asyncio.gather(
+            *[_search_symbol(orca, sem, sym) for sym in symbols]
+        )
+
+    seen: set[str] = set()
+    all_pools: list[dict] = []
+    for batch in batches:
+        for raw in batch:
+            parsed = _parse_pool(raw)
+            if parsed and parsed["address"] not in seen:
+                seen.add(parsed["address"])
+                all_pools.append(parsed)
+
+    filtered = [p for p in all_pools if p["tvl"] >= config.min_tvl]
+    filtered.sort(key=lambda x: x["score"], reverse=True)
+    top4 = filtered[:4]
+
+    if not top4:
+        builder = ReportBuilder("Orca RWA LP Ranger")
+        builder.source("routine", "orca_rwa_lp_ranger")
+        builder.tags(["orca", "rwa", "lp"])
+        builder.section("RESULT", None)
+        builder.markdown(
+            f"No RWA pools found above min_tvl=${config.min_tvl:,.0f}. "
+            f"Scanned {len(all_pools)} pools across {len(symbols)} symbols."
+        )
+        builder.manual_order()
+        await builder.save()
+        return RoutineResult(
+            text=(
+                f"No RWA pools found above min_tvl=${config.min_tvl:,.0f}. "
+                f"Scanned {len(all_pools)} pools."
+            )
+        )
+
+    # ── Step 2: Fetch 5m candles ──────────────────────────────────────────────
+    # Through pool_data, not a raw URL: GeckoTerminal's ~30 req/min is per *IP*,
+    # shared with the dashboard and the candle poll loop. fetch_ohlcv carries the
+    # rate gate, the circuit breaker and the single-flight, so no manual pacing.
+    candle_data: dict[str, list] = {}
+    for pool in top4:
+        addr = pool["address"]
+        ohlcv, err = await fetch_ohlcv(
+            addr,
+            "solana",
+            timeframe="5m",
+            currency="usd",
+            limit=config.candle_limit,
+        )
+        if err or not ohlcv:
+            logger.warning("GeckoTerminal candles for %s failed: %s", addr, err)
+            candle_data[addr] = []
+            continue
+        candle_data[addr] = sorted(ohlcv, key=lambda x: x[0])  # ascending by timestamp
+
+    # ── Steps 3 & 4: ATR ranges + 2×2 chart ──────────────────────────────────
+    subplot_titles = [f"{p['token_a_symbol']}-{p['token_b_symbol']}" for p in top4]
+    while len(subplot_titles) < 4:
+        subplot_titles.append("")
+
+    fig = make_subplots(
+        rows=2,
+        cols=2,
+        shared_xaxes=False,
+        subplot_titles=subplot_titles,
+    )
+
+    range_table_data: list[dict] = []
+
+    for i, pool in enumerate(top4):
+        row = i // 2 + 1
+        col = i % 2 + 1
+        addr = pool["address"]
+        ohlcv = candle_data.get(addr, [])
+        ta = pool["token_a_symbol"]
+        tb = pool["token_b_symbol"]
+
+        if len(ohlcv) < config.atr_periods + 1:
+            logger.warning("Insufficient candles for %s-%s: %d", ta, tb, len(ohlcv))
+            range_table_data.append(
+                {
+                    "Pool": f"{ta}-{tb}",
+                    "Current Price": "N/A",
+                    "Lower": "—",
+                    "Upper": "—",
+                    "Range %": "—",
+                    "ATR": "—",
+                    "Fee Tier": f"{pool['fee_tier']:.4f}%",
+                    "TVL": f"${pool['tvl']:,.0f}",
+                    "24h Fees": f"${pool['fees_24h']:,.2f}",
+                }
+            )
+            continue
+
+        timestamps = [_ts_to_dt(c[0]) for c in ohlcv]
+        opens = [c[1] for c in ohlcv]
+        highs = [c[2] for c in ohlcv]
+        lows = [c[3] for c in ohlcv]
+        closes = [c[4] for c in ohlcv]
+
+        atr = _compute_atr(highs, lows, closes, config.atr_periods)
+        current_price = closes[-1]
+        lower_price = max(
+            current_price - config.atr_multiplier * atr, current_price * 0.01
+        )
+        upper_price = current_price + config.atr_multiplier * atr
+        range_pct = (upper_price - lower_price) / current_price * 100
+
+        pool["current_price"] = current_price
+        pool["lower_price"] = lower_price
+        pool["upper_price"] = upper_price
+        pool["range_pct"] = range_pct
+        pool["atr"] = atr
+
+        # Candlestick
+        fig.add_trace(
+            go.Candlestick(
+                x=timestamps,
+                open=opens,
+                high=highs,
+                low=lows,
+                close=closes,
+                name=f"{ta}-{tb}",
+                increasing_line_color="#22c55e",
+                decreasing_line_color="#ef4444",
+                showlegend=False,
+            ),
+            row=row,
+            col=col,
+        )
+
+        # LP range shaded band
+        x_band = timestamps + timestamps[::-1]
+        y_band = [upper_price] * len(timestamps) + [lower_price] * len(timestamps)
+        fig.add_trace(
+            go.Scatter(
+                x=x_band,
+                y=y_band,
+                fill="toself",
+                fillcolor="rgba(99, 102, 241, 0.15)",
+                line=dict(width=0),
+                mode="lines",
+                name="LP Range",
+                showlegend=(i == 0),
+                hoverinfo="skip",
+            ),
+            row=row,
+            col=col,
+        )
+
+        # Upper bound dashed line
+        fig.add_shape(
+            type="line",
+            x0=timestamps[0],
+            x1=timestamps[-1],
+            y0=upper_price,
+            y1=upper_price,
+            line=dict(color="#6366f1", width=1.5, dash="dash"),
+            row=row,
+            col=col,
+        )
+        # Lower bound dashed line
+        fig.add_shape(
+            type="line",
+            x0=timestamps[0],
+            x1=timestamps[-1],
+            y0=lower_price,
+            y1=lower_price,
+            line=dict(color="#6366f1", width=1.5, dash="dash"),
+            row=row,
+            col=col,
+        )
+        # Current price dotted line
+        fig.add_shape(
+            type="line",
+            x0=timestamps[0],
+            x1=timestamps[-1],
+            y0=current_price,
+            y1=current_price,
+            line=dict(color="#f59e0b", width=1, dash="dot"),
+            row=row,
+            col=col,
+        )
+
+        # Price labels at right edge
+        fig.add_annotation(
+            x=timestamps[-1],
+            y=upper_price,
+            text=f"  ${upper_price:.4f}",
+            showarrow=False,
+            font=dict(color="#6366f1", size=10),
+            xanchor="left",
+            row=row,
+            col=col,
+        )
+        fig.add_annotation(
+            x=timestamps[-1],
+            y=lower_price,
+            text=f"  ${lower_price:.4f}",
+            showarrow=False,
+            font=dict(color="#6366f1", size=10),
+            xanchor="left",
+            row=row,
+            col=col,
+        )
+
+        fig.update_xaxes(type="date", rangeslider_visible=False, row=row, col=col)
+
+        range_table_data.append(
+            {
+                "Pool": f"{ta}-{tb}",
+                "Current Price": f"${current_price:.4f}",
+                "Lower": f"${lower_price:.4f}",
+                "Upper": f"${upper_price:.4f}",
+                "Range %": f"{range_pct:.1f}%",
+                "ATR": f"{atr:.6f}",
+                "Fee Tier": f"{pool['fee_tier']:.4f}%",
+                "TVL": f"${pool['tvl']:,.0f}",
+                "24h Fees": f"${pool['fees_24h']:,.2f}",
+            }
+        )
+
+    fig.update_layout(
+        title="Orca RWA — Top 4 Pools LP Range Suggestion (5m candles)",
+        template="plotly_dark",
+        height=800,
+        legend=dict(orientation="h", yanchor="top", y=-0.05, xanchor="center", x=0.5),
+    )
+
+    # ── Step 5: ReportBuilder ─────────────────────────────────────────────────
+    builder = ReportBuilder("Orca RWA LP Ranger")
+    builder.source("routine", "orca_rwa_lp_ranger")
+    builder.tags(["orca", "rwa", "lp", "range", "candles"])
+    builder.manual_order()
+
+    builder.section(
+        "TOP 4 RWA POOLS", "Ranked by composite score (fee/TVL × 0.6 + vol/TVL × 0.4)"
+    )
+    builder.kpi("Pools Analyzed", str(len(all_pools)))
+    builder.kpi("Pools Selected", str(len(top4)))
+    for p in top4:
+        builder.kpi(
+            f"{p['token_a_symbol']}-{p['token_b_symbol']}", f"Score: {p['score']:.3f}"
+        )
+
+    builder.section(
+        "LP RANGE CHART", "5m candles with ATR-based LP range overlay (purple band)"
+    )
+    builder.plotly(fig)
+
+    builder.section("RANGE DETAILS", "Suggested ranges per pool")
+    builder.table(
+        range_table_data,
+        [
+            "Pool",
+            "Current Price",
+            "Lower",
+            "Upper",
+            "Range %",
+            "ATR",
+            "Fee Tier",
+            "TVL",
+            "24h Fees",
+        ],
+    )
+
+    builder.section("NOTES", None)
+    builder.markdown(
+        f"**Range logic:** ATR({config.atr_periods}) × {config.atr_multiplier} centered on current price\n\n"
+        "**Candles:** 5m from GeckoTerminal\n\n"
+        "**Warning:** Tokenized RWAs track equity market hours — range may widen significantly at "
+        "open/close. Consider widening range further for overnight positions."
+    )
+
+    report_id = await builder.save()
+
+    # ── Step 6: RoutineResult ─────────────────────────────────────────────────
+    pools_with_ranges = [p for p in top4 if "current_price" in p]
+    return RoutineResult(
+        text=(
+            f"Top {len(top4)} RWA pools ranked. "
+            f"Ranges computed from ATR({config.atr_periods})×{config.atr_multiplier}. "
+            f"Report: {report_id}"
+        ),
+        table_data=[
+            {
+                "Pool": f"{p['token_a_symbol']}-{p['token_b_symbol']}",
+                "Current": f"${p['current_price']:.4f}",
+                "Lower": f"${p['lower_price']:.4f}",
+                "Upper": f"${p['upper_price']:.4f}",
+                "Range %": f"{p['range_pct']:.1f}%",
+                "Score": f"{p['score']:.3f}",
+            }
+            for p in pools_with_ranges
+        ],
+        table_columns=["Pool", "Current", "Lower", "Upper", "Range %", "Score"],
+    )
diff --git a/agents/orca_lp_expert/routines/orca_rwa_pool_analysis.py b/agents/orca_lp_expert/routines/orca_rwa_pool_analysis.py
new file mode 100644
index 00000000..275cd25c
--- /dev/null
+++ b/agents/orca_lp_expert/routines/orca_rwa_pool_analysis.py
@@ -0,0 +1,274 @@
+"""Orca RWA Pool Analysis — scans Orca CLMM for tokenized real-world asset pools
+and ranks them by fee yield.
+
+Uses https://api.orca.so/v2/solana directly (same base as handlers/dex/orca_api.py).
+Cloudflare-fronted: a custom User-Agent header is required or the request is 403'd.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+
+import httpx
+from pydantic import BaseModel, Field
+from telegram.ext import ContextTypes
+
+from condor.reports import ReportBuilder
+from routines.base import RoutineResult
+
+logger = logging.getLogger(__name__)
+
+CATEGORY = "Analysis"
+
+_BASE_URL = "https://api.orca.so/v2/solana"
+_USER_AGENT = "condor-dex-browser/1.0 (+https://github.com/hummingbot)"
+_TIMEOUT = httpx.Timeout(15.0, connect=5.0)
+
+
+class Config(BaseModel):
+    """Orca RWA Pool Analysis — scans Orca CLMM for tokenized real-world asset pools and ranks them by fee yield."""
+
+    min_tvl: float = Field(
+        default=1000.0, description="Minimum TVL in USD to include a pool"
+    )
+    include_symbols: str = Field(
+        default="SPCX,GME,SILV,TSLA,AAPL,NVDA,COIN,MSFT",
+        description="Comma-separated RWA token symbols to search",
+    )
+    top_n: int = Field(default=10, description="Number of top pools to show in summary")
+
+
+# ---------------------------------------------------------------------------
+# Fetch helpers
+# ---------------------------------------------------------------------------
+
+
+async def _search_symbol(
+    client: httpx.AsyncClient, sem: asyncio.Semaphore, symbol: str
+) -> list[dict]:
+    """Search Orca for pools containing a given RWA symbol and filter to close matches."""
+    async with sem:
+        try:
+            r = await client.get("/pools/search", params={"q": symbol, "stats": "24h"})
+            r.raise_for_status()
+            body = r.json()
+            rows = (
+                body.get("data", [])
+                if isinstance(body, dict)
+                else (body if isinstance(body, list) else [])
+            )
+            sym_upper = symbol.upper()
+            filtered = []
+            for p in rows:
+                if not isinstance(p, dict):
+                    continue
+                sym_a = ((p.get("tokenA") or {}).get("symbol") or "").upper()
+                sym_b = ((p.get("tokenB") or {}).get("symbol") or "").upper()
+                # Accept only when a token symbol starts with the searched RWA symbol.
+                # startswith avoids false positives like "COIN" matching "BITCOIN".
+                if sym_a.startswith(sym_upper) or sym_b.startswith(sym_upper):
+                    filtered.append(p)
+            return filtered
+        except Exception as exc:
+            logger.warning("Orca search for %s failed: %s", symbol, exc)
+            return []
+
+
+def _parse_pool(pool: dict) -> dict | None:
+    """Extract and compute metrics from a raw Orca whirlpool row.
+
+    Returns None if the pool has no TVL or fails to parse.
+    """
+    try:
+        address = pool.get("address") or ""
+        sym_a = (pool.get("tokenA") or {}).get("symbol") or "?"
+        sym_b = (pool.get("tokenB") or {}).get("symbol") or "?"
+        fee_rate_raw = float(pool.get("feeRate") or 0)
+        fee_tier = fee_rate_raw / 10000  # e.g. 1600 → 0.16 (percent)
+        tick_spacing = int(pool.get("tickSpacing") or 0)
+        tvl = float(pool.get("tvlUsdc") or 0)
+        if tvl <= 0:
+            return None
+        stats_24h = (pool.get("stats") or {}).get("24h") or {}
+        volume_24h = float(stats_24h.get("volume") or 0)
+        fees_24h = float(stats_24h.get("fees") or 0)
+
+        fee_tvl_ratio = fees_24h / tvl * 100 if tvl > 0 else 0.0
+        vol_tvl_ratio = volume_24h / tvl if tvl > 0 else 0.0
+        score = fee_tvl_ratio * 0.6 + vol_tvl_ratio * 0.4
+
+        addr_short = (
+            f"{address[:6]}...{address[-4:]}" if len(address) >= 10 else address
+        )
+
+        return {
+            "address": address,
+            "address_short": addr_short,
+            "token_a": sym_a,
+            "token_b": sym_b,
+            "pool_label": f"{sym_a}-{sym_b} ({addr_short})",
+            "fee_tier": round(fee_tier, 4),
+            "tick_spacing": tick_spacing,
+            "tvl": round(tvl, 2),
+            "volume_24h": round(volume_24h, 2),
+            "fees_24h": round(fees_24h, 4),
+            "fee_tvl_ratio": round(fee_tvl_ratio, 6),
+            "vol_tvl_ratio": round(vol_tvl_ratio, 6),
+            "score": round(score, 6),
+        }
+    except Exception as exc:
+        logger.warning("Failed to parse pool %s: %s", pool.get("address", "?"), exc)
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Main entry point
+# ---------------------------------------------------------------------------
+
+
+async def run(config: Config, context: ContextTypes.DEFAULT_TYPE) -> RoutineResult:
+    symbols = [
+        s.strip().upper() for s in config.include_symbols.split(",") if s.strip()
+    ]
+
+    # --- Fetch: parallel per-symbol searches with rate-limiting ---
+    async with httpx.AsyncClient(
+        base_url=_BASE_URL,
+        timeout=_TIMEOUT,
+        headers={"User-Agent": _USER_AGENT, "Accept": "application/json"},
+    ) as http:
+        sem = asyncio.Semaphore(5)
+        batches = await asyncio.gather(
+            *[_search_symbol(http, sem, sym) for sym in symbols]
+        )
+
+    # --- Deduplicate by pool address ---
+    seen: set[str] = set()
+    raw_pools: list[dict] = []
+    for batch in batches:
+        for p in batch:
+            addr = p.get("address") or ""
+            if addr and addr not in seen:
+                seen.add(addr)
+                raw_pools.append(p)
+
+    # --- Parse + filter by min_tvl ---
+    pools: list[dict] = []
+    for p in raw_pools:
+        m = _parse_pool(p)
+        if m and m["tvl"] >= config.min_tvl:
+            pools.append(m)
+
+    if not pools:
+        return RoutineResult(
+            text=f"No Orca RWA pools found above ${config.min_tvl:,.0f} TVL for symbols: {', '.join(symbols)}"
+        )
+
+    # Sort descending by score
+    pools.sort(key=lambda x: x["score"], reverse=True)
+
+    # --- Aggregate KPIs ---
+    total_tvl = sum(p["tvl"] for p in pools)
+    total_vol = sum(p["volume_24h"] for p in pools)
+    best_fee_tvl = max(p["fee_tvl_ratio"] for p in pools)
+
+    # --- Risk flags (computed before report) ---
+    thin = [p for p in pools if p["tvl"] < 10_000]
+    wrong_fee = [p for p in pools if p["fee_tier"] < 0.1]
+    stagnant = [p for p in pools if p["vol_tvl_ratio"] < 0.05]
+
+    risk_lines = ["## Risk Flags\n"]
+    if thin:
+        risk_lines.append("### Thin Liquidity (TVL < $10,000)")
+        for p in thin:
+            risk_lines.append(
+                f"- **{p['token_a']}/{p['token_b']}** (`{p['address_short']}`): TVL = ${p['tvl']:,.2f}"
+            )
+    if wrong_fee:
+        risk_lines.append("\n### Low Fee Tier for RWA (fee < 0.1%)")
+        for p in wrong_fee:
+            risk_lines.append(
+                f"- **{p['token_a']}/{p['token_b']}** (`{p['address_short']}`): fee = {p['fee_tier']:.4f}%"
+            )
+    if stagnant:
+        risk_lines.append("\n### Stagnant Pools (vol/TVL < 0.05)")
+        for p in stagnant:
+            risk_lines.append(
+                f"- **{p['token_a']}/{p['token_b']}** (`{p['address_short']}`): vol/TVL = {p['vol_tvl_ratio']:.4f}"
+            )
+    if not thin and not wrong_fee and not stagnant:
+        risk_lines.append("_No risk flags._")
+
+    # --- Build report ---
+    builder = ReportBuilder("Orca RWA Pool Analysis")
+    builder.source("routine", "orca_rwa_pool_analysis")
+    builder.tags(["orca", "rwa", "lp", "tokenized-assets"])
+
+    builder.section("PROTOCOL OVERVIEW")
+    builder.kpi("Total RWA Pools Found", str(len(pools)))
+    builder.kpi("Total TVL", f"${total_tvl:,.2f}")
+    builder.kpi("Total 24h Volume", f"${total_vol:,.2f}")
+    builder.kpi("Best Fee/TVL Ratio", f"{best_fee_tvl:.4f}%")
+
+    builder.section("RWA POOL RANKINGS")
+    builder.dataset("pools", pools)
+    builder.data_table(
+        "pools",
+        title="All RWA Pools",
+        columns=[
+            "token_a",
+            "token_b",
+            "fee_tier",
+            "tick_spacing",
+            "tvl",
+            "volume_24h",
+            "fees_24h",
+            "fee_tvl_ratio",
+            "vol_tvl_ratio",
+            "score",
+            "address_short",
+        ],
+    )
+
+    builder.section("POOL YIELD CHART")
+    builder.chart(
+        "bar",
+        "Fee Yield by Pool (fee/TVL %)",
+        "pools",
+        "pool_label",
+        "fee_tvl_ratio",
+        x_label="Pool",
+        y_label="Fee/TVL Ratio (%)",
+    )
+
+    builder.section("RISK FLAGS")
+    builder.markdown("\n".join(risk_lines))
+
+    builder.manual_order()
+    await builder.save()
+
+    # --- Inline summary: top N ---
+    top = pools[: config.top_n]
+    table_data = [
+        {
+            "Pool": f"{p['token_a']}/{p['token_b']}",
+            "Fee%": f"{p['fee_tier']:.4f}%",
+            "TVL": f"${p['tvl']:,.2f}",
+            "Vol 24h": f"${p['volume_24h']:,.2f}",
+            "Fee/TVL%": f"{p['fee_tvl_ratio']:.4f}%",
+            "Score": f"{p['score']:.4f}",
+        }
+        for p in top
+    ]
+
+    summary = (
+        f"Found {len(pools)} Orca RWA pools across {len(symbols)} symbols — "
+        f"best Fee/TVL: {best_fee_tvl:.4f}% | Total TVL: ${total_tvl:,.2f}"
+    )
+
+    return RoutineResult(
+        text=summary,
+        table_data=table_data,
+        table_columns=["Pool", "Fee%", "TVL", "Vol 24h", "Fee/TVL%", "Score"],
+    )
diff --git a/agents/orca_lp_expert/skills/add_token_to_gateway/SKILL.md b/agents/orca_lp_expert/skills/add_token_to_gateway/SKILL.md
new file mode 100644
index 00000000..f9d3336f
--- /dev/null
+++ b/agents/orca_lp_expert/skills/add_token_to_gateway/SKILL.md
@@ -0,0 +1,117 @@
+---
+name: add_token_to_gateway
+description: Playbook for adding a missing token to the Hummingbot Gateway so it can
+  be used in Orca LP positions. Covers both the UI walkthrough and the two input formats.
+when_to_use: When the user wants to LP or trade a token on Orca but the token is not
+  in the Gateway token list — Gateway refuses the pair, the executor fails with "token
+  not found", or the pool browser cannot resolve the token symbol. Common for newly-launched
+  RWA tokens (SPCX, SILV, GME, etc.) that are not pre-loaded.
+created: '2026-08-14T17:00:52Z'
+source: agent:orca_lp_expert
+---
+
+# Add a Token to the Gateway
+
+Use this playbook whenever a token is not recognized by the Gateway — the pool exists on Orca, but the executor or swap UI cannot resolve the token symbol or mint address.
+
+---
+
+## 1. Confirm the token is really missing
+
+Before adding, verify the pool exists and find the exact mint address:
+
+- Run the pool scanner (`orca_rwa_pool_analysis`) or search on Orca UI.
+- Note the **mint address** of the missing token (base58, ~44 characters on Solana).
+- Note the **network** — for Orca it is always `solana-mainnet-beta` (the Gateway network ID for Solana mainnet).
+
+---
+
+## 2. Navigate to Gateway → Tokens
+
+In Telegram (or the Condor web dashboard):
+
+```
+/gateway  →  🪙 Tokens  →  Select network  →  ➕ Add Token
+```
+
+> If the network list shows only "default" networks and Solana is not there, tap **🌐 All Networks** to expand it.
+
+---
+
+## 3. Add the token — two input formats
+
+The bot prompts for input after tapping ➕ Add Token. You have two options:
+
+### Option A — Address only (recommended for RWAs)
+Paste **only the mint address**. The bot fetches symbol, decimals, and name automatically from GeckoTerminal.
+
+```
+9QFfgxdSqH5zT7j6rZb1y6SZhw2aFtcQu2r6BuYpump
+```
+
+This works as long as the token is indexed on GeckoTerminal for the Solana network. Most traded RWA tokens (SPCX, SILV, GME, etc.) are indexed. If GeckoTerminal lookup fails, fall back to Option B.
+
+### Option B — Full format
+Send a comma-separated string when auto-lookup fails or you want to override the metadata:
+
+```
+address,symbol,decimals,name
+```
+
+Example:
+```
+9QFfgxdSqH5zT7j6rZb1y6SZhw2aFtcQu2r6BuYpump,SPCX,6,SpaceX Tokenized Equity
+```
+
+Field notes:
+- `address`: Solana mint address (base58)
+- `symbol`: Short ticker as shown on Orca (must match the pool's token symbol)
+- `decimals`: Token precision — **6** for most SPL stablecoins and RWA tokens, **9** for native SOL-like tokens. Check on-chain or GeckoTerminal if unsure.
+- `name`: Optional — can be omitted (`address,symbol,decimals`)
+
+---
+
+## 4. Verify the token was added
+
+After success, the bot shows `✅ Token Added Successfully` and returns to the token list for that network. The new token should appear in the grid.
+
+To confirm it is now usable:
+- Go to the pool browser (`/lp` or Dex page) and search for the pair (e.g., `SPCX-USDC`).
+- If the pair resolves and shows a pool address, the token is live in Gateway.
+
+---
+
+## 5. Edit or remove a token
+
+If the metadata was wrong (wrong symbol, wrong decimals):
+
+```
+/gateway  →  🪙 Tokens  →  Select network  →  [tap the token symbol]  →  ✏️ Edit
+```
+
+Send the corrected values in `symbol,decimals,name` format (address stays the same — Gateway does a delete + re-add internally).
+
+To remove: tap **🗑 Remove** and confirm.
+
+---
+
+## 6. Network ID reference (Orca = Solana)
+
+| Network | Gateway ID |
+|---------|-----------|
+| Solana Mainnet | `solana-mainnet-beta` |
+| Ethereum | `ethereum-mainnet` |
+| Arbitrum | `arbitrum-mainnet` |
+| Base | `base-mainnet` |
+| Polygon | `polygon-mainnet` |
+
+For Orca CLMM LP, always use `solana-mainnet-beta`.
+
+---
+
+## 7. RWA-specific notes
+
+- Most tokenized equity / RWA tokens on Solana use **6 decimals** — verify before adding.
+- If a token is freshly launched and not yet on GeckoTerminal, it may not have a pool on Orca either — check that a pool exists first.
+- The token symbol in Gateway must match the symbol the Orca connector uses in the trading pair (e.g., `SPCX-USDC` → symbol must be `SPCX`). A mismatch will cause the executor to fail even after adding.
+- After adding a new token, **restart the bot session** if the connector was already running — it caches the token list on startup.

From be792d2a6cb8a337afbeda6c82a24dac8daf6f66 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Mon, 17 Aug 2026 14:18:47 +0300
Subject: [PATCH 107/116] (refactor) ARCH-144: pool_data is core data, not a
 Telegram handler
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

condor/fetchers declares it must not import handlers/, and condor.dex_candles,
condor.fetchers.connectors and the dex/market web routes all broke that rule to
reach handlers.dex.pool_data — each with a function-scoped import, one of them
with a comment apologising for it. The module they were reaching for is 2,000
lines of GeckoTerminal/Gateway fetching with no Telegram import in it: a data
layer stranded in the wrong package.

Move it to condor/pool_data.py, with the Orca HTTP client it owns
(condor/orca_api.py), and point every caller at the new path. Core now imports
without pulling the handlers tree in at all.

Its cache calls move from handlers/dex/_shared to condor.cache directly, keeping
the "_cache" namespace explicit: the Telegram handlers invalidate that namespace
by group, and entries written anywhere else would outlive an invalidation the
handler believes it performed.
---
 .../routines/orca_rwa_lp_ranger.py            |  2 +-
 .../routines/orca_rwa_pool_analysis.py        |  2 +-
 .../smart_money_flow/routines/onchain_flow.py |  2 +-
 .../routines/lp_scanner.py                    |  2 +-
 condor/dex_candles.py                         | 12 +++------
 condor/fetchers/connectors.py                 |  7 +-----
 {handlers/dex => condor}/orca_api.py          |  0
 {handlers/dex => condor}/pool_data.py         | 25 +++++++++++++------
 condor/web/routes/dex.py                      | 14 +++++------
 condor/web/routes/market.py                   |  4 +--
 handlers/config/gateway/tokens.py             |  2 +-
 handlers/dex/__init__.py                      |  2 +-
 handlers/dex/geckoterminal.py                 | 13 +++++-----
 handlers/dex/pools.py                         |  7 +++++-
 .../hummingbot_api/tools/geckoterminal.py     |  2 +-
 routines/mcap_comparison.py                   |  2 +-
 routines/solana_pool_scanner.py               |  2 +-
 tests/conftest.py                             |  2 +-
 tests/test_dex_candles.py                     |  3 +--
 tests/test_dex_liquidity_bins_route.py        |  2 +-
 tests/test_dex_pool_discovery.py              |  6 ++---
 tests/test_dex_pool_resolution.py             |  2 +-
 tests/test_fetcher_venues.py                  |  2 +-
 tests/test_gecko_throttle.py                  |  4 +--
 24 files changed, 63 insertions(+), 58 deletions(-)
 rename {handlers/dex => condor}/orca_api.py (100%)
 rename {handlers/dex => condor}/pool_data.py (99%)

diff --git a/agents/orca_lp_expert/routines/orca_rwa_lp_ranger.py b/agents/orca_lp_expert/routines/orca_rwa_lp_ranger.py
index 75ef1c26..da10e977 100644
--- a/agents/orca_lp_expert/routines/orca_rwa_lp_ranger.py
+++ b/agents/orca_lp_expert/routines/orca_rwa_lp_ranger.py
@@ -17,8 +17,8 @@
 from pydantic import BaseModel, Field
 from telegram.ext import ContextTypes
 
+from condor.pool_data import fetch_ohlcv
 from condor.reports import ReportBuilder
-from handlers.dex.pool_data import fetch_ohlcv
 from routines.base import RoutineResult
 
 logger = logging.getLogger(__name__)
diff --git a/agents/orca_lp_expert/routines/orca_rwa_pool_analysis.py b/agents/orca_lp_expert/routines/orca_rwa_pool_analysis.py
index 275cd25c..02e96999 100644
--- a/agents/orca_lp_expert/routines/orca_rwa_pool_analysis.py
+++ b/agents/orca_lp_expert/routines/orca_rwa_pool_analysis.py
@@ -1,7 +1,7 @@
 """Orca RWA Pool Analysis — scans Orca CLMM for tokenized real-world asset pools
 and ranks them by fee yield.
 
-Uses https://api.orca.so/v2/solana directly (same base as handlers/dex/orca_api.py).
+Uses https://api.orca.so/v2/solana directly (same base as condor/orca_api.py).
 Cloudflare-fronted: a custom User-Agent header is required or the request is 403'd.
 """
 
diff --git a/agents/smart_money_flow/routines/onchain_flow.py b/agents/smart_money_flow/routines/onchain_flow.py
index 28318c88..d18f2aac 100644
--- a/agents/smart_money_flow/routines/onchain_flow.py
+++ b/agents/smart_money_flow/routines/onchain_flow.py
@@ -96,7 +96,7 @@ async def _gecko_json(path: str, params: dict | None = None) -> "dict | None":
     shared with the dashboard; CoinGecko keeps the plain fetcher. Returns None on
     any failure, like its sibling — a tick must never raise.
     """
-    from handlers.dex.pool_data import gecko_request
+    from condor.pool_data import gecko_request
 
     try:
         return await gecko_request("GET", path, params=params)
diff --git a/agents/solana_dex_lp_expert/routines/lp_scanner.py b/agents/solana_dex_lp_expert/routines/lp_scanner.py
index 2c814abe..912749d4 100644
--- a/agents/solana_dex_lp_expert/routines/lp_scanner.py
+++ b/agents/solana_dex_lp_expert/routines/lp_scanner.py
@@ -78,7 +78,7 @@ async def _gecko_get(path: str, params: dict | None = None) -> dict:
     tier is ~30 requests/minute per IP, shared with the dashboard and every other
     routine, and a scanner that fans out per venue is exactly what exhausts it.
     """
-    from handlers.dex.pool_data import gecko_request
+    from condor.pool_data import gecko_request
 
     return await gecko_request("GET", path, params=params)
 
diff --git a/condor/dex_candles.py b/condor/dex_candles.py
index 3cff51c6..86bed8c5 100644
--- a/condor/dex_candles.py
+++ b/condor/dex_candles.py
@@ -39,7 +39,7 @@
 
 def uses_gecko_candles(connector: str) -> bool:
     """Whether this connector's candles come from GeckoTerminal, not the API."""
-    from handlers.dex.pool_data import NETWORK_TO_GECKO
+    from condor.pool_data import NETWORK_TO_GECKO
 
     return connector in NETWORK_TO_GECKO
 
@@ -62,7 +62,7 @@ async def _pool_ohlcv(
     use_cache: bool = True,
 ) -> list:
     """Raw OHLCV rows for one pool, or [] on any miss. Never raises."""
-    from handlers.dex.pool_data import fetch_ohlcv
+    from condor.pool_data import fetch_ohlcv
 
     try:
         rows, err = await fetch_ohlcv(
@@ -98,7 +98,7 @@ async def _resolve_pool(connector: str, trading_pair: str) -> tuple[str, str]:
     ticker pair on a network whose bases are addresses, for instance, where a
     lookup would only spend a request to fail.
     """
-    from handlers.dex.pool_data import (
+    from condor.pool_data import (
         fetch_pair_top_pool,
         fetch_token_top_pool,
         uses_symbol_pairs,
@@ -141,11 +141,7 @@ async def fetch_dex_candles(
     Returns candle dicts (``timestamp``/``open``/``high``/``low``/``close``/
     ``volume``), ascending.
     """
-    from handlers.dex.pool_data import (
-        candles_needed,
-        normalize_timeframe,
-        timeframe_seconds,
-    )
+    from condor.pool_data import candles_needed, normalize_timeframe, timeframe_seconds
 
     timeframe = normalize_timeframe(interval)
     tf_seconds = timeframe_seconds(timeframe)
diff --git a/condor/fetchers/connectors.py b/condor/fetchers/connectors.py
index bbba72af..720dc0b6 100644
--- a/condor/fetchers/connectors.py
+++ b/condor/fetchers/connectors.py
@@ -4,6 +4,7 @@
 from typing import Dict, List
 
 from condor.fetchers._identifiers import validate_identifier
+from condor.pool_data import NETWORK_TO_GECKO, network_has_clmm
 
 logger = logging.getLogger(__name__)
 
@@ -51,10 +52,6 @@ async def _chartable_gateway_networks(client) -> List[str]:
     Raises whatever the gateway request raises — the caller decides how much of the
     answer a gateway failure is allowed to take down.
     """
-    # Lazy, like condor.dex_candles.uses_gecko_candles — condor.fetchers must not
-    # import handlers at module scope.
-    from handlers.dex.pool_data import NETWORK_TO_GECKO
-
     response = await client.gateway.list_networks()
     networks = (response or {}).get("networks") or []
     return sorted(
@@ -141,8 +138,6 @@ async def fetch_venues(
             must not empty the whole dropdown, and a list that still carries the
             credentialed venues is not a cached lie.
     """
-    from handlers.dex.pool_data import network_has_clmm
-
     # Credentials first: under strict this raises, and there is no point asking the
     # gateway about a server we cannot describe at all.
     connectors = await fetch_available_cex_connectors(
diff --git a/handlers/dex/orca_api.py b/condor/orca_api.py
similarity index 100%
rename from handlers/dex/orca_api.py
rename to condor/orca_api.py
diff --git a/handlers/dex/pool_data.py b/condor/pool_data.py
similarity index 99%
rename from handlers/dex/pool_data.py
rename to condor/pool_data.py
index 9edf8b2d..65bb7ce6 100644
--- a/handlers/dex/pool_data.py
+++ b/condor/pool_data.py
@@ -25,13 +25,18 @@
 from geckoterminal_py import constants as GECKO_CONSTANTS
 from glom import glom
 
+from condor import orca_api
+from condor.cache import evict_expired, get_cached, set_cached
 from config_manager import get_client
 
-from . import orca_api
-from ._shared import evict_expired, get_cached, set_cached
-
 logger = logging.getLogger(__name__)
 
+# The conversation cache these functions write into is shared with the Telegram DEX
+# handlers, which read and invalidate it by group under the "_cache" namespace (see
+# handlers/dex/_shared). Entries written under any other namespace would survive an
+# invalidation the handler thinks it performed, so this must stay in step with it.
+_CACHE_NS = "_cache"
+
 # CLMM venues an ``lp_executor`` can open a position on: (brand, the qualifiers its
 # GeckoTerminal dex id must carry, the gecko networks it exists on). Deliberately
 # separate from LIQUIDITY_SUPPORTED_DEXES below, which answers a different question
@@ -982,13 +987,15 @@ async def fetch_ohlcv(
                 f"ohlcv_{gecko_network}_{pool_address}_{timeframe}_{currency}"
                 f"_{token}_{limit}_{before_timestamp or 0}"
             )
-            cached = get_cached(user_data, cache_key, ttl=OHLCV_CACHE_TTL)
+            cached = get_cached(
+                user_data, cache_key, ttl=OHLCV_CACHE_TTL, namespace=_CACHE_NS
+            )
             if cached is not None:
                 return cached, None
             # Sweep on miss, as cached_call does. Historical windows mint a fresh
             # key per executor, so a long-lived caller would otherwise accumulate
             # one entry per chart forever.
-            evict_expired(user_data)
+            evict_expired(user_data, namespace=_CACHE_NS)
 
         # Pass all parameters explicitly:
         # - currency="token" means price in quote token (not USD)
@@ -1046,7 +1053,7 @@ async def fetch_ohlcv(
 
         # Cache result
         if user_data is not None:
-            set_cached(user_data, cache_key, ohlcv_list)
+            set_cached(user_data, cache_key, ohlcv_list, namespace=_CACHE_NS)
 
         return ohlcv_list, None
 
@@ -1099,7 +1106,9 @@ async def fetch_liquidity_bins(
         # Check cache
         cache_key = f"pool_bins_{connector}_{pool_address}"
         if user_data is not None:
-            cached = get_cached(user_data, cache_key, ttl=BINS_CACHE_TTL)
+            cached = get_cached(
+                user_data, cache_key, ttl=BINS_CACHE_TTL, namespace=_CACHE_NS
+            )
         else:
             cached = _ttl_get(
                 _pool_bins_cache, (connector, pool_address), BINS_CACHE_TTL
@@ -1170,7 +1179,7 @@ async def fetch_liquidity_bins(
 
         # Cache result
         if user_data is not None:
-            set_cached(user_data, cache_key, pool_info)
+            set_cached(user_data, cache_key, pool_info, namespace=_CACHE_NS)
         else:
             _ttl_put(
                 _pool_bins_cache, (connector, pool_address), pool_info, BINS_CACHE_TTL
diff --git a/condor/web/routes/dex.py b/condor/web/routes/dex.py
index b83ff2f4..41dfc9c4 100644
--- a/condor/web/routes/dex.py
+++ b/condor/web/routes/dex.py
@@ -5,7 +5,7 @@
 which one you are in *is* the decision. So this router browses pools rather than
 pairs, from the same three sources Telegram's ``/lp`` flow offers.
 
-Everything upstream lives in ``handlers.dex.pool_data`` — the single module that
+Everything upstream lives in ``condor.pool_data`` — the single module that
 talks to GeckoTerminal — so these handlers are auth, validation and shape, with no
 fetching or normalization of their own.
 """
@@ -113,7 +113,7 @@ async def list_pools(
     """
     cm = get_config_manager()
 
-    from handlers.dex.pool_data import (
+    from condor.pool_data import (
         list_gateway_pools,
         list_gecko_pools_page,
         list_orca_pools,
@@ -193,7 +193,7 @@ async def list_dexes(
     with no options is one the browser simply does not show.
     """
 
-    from handlers.dex.pool_data import list_gecko_dexes
+    from condor.pool_data import list_gecko_dexes
 
     return {"dexes": await list_gecko_dexes(network)}
 
@@ -216,7 +216,7 @@ async def list_chains(
     """
     cm = get_config_manager()
 
-    from handlers.dex.pool_data import NETWORK_TO_GECKO
+    from condor.pool_data import NETWORK_TO_GECKO
 
     fallback = [{"network_id": DEFAULT_NETWORK, "chain": "solana", "label": "Solana"}]
     try:
@@ -270,7 +270,7 @@ async def list_pools_by_address(
     otherwise be read as an address.
     """
 
-    from handlers.dex.pool_data import fetch_pools_by_addresses
+    from condor.pool_data import fetch_pools_by_addresses
 
     wanted = [a.strip() for a in (addresses or "").split(",") if a.strip()][:30]
     if not wanted:
@@ -294,7 +294,7 @@ async def get_pool(
     if not _POOL_ADDRESS_RE.match(pool_address):
         raise HTTPException(status_code=400, detail="Invalid pool_address")
 
-    from handlers.dex.pool_data import fetch_pool_by_address
+    from condor.pool_data import fetch_pool_by_address
 
     pool = await fetch_pool_by_address(network, pool_address)
     if not pool:
@@ -355,7 +355,7 @@ async def get_pool_bins(
     if not _POOL_ADDRESS_RE.match(pool_address):
         raise HTTPException(status_code=400, detail="Invalid pool_address")
 
-    from handlers.dex.pool_data import (
+    from condor.pool_data import (
         can_fetch_liquidity,
         fetch_liquidity_bins,
         get_connector_for_dex,
diff --git a/condor/web/routes/market.py b/condor/web/routes/market.py
index 0df93d7e..32d48706 100644
--- a/condor/web/routes/market.py
+++ b/condor/web/routes/market.py
@@ -173,7 +173,7 @@ async def get_dex_pool(
     to handle.
     """
 
-    from handlers.dex.pool_data import lp_provider_for_dex, resolve_pool_info
+    from condor.pool_data import lp_provider_for_dex, resolve_pool_info
 
     try:
         info = await resolve_pool_info(connector, trading_pair)
@@ -559,7 +559,7 @@ async def get_token_symbol(
     executor tables can resolve a symbol without threading a server name through
     every row. Auth is still required.
     """
-    from handlers.dex.pool_data import fetch_token_symbol
+    from condor.pool_data import fetch_token_symbol
 
     if not _ADDRESS_RE.match(mint):
         raise HTTPException(status_code=400, detail="Invalid token address")
diff --git a/handlers/config/gateway/tokens.py b/handlers/config/gateway/tokens.py
index 3001044d..d7a4a747 100644
--- a/handlers/config/gateway/tokens.py
+++ b/handlers/config/gateway/tokens.py
@@ -5,7 +5,7 @@
 from telegram import InlineKeyboardButton, InlineKeyboardMarkup, Update
 from telegram.ext import ContextTypes
 
-from handlers.dex.pool_data import gecko_call
+from condor.pool_data import gecko_call
 
 from ..user_preferences import get_active_server
 from ._shared import (
diff --git a/handlers/dex/__init__.py b/handlers/dex/__init__.py
index 5f1b9d5a..76d1a47c 100644
--- a/handlers/dex/__init__.py
+++ b/handlers/dex/__init__.py
@@ -13,7 +13,7 @@
 - swap.py: Unified swap (quote, execute, history with filters/pagination)
 - liquidity.py: Unified liquidity pools (balances, positions, history with filters/pagination)
 - pools.py: Pool info, position management (add, close, collect fees)
-- pool_data.py: Pool data fetching utilities (OHLCV, liquidity bins)
+  (pool/OHLCV/liquidity-bin fetching itself lives in ``condor.pool_data``)
 - geckoterminal.py: GeckoTerminal pool explorer with charts
 - visualizations.py: Chart generation (liquidity distribution, OHLCV candlesticks)
 - lp_monitor_handlers.py: LP monitor alert handling (navigation, rebalance, fees)
diff --git a/handlers/dex/geckoterminal.py b/handlers/dex/geckoterminal.py
index f3deeb21..7255edea 100644
--- a/handlers/dex/geckoterminal.py
+++ b/handlers/dex/geckoterminal.py
@@ -17,17 +17,17 @@
 from telegram import InlineKeyboardButton, InlineKeyboardMarkup, Update
 from telegram.ext import ContextTypes
 
-from utils.telegram_formatters import escape_markdown_v2
-
-from ._shared import cached_call
-from .pool_data import GECKO_TO_GATEWAY_NETWORK as _GECKO_TO_GATEWAY_NETWORK
-from .pool_data import (
+from condor.pool_data import GECKO_TO_GATEWAY_NETWORK as _GECKO_TO_GATEWAY_NETWORK
+from condor.pool_data import (
     can_fetch_liquidity,
     fetch_liquidity_bins,
     gecko_call,
     gecko_request,
     get_connector_for_dex,
 )
+from utils.telegram_formatters import escape_markdown_v2
+
+from ._shared import cached_call
 from .visualizations import (
     generate_combined_chart,
     generate_liquidity_chart,
@@ -3235,7 +3235,8 @@ async def handle_gecko_add_liquidity(
     update: Update, context: ContextTypes.DEFAULT_TYPE
 ) -> None:
     """Handle add liquidity from GeckoTerminal pool detail - bridges to pools.py flow"""
-    from .pool_data import get_connector_for_dex
+    from condor.pool_data import get_connector_for_dex
+
     from .pools import _show_pool_detail
 
     query = update.callback_query
diff --git a/handlers/dex/pools.py b/handlers/dex/pools.py
index 770fbe5e..b66e9400 100644
--- a/handlers/dex/pools.py
+++ b/handlers/dex/pools.py
@@ -14,6 +14,12 @@
 from telegram.error import BadRequest
 from telegram.ext import ContextTypes
 
+from condor.pool_data import (
+    fetch_liquidity_bins,
+    fetch_ohlcv,
+    gecko_call,
+    get_gecko_network,
+)
 from config_manager import get_client
 from handlers.config.user_preferences import get_dex_last_pool, set_dex_last_pool
 from utils.telegram_formatters import (
@@ -26,7 +32,6 @@
 )
 
 from ._shared import DEFAULT_CACHE_TTL, get_cached, invalidate_cache, set_cached
-from .pool_data import fetch_liquidity_bins, fetch_ohlcv, gecko_call, get_gecko_network
 from .visualizations import (
     generate_aggregated_liquidity_chart,
     generate_combined_chart,
diff --git a/mcp_servers/hummingbot_api/tools/geckoterminal.py b/mcp_servers/hummingbot_api/tools/geckoterminal.py
index c084ef31..24cb969f 100644
--- a/mcp_servers/hummingbot_api/tools/geckoterminal.py
+++ b/mcp_servers/hummingbot_api/tools/geckoterminal.py
@@ -264,7 +264,7 @@ async def explore_geckoterminal(
     trade_volume_filter: float | None = None,
 ) -> dict[str, Any]:
     """Execute a GeckoTerminal API action and return formatted results."""
-    from handlers.dex.pool_data import gecko_request
+    from condor.pool_data import gecko_request
 
     async def _get(path: str, params: dict | None = None) -> dict:
         """One call on this process's gecko budget.
diff --git a/routines/mcap_comparison.py b/routines/mcap_comparison.py
index 5db6d352..13d2cfef 100644
--- a/routines/mcap_comparison.py
+++ b/routines/mcap_comparison.py
@@ -73,7 +73,7 @@ async def _fetch_token_info(mint: str) -> dict:
     On the process-wide gecko budget — the ~30/min free tier is per IP and shared
     with the dashboard, so this routine cannot pace itself in isolation.
     """
-    from handlers.dex.pool_data import gecko_request
+    from condor.pool_data import gecko_request
 
     data = await gecko_request("GET", f"networks/solana/tokens/{mint}")
     attrs = data.get("data", {}).get("attributes", {})
diff --git a/routines/solana_pool_scanner.py b/routines/solana_pool_scanner.py
index 00d80c1e..40d3387f 100644
--- a/routines/solana_pool_scanner.py
+++ b/routines/solana_pool_scanner.py
@@ -55,7 +55,7 @@ async def _fetch_pools_page(dex_id: str, page: int) -> list[dict]:
     able to exhaust the ~30/min the whole process shares — hence the shared gate
     rather than a session of its own.
     """
-    from handlers.dex.pool_data import gecko_request
+    from condor.pool_data import gecko_request
 
     try:
         body = await gecko_request(
diff --git a/tests/conftest.py b/tests/conftest.py
index e4c1b38e..57edee04 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -39,7 +39,7 @@ def _reset_gecko_throttle():
     fast suite spends the whole minute's budget inside the first few tests and the
     rest fail on a throttle that has nothing to do with what they assert.
     """
-    from handlers.dex.pool_data import reset_gecko_throttle
+    from condor.pool_data import reset_gecko_throttle
 
     reset_gecko_throttle()
     yield
diff --git a/tests/test_dex_candles.py b/tests/test_dex_candles.py
index af102196..60ead04c 100644
--- a/tests/test_dex_candles.py
+++ b/tests/test_dex_candles.py
@@ -11,9 +11,8 @@
 
 import pytest
 
-from condor import dex_candles
+from condor import dex_candles, pool_data
 from condor.web.routes import market
-from handlers.dex import pool_data
 
 
 def run(coro):
diff --git a/tests/test_dex_liquidity_bins_route.py b/tests/test_dex_liquidity_bins_route.py
index f978c1d9..31873f9e 100644
--- a/tests/test_dex_liquidity_bins_route.py
+++ b/tests/test_dex_liquidity_bins_route.py
@@ -15,9 +15,9 @@
 from starlette.testclient import TestClient
 
 import condor.web.routes.dex as dex_routes
+from condor import pool_data
 from condor.web.auth import get_current_user
 from condor.web.models import WebUser
-from handlers.dex import pool_data
 
 POOL = "8sLbNZoA1cfnvMJLPfp98ZLAnFSYCFApfJKMbiXNLwxj"
 USER = WebUser(id=111, username="u", first_name="U", role="user")
diff --git a/tests/test_dex_pool_discovery.py b/tests/test_dex_pool_discovery.py
index 1433a55e..12a15db0 100644
--- a/tests/test_dex_pool_discovery.py
+++ b/tests/test_dex_pool_discovery.py
@@ -1,4 +1,4 @@
-"""Pool discovery in handlers/dex/pool_data.py (FEAT-044).
+"""Pool discovery in condor/pool_data.py (FEAT-044).
 
 The DEX page is pool-first, so every row it renders has to answer three questions
 the frontend cannot: can I chart this pool, can I trade in it, can I LP in it.
@@ -15,9 +15,9 @@
 from starlette.testclient import TestClient
 
 import condor.web.routes.dex as dex_routes
+from condor import pool_data
 from condor.web.auth import get_current_user
 from condor.web.models import WebUser
-from handlers.dex import pool_data
 
 POOL = "8sLbNZoA1cfnvMJLPfp98ZLAnFSYCFApfJKMbiXNLwxj"
 SOL = "So11111111111111111111111111111111111111112"
@@ -1161,7 +1161,7 @@ def test_chains_needs_server_access(route_client):
     assert client.get("/servers/srv/dex/chains").status_code == 403
 
 
-# ── the Orca source (handlers/dex/orca_api.py + list_orca_pools) ──
+# ── the Orca source (condor/orca_api.py + list_orca_pools) ──
 #
 # Gateway proxies this very API and nulls volume, fees, price and yield on the way
 # — and ignores its own `page` argument for this connector, so every page of the
diff --git a/tests/test_dex_pool_resolution.py b/tests/test_dex_pool_resolution.py
index 908a674c..e3289393 100644
--- a/tests/test_dex_pool_resolution.py
+++ b/tests/test_dex_pool_resolution.py
@@ -21,7 +21,7 @@
 
 import pytest
 
-from handlers.dex import pool_data
+from condor import pool_data
 
 
 def run(coro):
diff --git a/tests/test_fetcher_venues.py b/tests/test_fetcher_venues.py
index 2759cf78..0351d723 100644
--- a/tests/test_fetcher_venues.py
+++ b/tests/test_fetcher_venues.py
@@ -23,7 +23,7 @@
 import pytest
 
 from condor.fetchers.connectors import fetch_venues
-from handlers.dex.pool_data import network_has_clmm
+from condor.pool_data import network_has_clmm
 
 
 class FakeClient:
diff --git a/tests/test_gecko_throttle.py b/tests/test_gecko_throttle.py
index 4428ad48..2514ee5c 100644
--- a/tests/test_gecko_throttle.py
+++ b/tests/test_gecko_throttle.py
@@ -14,7 +14,7 @@
 
 import pytest
 
-from handlers.dex import pool_data
+from condor import pool_data
 
 
 def run(coro):
@@ -235,7 +235,7 @@ def test_no_gecko_call_bypasses_the_budget():
 
 
 # Everything below the repo root except pool_data.py, which owns the client.
-_REPO = Path(pool_data.__file__).resolve().parents[2]
+_REPO = Path(__file__).resolve().parents[1]
 _SKIP = {".venv", ".git", "node_modules", "__pycache__", "dist", "build"}
 
 

From 7b59aa1e8a437c80dfc7281fd928e311bb418a80 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Mon, 17 Aug 2026 14:24:51 +0300
Subject: [PATCH 108/116] (perf) PERF-169: one gecko request per candle window,
 whoever asks for it
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

PERF-137 coalesced GET /market/candles on the route's own cache key. That key
carries what the upstream window does not — the trading pair, the server name —
so two requests that resolve to the very same GeckoTerminal window each opened
their own request and spent the rate budget twice. The route guard cannot see
that they converge; only the fetch can.

So fetch_ohlcv now coalesces on the upstream request itself: pool, timeframe,
currency, priced side and window. Two charts of one pool labelled by different
pairs, the dashboard's shared cache and a chat's user_data, a caller with no
cache at all — one gecko request between them. The per-caller TTL caches above
it and the route guard are untouched; they only ever helped once an answer had
landed, which is precisely not the stampede case.

This reuses `_single_flight`, which pool_data already owns and which already
carries both hardenings the item asked for: it refuses a done() task, so a
finished fetch lingering before its done-callback cannot hand a fresh request
the previous outcome, and awaiters shield the shared task, so the viewer who
navigates away cannot cancel the fetch the others are waiting on. A failing
fetch reaches every waiter and is cached by nobody.
---
 condor/pool_data.py                     | 124 ++++++++------
 tests/test_ohlcv_upstream_coalescing.py | 219 ++++++++++++++++++++++++
 2 files changed, 295 insertions(+), 48 deletions(-)
 create mode 100644 tests/test_ohlcv_upstream_coalescing.py

diff --git a/condor/pool_data.py b/condor/pool_data.py
index 65bb7ce6..cb2cf379 100644
--- a/condor/pool_data.py
+++ b/condor/pool_data.py
@@ -955,6 +955,9 @@ async def fetch_ohlcv(
 ) -> Tuple[Optional[List], Optional[str]]:
     """Fetch OHLCV data for any pool via GeckoTerminal
 
+    Concurrent callers asking for the same upstream window share one request, no
+    matter what key each of them caches the answer under.
+
     Args:
         pool_address: Pool contract address
         network: Network identifier (will be converted to GeckoTerminal format)
@@ -997,60 +1000,85 @@ async def fetch_ohlcv(
             # one entry per chart forever.
             evict_expired(user_data, namespace=_CACHE_NS)
 
-        # Pass all parameters explicitly:
-        # - currency="token" means price in quote token (not USD)
-        # - token="base" means OHLCV for the base token
-        result = await gecko_call(
-            "get_ohlcv",
-            gecko_network,
-            pool_address,
-            timeframe,
-            before_timestamp=before_timestamp,
-            currency=currency,
-            token=token,
-            limit=limit,
-        )
-
-        # Parse response - handle different formats
-        ohlcv_list = None
-
-        try:
-            import pandas as pd
+        async def _fetch_upstream() -> Optional[List]:
+            # Pass all parameters explicitly:
+            # - currency="token" means price in quote token (not USD)
+            # - token="base" means OHLCV for the base token
+            result = await gecko_call(
+                "get_ohlcv",
+                gecko_network,
+                pool_address,
+                timeframe,
+                before_timestamp=before_timestamp,
+                currency=currency,
+                token=token,
+                limit=limit,
+            )
 
-            if isinstance(result, pd.DataFrame):
-                if not result.empty:
-                    # Convert DataFrame to list format
-                    ohlcv_list = result.values.tolist()
-        except ImportError:
-            pass
+            # Parse response - handle different formats
+            rows = None
 
-        if ohlcv_list is None:
-            if isinstance(result, list):
-                ohlcv_list = result
-            elif isinstance(result, dict):
-                # Try nested structure
-                data = result.get("data", result)
-                if isinstance(data, dict):
-                    attrs = data.get("attributes", data)
-                    ohlcv_list = attrs.get("ohlcv_list", [])
-                elif isinstance(data, list):
-                    ohlcv_list = data
+            try:
+                import pandas as pd
+
+                if isinstance(result, pd.DataFrame):
+                    if not result.empty:
+                        # Convert DataFrame to list format
+                        rows = result.values.tolist()
+            except ImportError:
+                pass
+
+            if rows is None:
+                if isinstance(result, list):
+                    rows = result
+                elif isinstance(result, dict):
+                    # Try nested structure
+                    data = result.get("data", result)
+                    if isinstance(data, dict):
+                        attrs = data.get("attributes", data)
+                        rows = attrs.get("ohlcv_list", [])
+                    elif isinstance(data, list):
+                        rows = data
+
+            # Debug logging: show price range from OHLCV data
+            if rows:
+                try:
+                    closes = [float(c[4]) for c in rows if len(c) > 4 and c[4]]
+                    if closes:
+                        logger.info(
+                            f"OHLCV {pool_address[:8]}... {timeframe} currency={currency}: "
+                            f"{len(rows)} candles, price range [{min(closes):.6f} - {max(closes):.6f}]"
+                        )
+                except Exception as e:
+                    logger.debug(f"Could not log OHLCV price range: {e}")
+
+            return rows
+
+        # Coalesce on the UPSTREAM window — pool, timeframe, currency, priced side
+        # and window — never on the caller's cache key. The TTL caches above are
+        # per-caller and only help once an answer has landed, so two callers whose
+        # own keys differ (a chart keyed by trading pair and one keyed by pool, the
+        # dashboard's shared cache and a chat's user_data) still resolve to the very
+        # same GeckoTerminal window and would each spend a request for it. Keyed
+        # here, they collapse onto one. A fetch that raises reaches every waiter and
+        # is cached by nobody. The rows are shared between callers: read-only.
+        ohlcv_list = await _single_flight(
+            (
+                "ohlcv",
+                gecko_network,
+                pool_address,
+                timeframe,
+                currency,
+                token,
+                limit,
+                before_timestamp or 0,
+            ),
+            _fetch_upstream,
+        )
 
         if not ohlcv_list:
             return None, "No OHLCV data available"
 
-        # Debug logging: show price range from OHLCV data
-        if ohlcv_list:
-            try:
-                closes = [float(c[4]) for c in ohlcv_list if len(c) > 4 and c[4]]
-                if closes:
-                    logger.info(
-                        f"OHLCV {pool_address[:8]}... {timeframe} currency={currency}: "
-                        f"{len(ohlcv_list)} candles, price range [{min(closes):.6f} - {max(closes):.6f}]"
-                    )
-            except Exception as e:
-                logger.debug(f"Could not log OHLCV price range: {e}")
-
         # Cache result
         if user_data is not None:
             set_cached(user_data, cache_key, ohlcv_list, namespace=_CACHE_NS)
diff --git a/tests/test_ohlcv_upstream_coalescing.py b/tests/test_ohlcv_upstream_coalescing.py
new file mode 100644
index 00000000..cf53274a
--- /dev/null
+++ b/tests/test_ohlcv_upstream_coalescing.py
@@ -0,0 +1,219 @@
+"""In-flight coalescing at the GeckoTerminal OHLCV fetch (PERF-169).
+
+PERF-137 coalesced GET /market/candles on the *route's* cache key. That key
+carries things the upstream window does not — the trading pair, the server name
+— so two requests that resolve to the very same GeckoTerminal window still opened
+one upstream request each and spent the rate budget twice. The dedup that matters
+for the budget lives at the fetch, keyed by pool + timeframe + window.
+"""
+
+import asyncio
+
+import pytest
+
+import condor.web.routes.market as market
+from condor import dex_candles, pool_data
+from condor.web.models import WebUser
+
+POOL = "So11111111111111111111111111111111111111112"
+ROWS = [[1_700_000_000, 1.0, 2.0, 0.5, 1.5, 10.0]]
+
+
+@pytest.fixture(autouse=True)
+def _clean_state():
+    def _reset():
+        market._candle_cache.clear()
+        market._candle_inflight.clear()
+        dex_candles._ohlcv_cache.clear()
+        pool_data.reset_gecko_throttle()
+
+    _reset()
+    yield
+    _reset()
+
+
+class _CountingGecko:
+    """Counts get_ohlcv calls and holds them open until the gate is released."""
+
+    def __init__(self, gate=None, fail=False):
+        self.calls = 0
+        self._gate = gate
+        self._fail = fail
+
+    async def __call__(self, method, *args, **kwargs):
+        assert method == "get_ohlcv"
+        self.calls += 1
+        if self._gate is not None:
+            await self._gate
+        if self._fail:
+            raise RuntimeError("gecko down")
+        return list(ROWS)
+
+
+def _route_call(trading_pair: str):
+    """One GET /market/candles for a pool, charted under a given pair label."""
+    return market.get_candles(
+        "srv",
+        connector="meteora",
+        trading_pair=trading_pair,
+        interval="1m",
+        limit=100,
+        start_time=1_699_999_900.0,
+        end_time=1_700_000_100.0,
+        pool_address=POOL,
+        user=WebUser(id=1, role="user"),
+    )
+
+
+class _Cm:
+    def has_server_access(self, user_id, name):
+        return True
+
+    async def get_client(self, name):
+        raise AssertionError("the DEX path must not touch the API server")
+
+
+def test_two_route_keys_on_one_upstream_window_share_one_fetch(monkeypatch):
+    """The acceptance criterion, driven through the real route.
+
+    Both requests name the same pool, timeframe and window, but different trading
+    pairs — so the route's own cache key differs and PERF-137's guard cannot see
+    that they converge. Only the fetch-level dedup collapses them.
+    """
+
+    async def scenario():
+        gate = asyncio.get_running_loop().create_future()
+        gecko = _CountingGecko(gate=gate)
+        monkeypatch.setattr(pool_data, "gecko_call", gecko)
+        monkeypatch.setattr(market, "get_config_manager", lambda: _Cm())
+
+        tasks = [
+            asyncio.ensure_future(_route_call("SOL-USDC")),
+            asyncio.ensure_future(_route_call("So111111-USDC")),
+        ]
+        # Let both requests reach the (gated) upstream call before releasing it.
+        for _ in range(6):
+            await asyncio.sleep(0)
+        assert len(market._candle_inflight) == 2, "the route keys must differ"
+        gate.set_result(None)
+        results = await asyncio.gather(*tasks)
+        return gecko.calls, results
+
+    calls, results = asyncio.run(scenario())
+    assert calls == 1, "two route keys on one window must spend one gecko request"
+    assert [c.close for c in results[0]] == [c.close for c in results[1]]
+    assert results[0], "both callers get the candles, not an empty chart"
+
+
+def test_distinct_caller_caches_still_share_one_fetch(monkeypatch):
+    """Dedup keys on the upstream request, never on where the caller caches it."""
+
+    async def scenario():
+        gate = asyncio.get_running_loop().create_future()
+        gecko = _CountingGecko(gate=gate)
+        monkeypatch.setattr(pool_data, "gecko_call", gecko)
+
+        # Three callers: two with their own private caches, one with none at all.
+        caches = [{}, {}, None]
+        tasks = [
+            asyncio.ensure_future(
+                pool_data.fetch_ohlcv(
+                    POOL, "meteora", timeframe="1m", user_data=cache, limit=50
+                )
+            )
+            for cache in caches
+        ]
+        for _ in range(6):
+            await asyncio.sleep(0)
+        gate.set_result(None)
+        results = await asyncio.gather(*tasks)
+        return gecko.calls, results
+
+    calls, results = asyncio.run(scenario())
+    assert calls == 1
+    assert all(err is None and rows == ROWS for rows, err in results)
+
+
+def test_a_different_window_is_not_coalesced(monkeypatch):
+    """Same pool, different candle count: two genuinely different answers."""
+
+    async def scenario():
+        gate = asyncio.get_running_loop().create_future()
+        gecko = _CountingGecko(gate=gate)
+        monkeypatch.setattr(pool_data, "gecko_call", gecko)
+
+        tasks = [
+            asyncio.ensure_future(
+                pool_data.fetch_ohlcv(POOL, "meteora", timeframe="1m", limit=limit)
+            )
+            for limit in (50, 100)
+        ]
+        for _ in range(6):
+            await asyncio.sleep(0)
+        gate.set_result(None)
+        await asyncio.gather(*tasks)
+        return gecko.calls
+
+    assert asyncio.run(scenario()) == 2
+
+
+def test_a_failing_fetch_reaches_every_waiter_and_is_not_cached(monkeypatch):
+    """A failure is shared, never remembered: the next call retries clean."""
+
+    async def scenario():
+        gate = asyncio.get_running_loop().create_future()
+        failing = _CountingGecko(gate=gate, fail=True)
+        monkeypatch.setattr(pool_data, "gecko_call", failing)
+
+        cache = {}
+        tasks = [
+            asyncio.ensure_future(
+                pool_data.fetch_ohlcv(
+                    POOL, "meteora", timeframe="1m", user_data=cache, limit=50
+                )
+            )
+            for _ in range(3)
+        ]
+        for _ in range(6):
+            await asyncio.sleep(0)
+        gate.set_result(None)
+        failed = await asyncio.gather(*tasks)
+
+        # Nothing was written to the caller's cache, so the retry goes upstream.
+        healthy = _CountingGecko()
+        monkeypatch.setattr(pool_data, "gecko_call", healthy)
+        retried = await pool_data.fetch_ohlcv(
+            POOL, "meteora", timeframe="1m", user_data=cache, limit=50
+        )
+        return failing.calls, failed, healthy.calls, retried
+
+    fail_calls, failed, retry_calls, retried = asyncio.run(scenario())
+    assert fail_calls == 1, "the failing fetch is shared, not repeated per waiter"
+    assert all(rows is None and err for rows, err in failed), "every waiter sees it"
+    assert retry_calls == 1, "a failure is not cached; the next call retries"
+    assert retried == (ROWS, None)
+
+
+def test_a_cancelled_waiter_does_not_cancel_the_shared_fetch(monkeypatch):
+    """One viewer navigating away must not take the others' chart down with it."""
+
+    async def scenario():
+        gate = asyncio.get_running_loop().create_future()
+        gecko = _CountingGecko(gate=gate)
+        monkeypatch.setattr(pool_data, "gecko_call", gecko)
+
+        leaver = asyncio.ensure_future(
+            pool_data.fetch_ohlcv(POOL, "meteora", timeframe="1m", limit=50)
+        )
+        stayer = asyncio.ensure_future(
+            pool_data.fetch_ohlcv(POOL, "meteora", timeframe="1m", limit=50)
+        )
+        for _ in range(6):
+            await asyncio.sleep(0)
+        leaver.cancel()
+        gate.set_result(None)
+        return gecko.calls, await stayer
+
+    calls, rows = asyncio.run(scenario())
+    assert calls == 1
+    assert rows == (ROWS, None)

From 8a04b752d1aecc8ca6bf7e5bc548233fbd886a70 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Tue, 18 Aug 2026 00:03:45 +0300
Subject: [PATCH 109/116] (feat) improve dex viz and failing tests

---
 .github/workflows/ci.yml                      |   4 +-
 .../routines/baseline_7d.py                   |   4 +-
 .../routines/hourly_mtf_check.py              | 205 ++++++++++++++----
 .../routines/position_mode_check.py           |  12 +-
 condor/rates.py                               |   2 +-
 frontend/src/components/dex/LpPositions.tsx   |  22 +-
 frontend/src/components/dex/lp-position.ts    |  18 ++
 frontend/src/components/trade/TradeChart.tsx  |  27 ++-
 frontend/src/hooks/useMainControllerData.ts   | 105 ++++++---
 handlers/bots/controller_handlers.py          |  12 +-
 handlers/bots/menu.py                         |   4 +-
 mcp_servers/condor/server.py                  |   4 +-
 mcp_servers/hummingbot_api/middleware.py      |   6 +-
 pyproject.toml                                |   5 +-
 tests/test_agents.py                          |   5 +
 tests/test_config_manager_load_recovery.py    |   6 +-
 uv.lock                                       |  17 +-
 17 files changed, 333 insertions(+), 125 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index efe42daa..e7678cf7 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -94,8 +94,10 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
+      # Gates on *new* errors against eslint-baseline.json rather than on the
+      # 76 that predate this workflow -- see frontend/scripts/lint-baseline.mjs.
       - name: Lint
-        run: npm run lint
+        run: npm run lint:ci
 
       - name: Build
         run: npm run build
diff --git a/agents/adaptive_grid_trader/routines/baseline_7d.py b/agents/adaptive_grid_trader/routines/baseline_7d.py
index c6316712..2454b8f1 100644
--- a/agents/adaptive_grid_trader/routines/baseline_7d.py
+++ b/agents/adaptive_grid_trader/routines/baseline_7d.py
@@ -1,7 +1,9 @@
+import logging
+
 from pydantic import BaseModel, Field
 from telegram.ext import ContextTypes
+
 from config_manager import get_client
-import logging
 
 logger = logging.getLogger(__name__)
 
diff --git a/agents/adaptive_grid_trader/routines/hourly_mtf_check.py b/agents/adaptive_grid_trader/routines/hourly_mtf_check.py
index 7d72c43c..34693610 100644
--- a/agents/adaptive_grid_trader/routines/hourly_mtf_check.py
+++ b/agents/adaptive_grid_trader/routines/hourly_mtf_check.py
@@ -1,10 +1,12 @@
-from pydantic import BaseModel, Field
-from telegram.ext import ContextTypes
-from config_manager import get_client
 import asyncio
 import logging
 import math
 
+from pydantic import BaseModel, Field
+from telegram.ext import ContextTypes
+
+from config_manager import get_client
+
 logger = logging.getLogger(__name__)
 
 CATEGORY = "Analysis"
@@ -12,17 +14,25 @@
 
 class Config(BaseModel):
     """Multi-timeframe analysis → LONG_GRID / SHORT_GRID / TWO_SIDED_GRID / HOLD recommendation."""
+
     trading_pair: str = Field(default="BTC-USDT")
     connector_name: str = Field(default="binance_perpetual")
-    lifetime_hours: float = Field(default=8.0, description="Expected grid lifetime for range calculation (6-12h typical due to anti-flip rule)")
+    lifetime_hours: float = Field(
+        default=8.0,
+        description="Expected grid lifetime for range calculation (6-12h typical due to anti-flip rule)",
+    )
     atr_period: int = Field(default=14)
-    baseline_atr: float = Field(default=0.0, description="From baseline_7d — 0 means compute from 1h candles only")
+    baseline_atr: float = Field(
+        default=0.0,
+        description="From baseline_7d — 0 means compute from 1h candles only",
+    )
 
 
 # ---------------------------------------------------------------------------
 # Helpers
 # ---------------------------------------------------------------------------
 
+
 def _parse_candles(result) -> list:
     """Defensively parse candles from API response."""
     if result is None:
@@ -115,7 +125,9 @@ def _confidence(trend_4h: str, trend_1d: str, closes_1h: list) -> str:
     slow = _compute_ema(closes_1h, 21)
     if fast and slow and slow[-1]:
         diff = (fast[-1] - slow[-1]) / slow[-1] * 100
-        aligned = (trend_4h == "BULLISH" and diff > 0.3) or (trend_4h == "BEARISH" and diff < -0.3)
+        aligned = (trend_4h == "BULLISH" and diff > 0.3) or (
+            trend_4h == "BEARISH" and diff < -0.3
+        )
         return "HIGH" if aligned else "MEDIUM"
     return "MEDIUM"
 
@@ -124,6 +136,7 @@ def _confidence(trend_4h: str, trend_1d: str, closes_1h: list) -> str:
 # Main
 # ---------------------------------------------------------------------------
 
+
 async def run(config: Config, context: ContextTypes.DEFAULT_TYPE) -> str:
     client = await get_client(context._chat_id, context=context)
     if not client:
@@ -132,11 +145,17 @@ async def run(config: Config, context: ContextTypes.DEFAULT_TYPE) -> str:
     # -- 1. Fetch three timeframes in parallel --
     try:
         raw_1h, raw_4h, raw_1d = await asyncio.gather(
-            client.market_data.get_candles(config.connector_name, config.trading_pair, "1h", max_records=50),
+            client.market_data.get_candles(
+                config.connector_name, config.trading_pair, "1h", max_records=50
+            ),
             # _trend_direction needs slow EMA period + 2 = 23 candles minimum,
             # so keep a margin above that or the timeframe reads NEUTRAL forever.
-            client.market_data.get_candles(config.connector_name, config.trading_pair, "4h", max_records=60),
-            client.market_data.get_candles(config.connector_name, config.trading_pair, "1d", max_records=60),
+            client.market_data.get_candles(
+                config.connector_name, config.trading_pair, "4h", max_records=60
+            ),
+            client.market_data.get_candles(
+                config.connector_name, config.trading_pair, "1d", max_records=60
+            ),
         )
     except Exception as e:
         logger.error(f"[hourly_mtf_check] candle fetch failed: {e}")
@@ -156,7 +175,9 @@ async def run(config: Config, context: ContextTypes.DEFAULT_TYPE) -> str:
         atr_1h = (atr_1h + config.baseline_atr) / 2.0
 
     window_24 = candles_1h[-24:] if len(candles_1h) >= 24 else candles_1h
-    vol_level, range_high, range_low, range_pct, range_pos = _volatility_level(atr_1h, window_24)
+    vol_level, range_high, range_low, range_pct, range_pos = _volatility_level(
+        atr_1h, window_24
+    )
     current_price = float(candles_1h[-1].get("close", 0) or 0)
 
     # 4h: trend direction
@@ -168,20 +189,28 @@ async def run(config: Config, context: ContextTypes.DEFAULT_TYPE) -> str:
     # -- 3. Signal synthesis --
     if trend_4h == "BULLISH" and trend_1d == "BULLISH":
         profile = "LONG_GRID"
-        rationale = ("Both medium (4h) and macro (1d) timeframes confirm bullish momentum. "
-                     "Grid skewed upward — capture breakout while limiting downside exposure.")
+        rationale = (
+            "Both medium (4h) and macro (1d) timeframes confirm bullish momentum. "
+            "Grid skewed upward — capture breakout while limiting downside exposure."
+        )
     elif trend_4h == "BEARISH" and trend_1d == "BEARISH":
         profile = "SHORT_GRID"
-        rationale = ("Both medium (4h) and macro (1d) timeframes confirm bearish pressure. "
-                     "Grid skewed downward — profit from continued decline with capped upside risk.")
+        rationale = (
+            "Both medium (4h) and macro (1d) timeframes confirm bearish pressure. "
+            "Grid skewed downward — profit from continued decline with capped upside risk."
+        )
     elif vol_level in ("LOW", "MODERATE"):
         profile = "TWO_SIDED_GRID"
-        rationale = ("Timeframes disagree or both neutral with contained volatility — "
-                     "price is likely range-bound. Symmetric two-sided grid maximises fee capture.")
+        rationale = (
+            "Timeframes disagree or both neutral with contained volatility — "
+            "price is likely range-bound. Symmetric two-sided grid maximises fee capture."
+        )
     else:
         profile = "HOLD"
-        rationale = ("Conflicting signals combined with elevated volatility — "
-                     "directional conviction is insufficient. Avoid new grid entry.")
+        rationale = (
+            "Conflicting signals combined with elevated volatility — "
+            "directional conviction is insufficient. Avoid new grid entry."
+        )
 
     closes_1h = [float(c.get("close", 0) or 0) for c in candles_1h]
     conf = _confidence(trend_4h, trend_1d, closes_1h)
@@ -209,29 +238,85 @@ async def run(config: Config, context: ContextTypes.DEFAULT_TYPE) -> str:
     # -- Build levels table --
     if profile == "LONG_GRID":
         levels_rows = [
-            {"Level": "limit_price", "Price": f"{limit_price:,.4f}", "Description": "Abort / stop-loss if breached"},
-            {"Level": "start_price", "Price": f"{start_price:,.4f}", "Description": "Grid lower bound"},
-            {"Level": "current_price", "Price": f"{current_price:,.4f}", "Description": "Reference at analysis time"},
-            {"Level": "end_price", "Price": f"{end_price:,.4f}", "Description": "Grid upper bound / TP zone"},
+            {
+                "Level": "limit_price",
+                "Price": f"{limit_price:,.4f}",
+                "Description": "Abort / stop-loss if breached",
+            },
+            {
+                "Level": "start_price",
+                "Price": f"{start_price:,.4f}",
+                "Description": "Grid lower bound",
+            },
+            {
+                "Level": "current_price",
+                "Price": f"{current_price:,.4f}",
+                "Description": "Reference at analysis time",
+            },
+            {
+                "Level": "end_price",
+                "Price": f"{end_price:,.4f}",
+                "Description": "Grid upper bound / TP zone",
+            },
         ]
     elif profile == "SHORT_GRID":
         levels_rows = [
-            {"Level": "end_price", "Price": f"{end_price:,.4f}", "Description": "Grid upper bound"},
-            {"Level": "current_price", "Price": f"{current_price:,.4f}", "Description": "Reference at analysis time"},
-            {"Level": "start_price", "Price": f"{start_price:,.4f}", "Description": "Grid lower bound / TP zone"},
-            {"Level": "limit_price", "Price": f"{limit_price:,.4f}", "Description": "Abort / stop-loss if breached"},
+            {
+                "Level": "end_price",
+                "Price": f"{end_price:,.4f}",
+                "Description": "Grid upper bound",
+            },
+            {
+                "Level": "current_price",
+                "Price": f"{current_price:,.4f}",
+                "Description": "Reference at analysis time",
+            },
+            {
+                "Level": "start_price",
+                "Price": f"{start_price:,.4f}",
+                "Description": "Grid lower bound / TP zone",
+            },
+            {
+                "Level": "limit_price",
+                "Price": f"{limit_price:,.4f}",
+                "Description": "Abort / stop-loss if breached",
+            },
         ]
     elif profile == "TWO_SIDED_GRID":
         levels_rows = [
-            {"Level": "start_price", "Price": f"{start_price:,.4f}", "Description": "Grid lower bound (−2D)"},
-            {"Level": "current_price", "Price": f"{current_price:,.4f}", "Description": "Reference / centre"},
-            {"Level": "end_price", "Price": f"{end_price:,.4f}", "Description": "Grid upper bound (+2D)"},
+            {
+                "Level": "start_price",
+                "Price": f"{start_price:,.4f}",
+                "Description": "Grid lower bound (−2D)",
+            },
+            {
+                "Level": "current_price",
+                "Price": f"{current_price:,.4f}",
+                "Description": "Reference / centre",
+            },
+            {
+                "Level": "end_price",
+                "Price": f"{end_price:,.4f}",
+                "Description": "Grid upper bound (+2D)",
+            },
         ]
     else:
         levels_rows = [
-            {"Level": "ref_low", "Price": f"{start_price:,.4f}", "Description": "Reference lower (−D) — NOT ACTIONABLE"},
-            {"Level": "current_price", "Price": f"{current_price:,.4f}", "Description": "Reference at analysis time"},
-            {"Level": "ref_high", "Price": f"{end_price:,.4f}", "Description": "Reference upper (+D) — NOT ACTIONABLE"},
+            {
+                "Level": "ref_low",
+                "Price": f"{start_price:,.4f}",
+                "Description": "Reference lower (−D) — NOT ACTIONABLE",
+            },
+            {
+                "Level": "current_price",
+                "Price": f"{current_price:,.4f}",
+                "Description": "Reference at analysis time",
+            },
+            {
+                "Level": "ref_high",
+                "Price": f"{end_price:,.4f}",
+                "Description": "Reference upper (+D) — NOT ACTIONABLE",
+            },
         ]
 
     # -- 5. ReportBuilder --
@@ -239,10 +324,15 @@ async def run(config: Config, context: ContextTypes.DEFAULT_TYPE) -> str:
         from condor.reports import ReportBuilder
 
         builder = ReportBuilder(f"MTF Check — {config.trading_pair}")
-        builder.source("routine", "hourly_mtf_check").tags(["grid", "mtf", "analysis", "adaptive"])
+        builder.source("routine", "hourly_mtf_check").tags(
+            ["grid", "mtf", "analysis", "adaptive"]
+        )
 
         # Section 1: Timeframe Summary
-        builder.section("01 / TIMEFRAME SUMMARY", "Per-timeframe: trend direction, ATR/volatility, signal")
+        builder.section(
+            "01 / TIMEFRAME SUMMARY",
+            "Per-timeframe: trend direction, ATR/volatility, signal",
+        )
         tf_rows = [
             {
                 "Timeframe": "1h (Range & Vol)",
@@ -275,10 +365,25 @@ async def run(config: Config, context: ContextTypes.DEFAULT_TYPE) -> str:
                 "Signal": trend_1d,
             },
         ]
-        builder.table(tf_rows, ["Timeframe", "Candles", "ATR(14)", "24h Range", "Range %", "Volatility", "Price in Range", "Signal"])
+        builder.table(
+            tf_rows,
+            [
+                "Timeframe",
+                "Candles",
+                "ATR(14)",
+                "24h Range",
+                "Range %",
+                "Volatility",
+                "Price in Range",
+                "Signal",
+            ],
+        )
 
         # Section 2: Signal Synthesis
-        builder.section("02 / SIGNAL SYNTHESIS", "Agreement analysis across timeframes and final profile decision")
+        builder.section(
+            "02 / SIGNAL SYNTHESIS",
+            "Agreement analysis across timeframes and final profile decision",
+        )
         builder.kpi("4h Trend", trend_4h)
         builder.kpi("1d Trend", trend_1d)
         builder.kpi("1h Volatility", vol_level)
@@ -288,12 +393,18 @@ async def run(config: Config, context: ContextTypes.DEFAULT_TYPE) -> str:
             f"**4h vs 1d agreement:** {agreement_str}  \n"
             f"**Current price:** {current_price:,.4f}  \n"
             f"**ATR(1h, {config.atr_period}):** {atr_1h:.6f}"
-            + (f"  *(blended with baseline {config.baseline_atr})*" if config.baseline_atr > 0 else "") +
-            f"  \n**D = ATR × √{config.lifetime_hours:.1f}h = {D:.6f}**"
+            + (
+                f"  *(blended with baseline {config.baseline_atr})*"
+                if config.baseline_atr > 0
+                else ""
+            )
+            + f"  \n**D = ATR × √{config.lifetime_hours:.1f}h = {D:.6f}**"
         )
 
         # Section 3: Recommendation
-        builder.section("03 / RECOMMENDATION", "Actionable grid profile with concrete price levels")
+        builder.section(
+            "03 / RECOMMENDATION", "Actionable grid profile with concrete price levels"
+        )
         builder.kpi("Profile", profile)
         builder.kpi("Confidence", conf)
         builder.kpi("D Value", f"{D:.4f}")
@@ -302,7 +413,9 @@ async def run(config: Config, context: ContextTypes.DEFAULT_TYPE) -> str:
         actionable = profile != "HOLD"
         if limit_price is not None:
             builder.kpi("Limit Price", f"{limit_price:,.4f}")
-        builder.kpi("Start Price", f"{start_price:,.4f}" + ("" if actionable else " (ref)"))
+        builder.kpi(
+            "Start Price", f"{start_price:,.4f}" + ("" if actionable else " (ref)")
+        )
         builder.kpi("End Price", f"{end_price:,.4f}" + ("" if actionable else " (ref)"))
 
         builder.table(levels_rows, ["Level", "Price", "Description"])
@@ -322,12 +435,18 @@ async def run(config: Config, context: ContextTypes.DEFAULT_TYPE) -> str:
         f"Current price: {current_price:,.4f} | ATR(1h): {atr_1h:.6f} | D: {D:.6f}",
     ]
     if profile == "LONG_GRID":
-        lines.append(f"limit_price={limit_price:.4f} | start_price={start_price:.4f} | end_price={end_price:.4f}")
+        lines.append(
+            f"limit_price={limit_price:.4f} | start_price={start_price:.4f} | end_price={end_price:.4f}"
+        )
     elif profile == "SHORT_GRID":
-        lines.append(f"start_price={start_price:.4f} | end_price={end_price:.4f} | limit_price={limit_price:.4f}")
+        lines.append(
+            f"start_price={start_price:.4f} | end_price={end_price:.4f} | limit_price={limit_price:.4f}"
+        )
     elif profile == "TWO_SIDED_GRID":
         lines.append(f"start_price={start_price:.4f} | end_price={end_price:.4f}")
     else:
-        lines.append(f"ref_low={start_price:.4f} | ref_high={end_price:.4f} [NOT ACTIONABLE]")
+        lines.append(
+            f"ref_low={start_price:.4f} | ref_high={end_price:.4f} [NOT ACTIONABLE]"
+        )
     lines.append(f"Rationale: {rationale}")
     return "\n".join(lines)
diff --git a/agents/adaptive_grid_trader/routines/position_mode_check.py b/agents/adaptive_grid_trader/routines/position_mode_check.py
index ed0ff202..f2f405e7 100644
--- a/agents/adaptive_grid_trader/routines/position_mode_check.py
+++ b/agents/adaptive_grid_trader/routines/position_mode_check.py
@@ -1,7 +1,9 @@
+import logging
+
 from pydantic import BaseModel, Field
 from telegram.ext import ContextTypes
+
 from config_manager import get_client
-import logging
 
 logger = logging.getLogger(__name__)
 
@@ -119,9 +121,13 @@ async def run(config: Config, context: ContextTypes.DEFAULT_TYPE) -> str:
                 "so level math and the liquidation guard would both be wrong"
             )
             if flat:
-                reason += ". Account is flat, so HEDGE could be set if two-sided is wanted"
+                reason += (
+                    ". Account is flat, so HEDGE could be set if two-sided is wanted"
+                )
             else:
-                reason += ". Account is not flat, so the mode cannot be changed right now"
+                reason += (
+                    ". Account is not flat, so the mode cannot be changed right now"
+                )
 
     lines = [f"Position Mode — {config.connector_name}", f"mode: {mode}"]
     if shrug_note:
diff --git a/condor/rates.py b/condor/rates.py
index ee43436d..2e8660c3 100644
--- a/condor/rates.py
+++ b/condor/rates.py
@@ -17,7 +17,7 @@ def _normalize(token: str) -> str:
 
 
 def merge_price_pool(
-    tickers_by_connector: Dict[str, Dict[str, dict]]
+    tickers_by_connector: Dict[str, Dict[str, dict]],
 ) -> Dict[str, float]:
     """Merge per-connector tickers into one `{pair: price}` pool.
 
diff --git a/frontend/src/components/dex/LpPositions.tsx b/frontend/src/components/dex/LpPositions.tsx
index 2017bc44..365a95d8 100644
--- a/frontend/src/components/dex/LpPositions.tsx
+++ b/frontend/src/components/dex/LpPositions.tsx
@@ -5,6 +5,8 @@ import { useNavigate } from "react-router-dom";
 
 import {
   LP_EXECUTOR_TYPE,
+  LP_REFRESH_MS,
+  RECENT_LP_EXECUTORS,
   feeAmount,
   lpStateStyle,
   readLpPosition,
@@ -13,20 +15,6 @@ import {
 import { api, type PoolSummary } from "@/lib/api";
 import { formatPnl, formatUsd, isExecutorActive, pnlColor } from "@/lib/formatters";
 
-/** Live enough to see a range break without hammering the API. */
-const REFRESH_MS = 20_000;
-
-/**
- * How far back the poll reads.
- *
- * The upstream search has no usable "open only" filter (its `status` values are
- * not the ones the API normalizes to), so open positions are found by reading
- * recent executors and filtering here. Unbounded that is a walk of the entire
- * history every {@link REFRESH_MS}; the search answers newest-first and an open
- * LP position is by definition recent, so the newest few hundred contain them.
- */
-const RECENT_EXECUTORS = 200;
-
 /** GeckoTerminal's multi-pool endpoint, which the labels come from, caps here. */
 const MAX_LABELLED_POOLS = 30;
 
@@ -68,10 +56,10 @@ export function LpPositions({ server }: { server: string }) {
     queryFn: () =>
       api.getExecutors(server, {
         executor_type: LP_EXECUTOR_TYPE,
-        limit: RECENT_EXECUTORS,
+        limit: RECENT_LP_EXECUTORS,
       }),
-    refetchInterval: REFRESH_MS,
-    staleTime: REFRESH_MS,
+    refetchInterval: LP_REFRESH_MS,
+    staleTime: LP_REFRESH_MS,
   });
 
   const positions = useMemo(() => {
diff --git a/frontend/src/components/dex/lp-position.ts b/frontend/src/components/dex/lp-position.ts
index 3eabd928..b55749d1 100644
--- a/frontend/src/components/dex/lp-position.ts
+++ b/frontend/src/components/dex/lp-position.ts
@@ -4,6 +4,24 @@ import { formatUsd } from "@/lib/formatters";
 /** LP executors are the only ones the DEX pages can route to a pool. */
 export const LP_EXECUTOR_TYPE = "lp_executor";
 
+/** Live enough to see a range break without hammering the API. */
+export const LP_REFRESH_MS = 20_000;
+
+/**
+ * How far back a "which LP positions exist" poll reads.
+ *
+ * The upstream search has no usable "open only" filter (its `status` values are
+ * not the ones the API normalizes to), so open positions are found by reading
+ * recent executors and filtering client-side. Unbounded that is a walk of the
+ * entire history every {@link LP_REFRESH_MS}; the search answers newest-first and
+ * an open LP position is by definition recent, so the newest few hundred contain
+ * them.
+ *
+ * Shared by the `/dex` strip and a pool's own page so both issue the *same*
+ * query — one cache entry, and opening a pool from the strip costs no fetch.
+ */
+export const RECENT_LP_EXECUTORS = 200;
+
 function num(v: unknown): number | null {
   if (v === null || v === undefined || v === "") return null;
   const n = typeof v === "number" ? v : parseFloat(String(v));
diff --git a/frontend/src/components/trade/TradeChart.tsx b/frontend/src/components/trade/TradeChart.tsx
index 36fc853e..77fed911 100644
--- a/frontend/src/components/trade/TradeChart.tsx
+++ b/frontend/src/components/trade/TradeChart.tsx
@@ -363,8 +363,17 @@ export function TradeChart({
         const volStr = _cvtVal ? _cvtVal(o.volume) : (Math.abs(o.volume) >= 1000 ? `$${(o.volume / 1000).toFixed(1)}K` : `$${o.volume.toFixed(0)}`);
         const feesStr = o.fees ? (_cvtVal ? _cvtVal(o.fees) : `$${o.fees.toFixed(2)}`) : "";
 
-        const sideClr = sideColor(o.side);
-        const sideBg = o.side === "buy" ? "rgba(34,197,94,0.15)" : "rgba(239,68,68,0.15)";
+        // An LP position has no direction -- it is `RANGE` -- and the buy/sell
+        // normalization files everything that is not a buy under "sell", which
+        // labelled a live two-sided range position `SELL`. Neutral for that type.
+        const isRangeSide = o.type === "lp";
+        const sideLabel = isRangeSide ? "range" : o.side;
+        const sideClr = isRangeSide ? "#9ca3af" : sideColor(o.side);
+        const sideBg = isRangeSide
+          ? "rgba(156,163,175,0.15)"
+          : o.side === "buy"
+            ? "rgba(34,197,94,0.15)"
+            : "rgba(239,68,68,0.15)";
         const statusBg = o.status?.toLowerCase() === "running" || o.status?.toLowerCase() === "active"
           ? "rgba(34,197,94,0.15)" : "rgba(156,163,175,0.15)";
         const statusClr = o.status?.toLowerCase() === "running" || o.status?.toLowerCase() === "active"
@@ -423,7 +432,7 @@ export function TradeChart({
         tooltip.innerHTML = `
           <div style="display:flex;align-items:center;gap:6px;margin-bottom:6px">
             <span style="font-weight:700;font-size:12px;font-family:monospace">${escapeHtml(o.executorId.slice(0, 10))}\u2026</span>
-            <span style="background:${sideBg};color:${sideClr};font-size:9px;font-weight:700;padding:1px 5px;border-radius:3px;text-transform:uppercase">${escapeHtml(o.side)}</span>
+            <span style="background:${sideBg};color:${sideClr};font-size:9px;font-weight:700;padding:1px 5px;border-radius:3px;text-transform:uppercase">${escapeHtml(sideLabel)}</span>
             <span style="background:${statusBg};color:${statusClr};font-size:9px;font-weight:600;padding:1px 5px;border-radius:3px">${escapeHtml(o.status)}</span>
           </div>
           <div style="display:flex;align-items:center;gap:4px;margin-bottom:2px">
@@ -715,9 +724,15 @@ export function TradeChart({
         extraLinesRef.current.push(pl);
       }
     }
-  }, [startPrice, endPrice, limitPrice, side, minSpread, totalAmountQuote, minOrderAmountQuote, activePickField, extraLines]);
+  }, [startPrice, endPrice, limitPrice, side, minSpread, totalAmountQuote, minOrderAmountQuote, activePickField, extraLines, chartReady]);
 
   // ── Executor overlays ──
+  // `chartReady` is a dependency, not a guard for its own sake: lightweight-charts
+  // is imported lazily, so on a warm cache the overlays exist before the chart
+  // does and this effect bails out. Without the flag in the deps nothing re-runs
+  // it -- executors keep a stable reference across refetches by design -- and the
+  // page renders candles with no box on them until an executor's PnL happens to
+  // move. Every effect below that draws through `chartModuleRef` needs the same.
   useEffect(() => {
     const chart = chartRef.current;
     const series = seriesRef.current;
@@ -883,7 +898,7 @@ export function TradeChart({
         }
       }
     }
-  }, [filteredOverlays, selectedExecutorId]);
+  }, [filteredOverlays, selectedExecutorId, chartReady]);
 
   // ── Zoom to selected executor (one-time action) ──
   useEffect(() => {
@@ -948,7 +963,7 @@ export function TradeChart({
       });
       positionLinesRef.current.push(pl);
     }
-  }, [positions]);
+  }, [positions, chartReady]);
 
   // ── Measure tool helpers ──
   const clearMeasure = () => {
diff --git a/frontend/src/hooks/useMainControllerData.ts b/frontend/src/hooks/useMainControllerData.ts
index 4668e89c..3d38fc22 100644
--- a/frontend/src/hooks/useMainControllerData.ts
+++ b/frontend/src/hooks/useMainControllerData.ts
@@ -1,16 +1,14 @@
-import { useMemo, useRef } from "react";
+import { useMemo } from "react";
 import { useQuery, keepPreviousData } from "@tanstack/react-query";
 
+import {
+  LP_EXECUTOR_TYPE,
+  LP_REFRESH_MS,
+  RECENT_LP_EXECUTORS,
+} from "@/components/dex/lp-position";
 import { api, type ExecutorInfo } from "@/lib/api";
 import { computeMultiOverlays } from "@/lib/executor-overlays";
 
-/** Build a fingerprint string for an executor array to detect real changes */
-function executorsFingerprint(exs: ExecutorInfo[]): string {
-  return exs
-    .map((e) => `${e.id}:${e.status}:${e.pnl}:${e.entry_price}:${e.current_price}:${e.close_timestamp}`)
-    .join("|");
-}
-
 /** The pool an executor traded in, from wherever it records one. */
 function executorPool(ex: ExecutorInfo): string {
   return (
@@ -32,12 +30,16 @@ interface Options {
    */
   altPair?: string;
   /**
-   * Keep only the liquidity positions held in this exact pool.
+   * The pool the page is about, which is also how its LP positions are found.
    *
-   * On a pool-first page the pair is not the identity -- `SOL-USDC` names dozens
-   * of pools -- and a position lives in exactly one of them, so an LP executor
-   * that records a different pool is dropped. Swaps are not filtered: an order is
-   * a fact about the pair, and the router picks its own pool for it.
+   * Two jobs. It keeps only the liquidity held in *this* pool: on a pool-first
+   * page the pair is not the identity -- `SOL-USDC` names dozens of pools -- and
+   * a position lives in exactly one of them, so an LP executor recording a
+   * different pool is dropped. Swaps are not filtered: an order is a fact about
+   * the pair, and the router picks its own pool for it.
+   *
+   * It is also queried on directly, because no spelling of the pair reliably
+   * finds an LP position -- see the by-pool query below.
    */
   poolAddress?: string;
 }
@@ -69,11 +71,54 @@ export function useMainControllerData(
     refetchOnWindowFocus: false,
   });
 
-  // connector and pool are not server-side filters — apply them client-side
-  const filteredExecutors = useMemo(() => {
+  /**
+   * Every recent LP executor on the server, narrowed to the ones in this pool.
+   *
+   * Neither pair query above is guaranteed to find a position. The API's pair
+   * filter is case-sensitive and matches whatever spelling the *creator* used,
+   * while `altPair` is built from the pool row, whose symbols are upper-cased --
+   * so a real position in `GMEx-USDC` is asked for as `GMEX-USDC` and comes back
+   * empty, and the pool page renders no box on the chart and no row in the table.
+   * The pool address is the one identifier both sides spell identically, so it is
+   * matched on directly here.
+   *
+   * Same query as the `/dex` strip, key included, so arriving from there -- the
+   * usual way into a pool you hold -- costs no extra fetch.
+   */
+  const { data: poolLpExecutors } = useQuery<ExecutorInfo[]>({
+    queryKey: ["dex-lp-executors", server],
+    queryFn: () =>
+      api.getExecutors(server!, {
+        executor_type: LP_EXECUTOR_TYPE,
+        limit: RECENT_LP_EXECUTORS,
+      }),
+    enabled: !!server && !!poolAddress,
+    refetchInterval: LP_REFRESH_MS,
+    staleTime: LP_REFRESH_MS,
+  });
+
+  // connector and pool are not server-side filters — apply them client-side.
+  //
+  // No identity stabiliser sits on top of this: react-query's structural
+  // sharing (on by default) hands back the *same* array reference when a
+  // refetch returns deep-equal JSON, so an idle market already re-runs this
+  // memo zero times. The hand-rolled fingerprint+ref that used to guard it
+  // compared six fields, which made it both redundant here and a staleness
+  // trap -- a change to any seventh field kept serving the old rows.
+  const executors = useMemo(() => {
     const seen = new Set<string>();
     const rows: ExecutorInfo[] = [];
-    for (const ex of [...(cachedExecutors ?? []), ...(wantsAlt ? altExecutors ?? [] : [])]) {
+    // The by-pool rows are the whole server's LP history, so they are admitted
+    // only on an exact pool match -- unlike the pair rows, which were already
+    // scoped by the query that fetched them.
+    const inThisPool = poolAddress
+      ? (poolLpExecutors ?? []).filter((ex) => executorPool(ex) === poolAddress)
+      : [];
+    for (const ex of [
+      ...(cachedExecutors ?? []),
+      ...(wantsAlt ? (altExecutors ?? []) : []),
+      ...inThisPool,
+    ]) {
       if (seen.has(ex.id)) continue;
       seen.add(ex.id);
       if (ex.connector !== connector) continue;
@@ -84,20 +129,7 @@ export function useMainControllerData(
       rows.push(ex);
     }
     return rows;
-  }, [cachedExecutors, altExecutors, wantsAlt, connector, poolAddress]);
-
-  // Stable reference: only update when executor data actually changes
-  const prevFingerprintRef = useRef("");
-  const stableExecutorsRef = useRef<ExecutorInfo[]>([]);
-
-  const executors = useMemo(() => {
-    const fp = executorsFingerprint(filteredExecutors);
-    if (fp !== prevFingerprintRef.current) {
-      prevFingerprintRef.current = fp;
-      stableExecutorsRef.current = filteredExecutors;
-    }
-    return stableExecutorsRef.current;
-  }, [filteredExecutors]);
+  }, [cachedExecutors, altExecutors, poolLpExecutors, wantsAlt, connector, poolAddress]);
 
   const overlays = useMemo(() => computeMultiOverlays(executors), [executors]);
 
@@ -117,9 +149,14 @@ export function useMainControllerData(
       ...(positionsData.executor_positions ?? []),
       ...(positionsData.bot_positions ?? []),
     ];
-    // A position is named the same two ways its executor is, so both spellings
-    // of the market count as this market.
-    const pairs = new Set([pair, ...(wantsAlt ? [altPair] : [])]);
+    // A position is named however its executor is, and an executor found by pool
+    // may spell the market a third way neither `pair` nor `altPair` predicted --
+    // so the spellings that actually turned up count as this market too.
+    const pairs = new Set([
+      pair,
+      ...(wantsAlt ? [altPair] : []),
+      ...executors.map((ex) => ex.trading_pair).filter(Boolean),
+    ]);
     return all.filter(
       (p) =>
         // Show positions from main controller or untagged (executor-level positions)
@@ -127,7 +164,7 @@ export function useMainControllerData(
         p.connector_name === connector &&
         pairs.has(p.trading_pair),
     );
-  }, [positionsData, connector, pair, altPair, wantsAlt]);
+  }, [positionsData, connector, pair, altPair, wantsAlt, executors]);
 
   return { executors, overlays, positions, isLoadingPositions };
 }
diff --git a/handlers/bots/controller_handlers.py b/handlers/bots/controller_handlers.py
index 9786ebc3..46dabdd5 100644
--- a/handlers/bots/controller_handlers.py
+++ b/handlers/bots/controller_handlers.py
@@ -275,7 +275,9 @@ async def show_controller_configs_menu(
             nav = []
             if page > 0:
                 nav.append(
-                    InlineKeyboardButton("◀️", callback_data=f"bots:cfg_page:{page - 1}")
+                    InlineKeyboardButton(
+                        "◀️", callback_data=f"bots:cfg_page:{page - 1}"
+                    )
                 )
             nav.append(
                 InlineKeyboardButton(
@@ -284,7 +286,9 @@ async def show_controller_configs_menu(
             )
             if page < total_pages - 1:
                 nav.append(
-                    InlineKeyboardButton("▶️", callback_data=f"bots:cfg_page:{page + 1}")
+                    InlineKeyboardButton(
+                        "▶️", callback_data=f"bots:cfg_page:{page + 1}"
+                    )
                 )
             keyboard.append(nav)
 
@@ -5181,7 +5185,9 @@ def _build_deploy_progressive_message(
             value_display = f"{default} (default)" if default else "Not set"
 
         if field_name == current_field:
-            lines.append(f"➡️ *{escape_markdown_v2(label)}*{required}: _awaiting input_")
+            lines.append(
+                f"➡️ *{escape_markdown_v2(label)}*{required}: _awaiting input_"
+            )
         elif DEPLOY_FIELD_ORDER.index(field_name) < DEPLOY_FIELD_ORDER.index(
             current_field
         ):
diff --git a/handlers/bots/menu.py b/handlers/bots/menu.py
index 34df06a1..3e895853 100644
--- a/handlers/bots/menu.py
+++ b/handlers/bots/menu.py
@@ -951,7 +951,9 @@ async def handle_confirm_stop_controller(
         keyboard = [
             [
                 InlineKeyboardButton("▶️ Restart", callback_data="bots:start_ctrl"),
-                InlineKeyboardButton("⬅️ Back to Bot", callback_data="bots:back_to_bot"),
+                InlineKeyboardButton(
+                    "⬅️ Back to Bot", callback_data="bots:back_to_bot"
+                ),
             ]
         ]
 
diff --git a/mcp_servers/condor/server.py b/mcp_servers/condor/server.py
index 6eeb170e..6aee6e1a 100644
--- a/mcp_servers/condor/server.py
+++ b/mcp_servers/condor/server.py
@@ -11,7 +11,9 @@
 from mcp_servers.condor.tools import available_models as available_models_tool
 from mcp_servers.condor.tools import code as code_tool
 from mcp_servers.condor.tools import consult as consult_tool
-from mcp_servers.condor.tools import context
+from mcp_servers.condor.tools import (
+    context,
+)
 from mcp_servers.condor.tools import delegate as delegate_tool
 from mcp_servers.condor.tools import (
     memory,
diff --git a/mcp_servers/hummingbot_api/middleware.py b/mcp_servers/hummingbot_api/middleware.py
index 8fe5726a..84875261 100644
--- a/mcp_servers/hummingbot_api/middleware.py
+++ b/mcp_servers/hummingbot_api/middleware.py
@@ -9,7 +9,9 @@
 from mcp_servers.hummingbot_api.exceptions import (
     MaxConnectionsAttemptError as HBConnectionError,
 )
-from mcp_servers.hummingbot_api.exceptions import ToolError
+from mcp_servers.hummingbot_api.exceptions import (
+    ToolError,
+)
 
 logger = logging.getLogger("hummingbot-mcp")
 
@@ -36,7 +38,7 @@ def handle_errors(
     """
 
     def decorator(
-        func: Callable[..., Coroutine[Any, Any, T]]
+        func: Callable[..., Coroutine[Any, Any, T]],
     ) -> Callable[..., Coroutine[Any, Any, T]]:
         @functools.wraps(func)
         async def wrapper(*args: Any, **kwargs: Any) -> T:
diff --git a/pyproject.toml b/pyproject.toml
index 70d7398c..a0d3be28 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -27,7 +27,10 @@ dependencies = [
     "bleach>=6.4.0",
 ]
 
-[project.optional-dependencies]
+[dependency-groups]
+# PEP 735 group: this is what ``uv sync --dev`` installs. Declared as an
+# optional-dependencies extra it was invisible to ``--dev``, so CI ran
+# ``black --check`` with no black on PATH and failed to spawn it.
 dev = ["pytest", "pytest-asyncio", "black", "isort", "pre-commit"]
 
 [tool.isort]
diff --git a/tests/test_agents.py b/tests/test_agents.py
index 82205f6f..d7723127 100644
--- a/tests/test_agents.py
+++ b/tests/test_agents.py
@@ -744,6 +744,11 @@ def get_server(self, name):
                 "password": 123,
             }
 
+        def has_server_access(self, user_id, server_name, *args, **kwargs):
+            # SEC-178: the resolver holds every candidate to reach, not just
+            # existence. This double owns the server it hands out.
+            return True
+
     monkeypatch.setattr(
         config_manager, "get_config_manager", lambda: _NumericPasswordServer()
     )
diff --git a/tests/test_config_manager_load_recovery.py b/tests/test_config_manager_load_recovery.py
index fc9b9095..9fe6e508 100644
--- a/tests/test_config_manager_load_recovery.py
+++ b/tests/test_config_manager_load_recovery.py
@@ -21,14 +21,12 @@
     "version": 1,
 }
 
-INVALID_YAML = textwrap.dedent(
-    """\
+INVALID_YAML = textwrap.dedent("""\
     servers:
       prod:
         url: http://localhost:8000
        username: broken-indentation
-    """
-)
+    """)
 
 
 @pytest.fixture
diff --git a/uv.lock b/uv.lock
index 76f03edf..a25fe8e0 100644
--- a/uv.lock
+++ b/uv.lock
@@ -622,7 +622,7 @@ dependencies = [
     { name = "watchfiles" },
 ]
 
-[package.optional-dependencies]
+[package.dev-dependencies]
 dev = [
     { name = "black" },
     { name = "isort" },
@@ -635,23 +635,18 @@ dev = [
 requires-dist = [
     { name = "aiohttp" },
     { name = "beautifulsoup4", specifier = ">=4.14.3" },
-    { name = "black", marker = "extra == 'dev'" },
     { name = "bleach", specifier = ">=6.4.0" },
     { name = "fastapi" },
     { name = "faster-whisper" },
     { name = "geckoterminal-py" },
     { name = "hummingbot-api-client", specifier = "==1.5.7" },
-    { name = "isort", marker = "extra == 'dev'" },
     { name = "kaleido" },
     { name = "markdown", specifier = ">=3.10.2" },
     { name = "matplotlib", specifier = ">=3.10.8" },
     { name = "mcp" },
     { name = "pandas" },
     { name = "plotly" },
-    { name = "pre-commit", marker = "extra == 'dev'" },
     { name = "pydantic-ai", extras = ["mcp"] },
-    { name = "pytest", marker = "extra == 'dev'" },
-    { name = "pytest-asyncio", marker = "extra == 'dev'" },
     { name = "python-dotenv" },
     { name = "python-jose", extras = ["cryptography"] },
     { name = "python-telegram-bot", extras = ["job-queue"] },
@@ -660,7 +655,15 @@ requires-dist = [
     { name = "uvicorn", extras = ["standard"] },
     { name = "watchfiles" },
 ]
-provides-extras = ["dev"]
+
+[package.metadata.requires-dev]
+dev = [
+    { name = "black" },
+    { name = "isort" },
+    { name = "pre-commit" },
+    { name = "pytest" },
+    { name = "pytest-asyncio" },
+]
 
 [[package]]
 name = "contourpy"

From 9b10e73407fe87ed149e419871845c9c220b79aa Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Tue, 18 Aug 2026 00:04:03 +0300
Subject: [PATCH 110/116] (feat) update front

---
 frontend/package.json                         |   2 +
 .../src/components/dex/PoolSourceTabs.tsx     |  44 +-
 .../src/components/executor/LPConfigPanel.tsx | 399 +-----------------
 .../executor/PositionConfigPanel.tsx          |   2 +-
 frontend/src/components/executor/fields.tsx   |  12 +-
 .../src/components/grid/GridConfigPanel.tsx   |   3 +-
 frontend/src/pages/CreateExecutor.tsx         |  52 ++-
 frontend/src/pages/Dex.tsx                    |   6 +-
 frontend/src/pages/DexPool.tsx                |   6 +-
 9 files changed, 71 insertions(+), 455 deletions(-)

diff --git a/frontend/package.json b/frontend/package.json
index e2439edd..7951deaa 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -7,6 +7,8 @@
     "dev": "vite",
     "build": "tsc -b && vite build",
     "lint": "eslint .",
+    "lint:ci": "node scripts/lint-baseline.mjs",
+    "lint:baseline": "node scripts/lint-baseline.mjs",
     "preview": "vite preview"
   },
   "dependencies": {
diff --git a/frontend/src/components/dex/PoolSourceTabs.tsx b/frontend/src/components/dex/PoolSourceTabs.tsx
index 33a05841..16e8046d 100644
--- a/frontend/src/components/dex/PoolSourceTabs.tsx
+++ b/frontend/src/components/dex/PoolSourceTabs.tsx
@@ -3,44 +3,14 @@ import { useEffect, useMemo, useRef, useState } from "react";
 
 import type { DexChain, DexVenue } from "@/lib/api";
 
-/**
- * Which pool listing to browse. The upstreams take genuinely different arguments
- * — GeckoTerminal ranks a *chain*'s pools and searches by address, Gateway CLMM
- * lists one *connector*'s pools and searches free text, favourites are a local
- * list of addresses — so they are separate tabs rather than one filter row.
- */
-export type PoolSource =
-  | { kind: "gecko"; view: "trending" | "top" | "new" | "token" }
-  | { kind: "gateway"; connector: string }
-  | { kind: "favorites" };
-
-export const GECKO_TABS = [
-  { view: "trending", label: "Trending" },
-  { view: "top", label: "Top" },
-  { view: "new", label: "New" },
-  { view: "token", label: "Search" },
-] as const;
+import {
+  GATEWAY_TAB_CHAIN,
+  GATEWAY_TABS,
+  GECKO_TABS,
+  type PoolSource,
+  sameSource,
+} from "./pool-source";
 
-/**
- * The CLMM connectors Gateway can list pools for (and open positions in).
- *
- * Both are Solana venues, so these tabs are hidden on any other chain: a Meteora
- * tab on Base lists nothing and offers no position to open, which is worse than
- * not offering it. GeckoTerminal browsing works on every chain either way.
- */
-export const GATEWAY_TABS = [
-  { connector: "meteora", label: "Meteora" },
-  { connector: "orca", label: "Orca" },
-] as const;
-
-export const GATEWAY_TAB_CHAIN = "solana";
-
-export function sameSource(a: PoolSource, b: PoolSource): boolean {
-  if (a.kind === "gecko" && b.kind === "gecko") return a.view === b.view;
-  if (a.kind === "gateway" && b.kind === "gateway")
-    return a.connector === b.connector;
-  return a.kind === "favorites" && b.kind === "favorites";
-}
 
 /**
  * Pills rather than underlined tabs, because there are seven of them and they no
diff --git a/frontend/src/components/executor/LPConfigPanel.tsx b/frontend/src/components/executor/LPConfigPanel.tsx
index 3b768748..4c62c6fc 100644
--- a/frontend/src/components/executor/LPConfigPanel.tsx
+++ b/frontend/src/components/executor/LPConfigPanel.tsx
@@ -1,5 +1,4 @@
-import { useQuery } from "@tanstack/react-query";
-import { useEffect, useMemo, useReducer } from "react";
+import { useEffect } from "react";
 import { AlertTriangle, Sparkles } from "lucide-react";
 
 import {
@@ -13,390 +12,18 @@ import {
   ValidationMessages,
   type FieldDispatch,
 } from "./fields";
-import type { ChartPriceMapping, ExecutorValidation, PickSlot } from "./types";
-import { api, type DexPoolInfo } from "@/lib/api";
-import { getThemeColors } from "@/lib/theme-colors";
-
-// ── Sides ──
-// `side` is a TradeType enum, not a direction: it says which token(s) you are
-// putting in, which in turn dictates where the range sits relative to the price.
-
-export const LP_SIDE_BUY = 1; // quote-only, range below the price
-export const LP_SIDE_SELL = 2; // base-only, range above the price
-export const LP_SIDE_RANGE = 3; // both tokens, range centered
-
-export type LpSide = 1 | 2 | 3;
-
-/**
- * How far outside the range its auto-close triggers sit, as a multiple of the
- * range's own half-width.
- *
- * Proportional rather than fixed: a flat 10% buffer put the trigger for a 1%
- * range nine range-widths away, so a position could sit out of range indefinitely
- * without ever firing. At 1× the limits move with the preset — a 1% range closes
- * 1% beyond its bound, a 20% range 20% beyond.
- */
-const LIMIT_BUFFER_RATIO = 1;
-
-// ── State ──
-
-export interface LPState {
-  pool_address: string;
-  lp_provider: string;
-  lower_price: number;
-  upper_price: number;
-  lower_limit_price: number;
-  upper_limit_price: number;
-  side: LpSide;
-  base_amount: number;
-  quote_amount: number;
-  keep_position: boolean;
-  /** Meteora only: 0 Spot / 1 Curve / 2 Bid-Ask. Held as a string for SelectField. */
-  strategy_type: string;
-  /** Half-width of the auto-filled range, as a fraction of the current price. */
-  range_pct: number;
-  activePickField: string | null;
-  showAdvanced: boolean;
-  /**
-   * Whether the user has typed a pool or provider. A manual entry is the real
-   * answer for anyone who cares about fee tier or bin step, so it must survive
-   * every re-resolve of the auto-resolved pool.
-   */
-  poolTouched: boolean;
-}
-
-type LPAction =
-  | { type: "SET_FIELD"; field: string; value: unknown }
-  | { type: "SET_CONNECTOR"; value: string }
-  | { type: "SET_PAIR"; value: string }
-  | { type: "RESOLVED"; pool: DexPoolInfo }
-  | { type: "AUTO_RANGE"; price: number }
-  | { type: "SET_SIDE"; value: LpSide; price: number | null }
-  | { type: "SET_RANGE_PCT"; value: number; price: number | null };
-
-const DEFAULTS: LPState = {
-  pool_address: "",
-  lp_provider: "",
-  lower_price: 0,
-  upper_price: 0,
-  lower_limit_price: 0,
-  upper_limit_price: 0,
-  side: LP_SIDE_RANGE,
-  base_amount: 0,
-  quote_amount: 0,
-  keep_position: true,
-  strategy_type: "0",
-  range_pct: 0.05,
-  activePickField: null,
-  showAdvanced: false,
-  poolTouched: false,
-};
-
-const STORAGE_KEY = "condor_lp_defaults";
-
-// The pool and the range belong to a pair, not to the user's habits, so neither is
-// persisted — only the shape of position they tend to open.
-const PERSISTED_FIELDS: (keyof LPState)[] = [
-  "side",
-  "base_amount",
-  "quote_amount",
-  "keep_position",
-  "strategy_type",
-  "range_pct",
-];
-
-function loadSavedDefaults(): LPState {
-  try {
-    const raw = localStorage.getItem(STORAGE_KEY);
-    if (!raw) return DEFAULTS;
-    const saved = JSON.parse(raw);
-    const merged = { ...DEFAULTS };
-    for (const key of PERSISTED_FIELDS) {
-      if (key in saved && saved[key] !== undefined) {
-        (merged as Record<string, unknown>)[key] = saved[key];
-      }
-    }
-    return merged;
-  } catch {
-    return DEFAULTS;
-  }
-}
-
-function saveDefaults(state: LPState) {
-  const toSave: Record<string, unknown> = {};
-  for (const key of PERSISTED_FIELDS) toSave[key] = state[key];
-  localStorage.setItem(STORAGE_KEY, JSON.stringify(toSave));
-}
-
-/**
- * Range bounds and auto-close triggers for a side, anchored on the current price.
- *
- * A single-sided position has to start out of range for its conversion to happen
- * in the direction the tokens allow: quote-only (BUY) converts to base as the
- * price *falls* through a range below it, base-only (SELL) converts to quote as
- * the price *rises* through a range above it. Centering either one would leave
- * half the range unusable.
- */
-export function rangeForSide(side: LpSide, price: number, pct: number) {
-  let lower: number;
-  let upper: number;
-  if (side === LP_SIDE_BUY) {
-    lower = price * (1 - pct);
-    upper = price;
-  } else if (side === LP_SIDE_SELL) {
-    lower = price;
-    upper = price * (1 + pct);
-  } else {
-    lower = price * (1 - pct);
-    upper = price * (1 + pct);
-  }
-  const buffer = pct * LIMIT_BUFFER_RATIO;
-  return {
-    lower_price: lower,
-    upper_price: upper,
-    lower_limit_price: lower * (1 - buffer),
-    upper_limit_price: upper * (1 + buffer),
-  };
-}
-
-function lpReducer(state: LPState, action: LPAction): LPState {
-  switch (action.type) {
-    case "SET_FIELD": {
-      const touched =
-        action.field === "pool_address" || action.field === "lp_provider";
-      return {
-        ...state,
-        [action.field]: action.value,
-        ...(touched ? { poolTouched: true } : {}),
-      };
-    }
-    case "SET_CONNECTOR":
-    case "SET_PAIR":
-      // A pool address belongs to one pair on one chain. Carrying it across would
-      // submit a position in a pool that trades something else entirely.
-      return {
-        ...state,
-        pool_address: "",
-        lp_provider: "",
-        poolTouched: false,
-        lower_price: 0,
-        upper_price: 0,
-        lower_limit_price: 0,
-        upper_limit_price: 0,
-      };
-    case "RESOLVED": {
-      // Only a pool that can actually take a position is filled in. Handing over
-      // the address of a router pool would just build a payload the API rejects.
-      if (state.poolTouched || !action.pool.lp_supported) return state;
-      return {
-        ...state,
-        pool_address: action.pool.pool_address ?? "",
-        lp_provider: action.pool.lp_provider ?? "",
-      };
-    }
-    case "AUTO_RANGE":
-      return { ...state, ...rangeForSide(state.side, action.price, state.range_pct) };
-    case "SET_SIDE":
-      return {
-        ...state,
-        side: action.value,
-        ...(action.price && action.price > 0
-          ? rangeForSide(action.value, action.price, state.range_pct)
-          : {}),
-      };
-    case "SET_RANGE_PCT":
-      return {
-        ...state,
-        range_pct: action.value,
-        ...(action.price && action.price > 0
-          ? rangeForSide(state.side, action.price, action.value)
-          : {}),
-      };
-    default:
-      return state;
-  }
-}
-
-// ── Validation ──
-
-export function useLpValidation(state: LPState): ExecutorValidation {
-  return useMemo(() => {
-    const errors: string[] = [];
-    if (!state.pool_address) errors.push("Pool address required");
-    if (!state.lp_provider) errors.push("LP provider required (e.g. meteora/clmm)");
-    if (state.lower_price <= 0) errors.push("Lower price required");
-    if (state.upper_price <= 0) errors.push("Upper price required");
-    if (
-      state.lower_price > 0 &&
-      state.upper_price > 0 &&
-      state.upper_price <= state.lower_price
-    ) {
-      errors.push("Upper price must be above lower price");
-    }
-    if (state.base_amount <= 0 && state.quote_amount <= 0) {
-      errors.push("At least one amount required");
-    }
-    return { valid: errors.length === 0, errors };
-  }, [state]);
-}
-
-/**
- * Things the schema permits but that are rarely meant. Kept apart from validation
- * because none of them should block a create — a deliberately odd position is
- * still a position.
- */
-function rangeWarnings(state: LPState, price: number | null): string[] {
-  const warnings: string[] = [];
-  const bothAmounts = state.base_amount > 0 && state.quote_amount > 0;
-
-  if (state.side === LP_SIDE_RANGE && !bothAmounts) {
-    warnings.push("RANGE is double-sided; only one amount is set");
-  }
-  if (state.side !== LP_SIDE_RANGE && bothAmounts) {
-    warnings.push("Single-sided side with both amounts set — one will be unused");
-  }
-  if (price && price > 0) {
-    if (state.side === LP_SIDE_BUY && state.lower_price > price) {
-      warnings.push("BUY (quote-only) usually ranges below the current price");
-    }
-    if (state.side === LP_SIDE_SELL && state.upper_price < price) {
-      warnings.push("SELL (base-only) usually ranges above the current price");
-    }
-  }
-  if (state.upper_limit_price > 0 && state.upper_limit_price <= state.upper_price) {
-    warnings.push("Upper limit sits inside the range");
-  }
-  if (state.lower_limit_price > 0 && state.lower_limit_price >= state.lower_price) {
-    warnings.push("Lower limit sits inside the range");
-  }
-  return warnings;
-}
-
-// ── Chart pick slots ──
-// One slot per price: the two bounds and both auto-close triggers. The lower
-// limit rides `limit2`, the slot for a price the panel draws itself as an extra
-// line rather than one the chart owns.
-const PICK_SLOT: Record<string, PickSlot> = {
-  upper_price: "start",
-  lower_price: "end",
-  upper_limit_price: "limit",
-  lower_limit_price: "limit2",
-};
-
-const SLOT_FIELD: Record<PickSlot, keyof LPState> = {
-  start: "upper_price",
-  end: "lower_price",
-  limit: "upper_limit_price",
-  limit2: "lower_limit_price",
-};
-
-export function isMeteoraProvider(provider: string): boolean {
-  return provider.toLowerCase().startsWith("meteora/");
-}
-
-// ── Hook ──
-
-export function useLpConfig(
-  server: string | null,
-  connector: string,
-  pair: string,
-  enabled: boolean,
-) {
-  const [state, dispatch] = useReducer(lpReducer, undefined, loadSavedDefaults);
-  const validation = useLpValidation(state);
-
-  const { data: pool, isFetching: poolFetching } = useQuery({
-    queryKey: ["dex-pool", server, connector, pair],
-    queryFn: () => api.getDexPool(server!, connector, pair),
-    enabled: enabled && !!server && !!connector && !!pair,
-    staleTime: 60 * 1000,
-  });
-
-  useEffect(() => {
-    if (pool) dispatch({ type: "RESOLVED", pool });
-  }, [pool]);
-
-  const chartProps: ChartPriceMapping = useMemo(
-    () => ({
-      startPrice: state.upper_price,
-      endPrice: state.lower_price,
-      limitPrice: state.upper_limit_price,
-      // ChartPriceMapping.side is 1 | 2 and only selects the picker's color, so
-      // RANGE collapses onto the BUY color rather than growing the union.
-      side: state.side === LP_SIDE_SELL ? 2 : 1,
-      minSpread: 0,
-      activePickField: PICK_SLOT[state.activePickField ?? ""] ?? null,
-      extraLines:
-        state.lower_limit_price > 0
-          ? [
-              {
-                price: state.lower_limit_price,
-                label: "Lower limit",
-                // Amber while armed, matching how the chart marks its own lines.
-                color:
-                  state.activePickField === "lower_limit_price"
-                    ? "#fbbf24"
-                    : getThemeColors().red,
-                lineStyle: "dotted" as const,
-                lineWidth: 1,
-              },
-            ]
-          : undefined,
-    }),
-    [
-      state.upper_price,
-      state.lower_price,
-      state.upper_limit_price,
-      state.lower_limit_price,
-      state.side,
-      state.activePickField,
-    ],
-  );
-
-  const buildPayload = (connectorName: string, tradingPair: string) => {
-    const config: Record<string, unknown> = {
-      // The NETWORK (solana-mainnet-beta), not the DEX — the API rejects
-      // `meteora/clmm` here with "Invalid network format". The DEX is lp_provider.
-      connector_name: connectorName,
-      lp_provider: state.lp_provider,
-      trading_pair: tradingPair,
-      pool_address: state.pool_address,
-      lower_price: state.lower_price,
-      upper_price: state.upper_price,
-      side: state.side,
-      base_amount: state.base_amount,
-      quote_amount: state.quote_amount,
-      keep_position: state.keep_position,
-    };
-    // Both default to null (no trigger); 0 is not a way to say "unset".
-    if (state.upper_limit_price > 0) config.upper_limit_price = state.upper_limit_price;
-    if (state.lower_limit_price > 0) config.lower_limit_price = state.lower_limit_price;
-    // strategyType is Meteora's alone — any other provider rejects extra_params.
-    if (isMeteoraProvider(state.lp_provider)) {
-      config.extra_params = { strategyType: Number(state.strategy_type) };
-    }
-    return { executor_type: "lp_executor" as const, config };
-  };
-
-  const save = () => saveDefaults(state);
-
-  const handleChartPriceSet = (field: PickSlot, price: number) => {
-    dispatch({ type: "SET_FIELD", field: SLOT_FIELD[field], value: price });
-    dispatch({ type: "SET_FIELD", field: "activePickField", value: null });
-  };
-
-  return {
-    state,
-    dispatch,
-    validation,
-    chartProps,
-    buildPayload,
-    save,
-    handleChartPriceSet,
-    pool,
-    poolFetching,
-  };
-}
+import type { ExecutorValidation } from "./types";
+import type { DexPoolInfo } from "@/lib/api";
+import {
+  LP_SIDE_BUY,
+  LP_SIDE_RANGE,
+  LP_SIDE_SELL,
+  type LPAction,
+  type LPState,
+  type LpSide,
+  isMeteoraProvider,
+  rangeWarnings,
+} from "./lp-config";
 
 // ── Options ──
 
diff --git a/frontend/src/components/executor/PositionConfigPanel.tsx b/frontend/src/components/executor/PositionConfigPanel.tsx
index d46330c1..e151505f 100644
--- a/frontend/src/components/executor/PositionConfigPanel.tsx
+++ b/frontend/src/components/executor/PositionConfigPanel.tsx
@@ -11,9 +11,9 @@ import {
   SelectField,
   SideSelector,
   ValidationMessages,
-  ORDER_TYPE_OPTIONS,
   type FieldDispatch,
 } from "./fields";
+import { ORDER_TYPE_OPTIONS } from "./field-options";
 import type { ChartPriceMapping, ExecutorValidation, ExtraLine, PickSlot } from "./types";
 import { getThemeColors } from "@/lib/theme-colors";
 
diff --git a/frontend/src/components/executor/fields.tsx b/frontend/src/components/executor/fields.tsx
index 6869c91a..d4d959c0 100644
--- a/frontend/src/components/executor/fields.tsx
+++ b/frontend/src/components/executor/fields.tsx
@@ -9,6 +9,8 @@ import {
 
 // ── Generic dispatch type ──
 
+import { PERCENT_PRESETS, SIDE_OPTIONS } from "./field-options";
+
 export type FieldDispatch = (action: { type: "SET_FIELD"; field: string; value: unknown }) => void;
 
 // ── PriceField ──
@@ -106,7 +108,6 @@ export function PriceField({
 // ── PercentPresets ──
 
 /** Fractions of the available balance the presets offer. */
-export const PERCENT_PRESETS = [0.1, 0.25, 0.5, 1] as const;
 
 function formatAvailable(value: number): string {
   if (value === 0) return "0";
@@ -530,16 +531,7 @@ export function LeverageField({
 
 // ── Shared constants ──
 
-export const ORDER_TYPE_OPTIONS = [
-  { value: 1, label: "Market" },
-  { value: 2, label: "Limit" },
-  { value: 3, label: "Limit Maker" },
-];
 
-export const SIDE_OPTIONS = [
-  { value: 1, label: "LONG", color: "var(--color-green)" },
-  { value: 2, label: "SHORT", color: "var(--color-red)" },
-];
 
 export function SideSelector({ side, dispatch }: { side: 1 | 2; dispatch: FieldDispatch }) {
   return (
diff --git a/frontend/src/components/grid/GridConfigPanel.tsx b/frontend/src/components/grid/GridConfigPanel.tsx
index d4983897..8753edce 100644
--- a/frontend/src/components/grid/GridConfigPanel.tsx
+++ b/frontend/src/components/grid/GridConfigPanel.tsx
@@ -8,7 +8,8 @@ import {
   Sparkles,
 } from "lucide-react";
 
-import { LeverageField, SelectField, ToggleField, ORDER_TYPE_OPTIONS, type FieldDispatch } from "@/components/executor/fields";
+import { LeverageField, SelectField, ToggleField, type FieldDispatch } from "@/components/executor/fields";
+import { ORDER_TYPE_OPTIONS } from "@/components/executor/field-options";
 import type { GridState, GridAction } from "@/lib/gridExecutor";
 
 interface GridConfigPanelProps {
diff --git a/frontend/src/pages/CreateExecutor.tsx b/frontend/src/pages/CreateExecutor.tsx
index 7178d490..ee951355 100644
--- a/frontend/src/pages/CreateExecutor.tsx
+++ b/frontend/src/pages/CreateExecutor.tsx
@@ -29,7 +29,8 @@ import { GridConfigPanel, useGridValidation } from "@/components/grid/GridConfig
 import { PositionConfigPanel, usePositionConfig } from "@/components/executor/PositionConfigPanel";
 import { OrderConfigPanel, useOrderConfig } from "@/components/executor/OrderConfigPanel";
 import { DCAConfigPanel, useDCAConfig } from "@/components/executor/DCAConfigPanel";
-import { LPConfigPanel, useLpConfig } from "@/components/executor/LPConfigPanel";
+import { LPConfigPanel } from "@/components/executor/LPConfigPanel";
+import { useLpConfig } from "@/components/executor/lp-config";
 import { TradeBottomPane } from "@/components/trade/TradeBottomPane";
 import { useCandleStore } from "@/hooks/useCandleStore";
 import { usePairBalances } from "@/hooks/usePairBalances";
@@ -139,7 +140,21 @@ export function CreateExecutor() {
   const [rightPanel, setRightPanel] = useState<"config" | "depth" | "markets">("config");
   const [rightPanelWidth, setRightPanelWidth] = useState(288);
   const [bottomPaneHeight, setBottomPaneHeight] = useState(200);
-  const [selectedExecutorId, setSelectedExecutorId] = useState<string | null>(null);
+  // The selection belongs to the market it was made in, so it carries that
+  // market with it and simply stops matching when the market changes. Clearing
+  // it from an effect instead used to cost a second render pass on every
+  // connector/pair switch, and left one render where the chart still had a
+  // selected executor from the market it had already navigated away from.
+  const [selection, setSelection] = useState<{ market: string; id: string | null }>({
+    market: "",
+    id: null,
+  });
+  const selectionMarket = `${connector}:${pair}`;
+  const selectedExecutorId = selection.market === selectionMarket ? selection.id : null;
+  const setSelectedExecutorId = useCallback(
+    (id: string | null) => setSelection({ market: selectionMarket, id }),
+    [selectionMarket],
+  );
 
   const { onMouseDown: startHDrag } = useResizeDrag({
     axis: "x",
@@ -225,12 +240,12 @@ export function CreateExecutor() {
     gridDispatch({ type: "SET_FIELD", field: "lookbackSeconds", value: newLookback });
   }, [server]);
 
-  // Persist last-used connector/pair to localStorage & clear executor selection
+  // Persist last-used connector/pair to localStorage. The executor selection is
+  // not cleared here -- it expires on its own, see `selection` above.
   useEffect(() => {
     try {
       localStorage.setItem(LAST_MARKET_KEY, JSON.stringify({ connector, pair }));
     } catch { /* ok */ }
-    setSelectedExecutorId(null);
   }, [connector, pair]);
 
   // A /trade URL naming a gateway network is a link to the wrong page now: its
@@ -356,9 +371,22 @@ export function CreateExecutor() {
     }
   }, [executorType, gridState, positionConfig.chartProps, orderConfig.chartProps, dcaConfig.chartProps, lpConfig.chartProps]);
 
-  // Chart price set handler
-  const handlePriceSet = useMemo(
-    () => (field: PickSlot, price: number) => {
+  // Chart price set handler.
+  //
+  // Each per-type panel hands back a fresh config object every render, so naming
+  // them as deps would rebuild this callback on every render and defeat the
+  // stable identity the chart memoizes on. Pinning the deps to `[executorType]`
+  // bought that stability with a stale closure -- the callback kept calling
+  // whichever `handleChartPriceSet` existed when the type last changed, not the
+  // current one. A latest-value ref gives the stability without the staleness.
+  const priceSetTargets = useRef({ positionConfig, orderConfig, dcaConfig, lpConfig });
+  useEffect(() => {
+    priceSetTargets.current = { positionConfig, orderConfig, dcaConfig, lpConfig };
+  });
+
+  const handlePriceSet = useCallback(
+    (field: PickSlot, price: number) => {
+      const targets = priceSetTargets.current;
       switch (executorType) {
         case "grid":
           // The grid panel arms only start/end/limit; `limit2` belongs to the LP
@@ -368,20 +396,20 @@ export function CreateExecutor() {
           gridDispatch({ type: "SET_FIELD", field: "activePickField", value: null });
           break;
         case "position":
-          positionConfig.handleChartPriceSet(field, price);
+          targets.positionConfig.handleChartPriceSet(field, price);
           break;
         case "order":
-          orderConfig.handleChartPriceSet(field, price);
+          targets.orderConfig.handleChartPriceSet(field, price);
           break;
         case "dca":
-          dcaConfig.handleChartPriceSet(field, price);
+          targets.dcaConfig.handleChartPriceSet(field, price);
           break;
         case "lp":
-          lpConfig.handleChartPriceSet(field, price);
+          targets.lpConfig.handleChartPriceSet(field, price);
           break;
       }
     },
-    [executorType], // eslint-disable-line react-hooks/exhaustive-deps
+    [executorType],
   );
 
   // Create mutation
diff --git a/frontend/src/pages/Dex.tsx b/frontend/src/pages/Dex.tsx
index 67acf517..2b4fdd49 100644
--- a/frontend/src/pages/Dex.tsx
+++ b/frontend/src/pages/Dex.tsx
@@ -6,10 +6,8 @@ import { useNavigate } from "react-router-dom";
 import { NoServerCard } from "@/components/NoServerCard";
 import { LpPositions } from "@/components/dex/LpPositions";
 import { PoolBrowser } from "@/components/dex/PoolBrowser";
-import {
-  type PoolSource,
-  PoolSourceTabs,
-} from "@/components/dex/PoolSourceTabs";
+import { PoolSourceTabs } from "@/components/dex/PoolSourceTabs";
+import type { PoolSource } from "@/components/dex/pool-source";
 import { useServer } from "@/hooks/useServer";
 import { api, type PoolSummary } from "@/lib/api";
 import { useDexFavorites } from "@/lib/dexFavorites";
diff --git a/frontend/src/pages/DexPool.tsx b/frontend/src/pages/DexPool.tsx
index 04a509da..ee1c716a 100644
--- a/frontend/src/pages/DexPool.tsx
+++ b/frontend/src/pages/DexPool.tsx
@@ -7,10 +7,8 @@ import { NoServerCard } from "@/components/NoServerCard";
 import { LiquidityDepthColumn } from "@/components/dex/LiquidityDepthColumn";
 import { LpPositionBar } from "@/components/dex/LpPositionBar";
 import { PoolStats } from "@/components/dex/PoolStats";
-import {
-  LPConfigPanel,
-  useLpConfig,
-} from "@/components/executor/LPConfigPanel";
+import { LPConfigPanel } from "@/components/executor/LPConfigPanel";
+import { useLpConfig } from "@/components/executor/lp-config";
 import {
   OrderConfigPanel,
   useOrderConfig,

From 84cb72988498489715eb584574ea8d7b5035504f Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Tue, 18 Aug 2026 00:04:19 +0300
Subject: [PATCH 111/116] (feat) add linting

---
 frontend/eslint-baseline.json      |  44 +++++++++++++
 frontend/scripts/lint-baseline.mjs | 101 +++++++++++++++++++++++++++++
 2 files changed, 145 insertions(+)
 create mode 100644 frontend/eslint-baseline.json
 create mode 100644 frontend/scripts/lint-baseline.mjs

diff --git a/frontend/eslint-baseline.json b/frontend/eslint-baseline.json
new file mode 100644
index 00000000..ef21e191
--- /dev/null
+++ b/frontend/eslint-baseline.json
@@ -0,0 +1,44 @@
+{
+  "src/components/agent/AgentOverviewTab.tsx | react-hooks/preserve-manual-memoization": 1,
+  "src/components/agent/AgentPnlChart.tsx | react-refresh/only-export-components": 2,
+  "src/components/agent/AgentSessionContent.tsx | react-hooks/preserve-manual-memoization": 1,
+  "src/components/agent/SessionReviewer.tsx | react-hooks/preserve-manual-memoization": 2,
+  "src/components/bots/AggregatedPnlChart.tsx | react-hooks/set-state-in-render": 1,
+  "src/components/bots/ControllerBrowser.tsx | react-hooks/set-state-in-effect": 1,
+  "src/components/bots/ControllerPnlChart.tsx | react-hooks/purity": 1,
+  "src/components/bots/DeployBotDialog.tsx | react-refresh/only-export-components": 3,
+  "src/components/chat/ChatInput.tsx | react-hooks/immutability": 1,
+  "src/components/chat/ChatThread.tsx | react-refresh/only-export-components": 1,
+  "src/components/chat/DockRoutines.tsx | react-refresh/only-export-components": 1,
+  "src/components/editor/EditorDialogs.tsx | react-hooks/set-state-in-render": 2,
+  "src/components/executor/DCAConfigPanel.tsx | @typescript-eslint/no-unused-vars": 1,
+  "src/components/executor/DCAConfigPanel.tsx | react-refresh/only-export-components": 2,
+  "src/components/executor/ExecutorTable.tsx | no-empty": 1,
+  "src/components/executor/fields.tsx | react-hooks/set-state-in-effect": 3,
+  "src/components/executor/OrderConfigPanel.tsx | react-refresh/only-export-components": 2,
+  "src/components/executor/PositionConfigPanel.tsx | react-refresh/only-export-components": 2,
+  "src/components/grid/GridConfigPanel.tsx | react-hooks/set-state-in-effect": 2,
+  "src/components/grid/GridConfigPanel.tsx | react-refresh/only-export-components": 1,
+  "src/components/market/MarketsPanel.tsx | react-hooks/purity": 1,
+  "src/components/market/OrderBook.tsx | react-hooks/immutability": 1,
+  "src/components/market/PairSelector.tsx | react-hooks/set-state-in-effect": 1,
+  "src/components/market/PairSelector.tsx | react-refresh/only-export-components": 1,
+  "src/components/market/PriceTicker.tsx | react-hooks/refs": 3,
+  "src/components/market/RecentTrades.tsx | react-hooks/set-state-in-effect": 1,
+  "src/components/routines/ReportBrowser.tsx | react-hooks/set-state-in-effect": 4,
+  "src/components/routines/RoutineConfigForm.tsx | react-hooks/set-state-in-effect": 1,
+  "src/components/routines/RoutineHooksPanel.tsx | react-hooks/set-state-in-effect": 1,
+  "src/components/settings/GatewaySettings.tsx | react-hooks/set-state-in-effect": 1,
+  "src/components/settings/VoiceSettings.tsx | react-hooks/set-state-in-effect": 1,
+  "src/hooks/useBacktest.ts | react-hooks/set-state-in-effect": 1,
+  "src/hooks/useCandleStore.ts | react-hooks/set-state-in-effect": 1,
+  "src/hooks/useChat.tsx | react-refresh/only-export-components": 2,
+  "src/pages/BotDetail.tsx | react-hooks/refs": 2,
+  "src/pages/Bots.tsx | react-hooks/refs": 12,
+  "src/pages/CreateExecutor.tsx | react-hooks/set-state-in-effect": 1,
+  "src/pages/Executors.tsx | react-hooks/purity": 1,
+  "src/pages/Login.tsx | react-hooks/set-state-in-effect": 1,
+  "src/pages/StrategyDetail.tsx | react-hooks/preserve-manual-memoization": 1,
+  "src/pages/StrategyDetail.tsx | react-hooks/set-state-in-effect": 1,
+  "src/pages/tabs/EditorTab.tsx | react-hooks/refs": 6
+}
diff --git a/frontend/scripts/lint-baseline.mjs b/frontend/scripts/lint-baseline.mjs
new file mode 100644
index 00000000..b76655fe
--- /dev/null
+++ b/frontend/scripts/lint-baseline.mjs
@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+/**
+ * Lint gate that fails on *new* errors rather than on the whole backlog.
+ *
+ * `eslint .` reports 76 errors that predate the CI gate — mostly React Compiler
+ * findings (stale refs, cascading setState) that are real but each need their
+ * own fix. Blocking every PR on all of them would have meant either a
+ * frontend-wide refactor bolted onto whatever branch got there first, or
+ * switching the rules off and losing the findings. So the known set is recorded
+ * in eslint-baseline.json and only what exceeds it fails.
+ *
+ * Entries are keyed by file + rule, not by line: line numbers churn on every
+ * edit above them, which would make the baseline fail for reasons unrelated to
+ * lint. Counts are compared, so a second violation of an already-known rule in
+ * an already-known file is still caught.
+ *
+ * The baseline only ever ratchets down. A fixed error is reported as drift and
+ * fails the run too, so the file cannot quietly keep granting an exception that
+ * is no longer used — rerun with --update to bank the fix.
+ *
+ *   node scripts/lint-baseline.mjs            check (CI)
+ *   node scripts/lint-baseline.mjs --update   rewrite the baseline
+ */
+import { execFileSync } from "node:child_process";
+import { readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+const baselinePath = join(root, "eslint-baseline.json");
+const update = process.argv.includes("--update");
+
+function currentCounts() {
+  let stdout;
+  try {
+    // eslint exits non-zero whenever it reports anything, which is the normal
+    // case here — the report on stdout is what matters, not the status.
+    stdout = execFileSync("npx", ["eslint", ".", "-f", "json"], {
+      cwd: root,
+      encoding: "utf8",
+      maxBuffer: 64 * 1024 * 1024,
+    });
+  } catch (err) {
+    if (!err.stdout) throw err;
+    stdout = err.stdout;
+  }
+
+  const counts = {};
+  for (const file of JSON.parse(stdout)) {
+    const path = file.filePath.slice(root.length + 1);
+    for (const msg of file.messages) {
+      if (msg.severity !== 2) continue; // warnings are not gated
+      const key = `${path} | ${msg.ruleId ?? "(no-rule)"}`;
+      counts[key] = (counts[key] ?? 0) + 1;
+    }
+  }
+  return counts;
+}
+
+const counts = currentCounts();
+const total = Object.values(counts).reduce((a, b) => a + b, 0);
+
+if (update) {
+  const sorted = Object.fromEntries(Object.entries(counts).sort(([a], [b]) => a.localeCompare(b)));
+  writeFileSync(baselinePath, `${JSON.stringify(sorted, null, 2)}\n`);
+  console.log(`Baseline updated: ${Object.keys(sorted).length} entries, ${total} errors.`);
+  process.exit(0);
+}
+
+let baseline;
+try {
+  baseline = JSON.parse(readFileSync(baselinePath, "utf8"));
+} catch {
+  console.error(`Missing or unreadable ${baselinePath}. Run: npm run lint:baseline -- --update`);
+  process.exit(1);
+}
+
+const regressions = [];
+const fixed = [];
+for (const key of new Set([...Object.keys(counts), ...Object.keys(baseline)])) {
+  const now = counts[key] ?? 0;
+  const was = baseline[key] ?? 0;
+  if (now > was) regressions.push(`  ${key}  (${was} allowed, ${now} found)`);
+  else if (now < was) fixed.push(`  ${key}  (${was} allowed, ${now} found)`);
+}
+
+if (regressions.length) {
+  console.error(`\nNew lint errors not in the baseline:\n${regressions.join("\n")}`);
+  console.error("\nFix them, or if they are genuinely acceptable, run:");
+  console.error("  npm run lint:baseline -- --update\n");
+  process.exit(1);
+}
+
+if (fixed.length) {
+  console.error(`\nBaseline is stale — these are already fixed:\n${fixed.join("\n")}`);
+  console.error("\nBank the improvement so it cannot regress:");
+  console.error("  npm run lint:baseline -- --update\n");
+  process.exit(1);
+}
+
+console.log(`No new lint errors. ${total} baselined errors remain to pay down.`);

From db5c44d8be112e4bb64a755ce117cc719d551050 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Tue, 18 Aug 2026 00:04:23 +0300
Subject: [PATCH 112/116] (feat) add components

---
 frontend/src/components/dex/pool-source.ts    |  38 ++
 .../src/components/executor/field-options.ts  |  13 +
 frontend/src/components/executor/lp-config.ts | 388 ++++++++++++++++++
 3 files changed, 439 insertions(+)
 create mode 100644 frontend/src/components/dex/pool-source.ts
 create mode 100644 frontend/src/components/executor/field-options.ts
 create mode 100644 frontend/src/components/executor/lp-config.ts

diff --git a/frontend/src/components/dex/pool-source.ts b/frontend/src/components/dex/pool-source.ts
new file mode 100644
index 00000000..cd53f69c
--- /dev/null
+++ b/frontend/src/components/dex/pool-source.ts
@@ -0,0 +1,38 @@
+/**
+ * Which pool listing to browse. The upstreams take genuinely different arguments
+ * — GeckoTerminal ranks a *chain*'s pools and searches by address, Gateway CLMM
+ * lists one *connector*'s pools and searches free text, favourites are a local
+ * list of addresses — so they are separate tabs rather than one filter row.
+ */
+export type PoolSource =
+  | { kind: "gecko"; view: "trending" | "top" | "new" | "token" }
+  | { kind: "gateway"; connector: string }
+  | { kind: "favorites" };
+
+export const GECKO_TABS = [
+  { view: "trending", label: "Trending" },
+  { view: "top", label: "Top" },
+  { view: "new", label: "New" },
+  { view: "token", label: "Search" },
+] as const;
+
+/**
+ * The CLMM connectors Gateway can list pools for (and open positions in).
+ *
+ * Both are Solana venues, so these tabs are hidden on any other chain: a Meteora
+ * tab on Base lists nothing and offers no position to open, which is worse than
+ * not offering it. GeckoTerminal browsing works on every chain either way.
+ */
+export const GATEWAY_TABS = [
+  { connector: "meteora", label: "Meteora" },
+  { connector: "orca", label: "Orca" },
+] as const;
+
+export const GATEWAY_TAB_CHAIN = "solana";
+
+export function sameSource(a: PoolSource, b: PoolSource): boolean {
+  if (a.kind === "gecko" && b.kind === "gecko") return a.view === b.view;
+  if (a.kind === "gateway" && b.kind === "gateway")
+    return a.connector === b.connector;
+  return a.kind === "favorites" && b.kind === "favorites";
+}
diff --git a/frontend/src/components/executor/field-options.ts b/frontend/src/components/executor/field-options.ts
new file mode 100644
index 00000000..09acba10
--- /dev/null
+++ b/frontend/src/components/executor/field-options.ts
@@ -0,0 +1,13 @@
+export const PERCENT_PRESETS = [0.1, 0.25, 0.5, 1] as const;
+
+export const ORDER_TYPE_OPTIONS = [
+  { value: 1, label: "Market" },
+  { value: 2, label: "Limit" },
+  { value: 3, label: "Limit Maker" },
+];
+
+export const SIDE_OPTIONS = [
+  { value: 1, label: "LONG", color: "var(--color-green)" },
+  { value: 2, label: "SHORT", color: "var(--color-red)" },
+];
+
diff --git a/frontend/src/components/executor/lp-config.ts b/frontend/src/components/executor/lp-config.ts
new file mode 100644
index 00000000..5b966af6
--- /dev/null
+++ b/frontend/src/components/executor/lp-config.ts
@@ -0,0 +1,388 @@
+import { useQuery } from "@tanstack/react-query";
+import { useEffect, useMemo, useReducer } from "react";
+
+import type { ChartPriceMapping, ExecutorValidation, PickSlot } from "./types";
+import { api, type DexPoolInfo } from "@/lib/api";
+import { getThemeColors } from "@/lib/theme-colors";
+
+// ── Sides ──
+// `side` is a TradeType enum, not a direction: it says which token(s) you are
+// putting in, which in turn dictates where the range sits relative to the price.
+
+export const LP_SIDE_BUY = 1; // quote-only, range below the price
+export const LP_SIDE_SELL = 2; // base-only, range above the price
+export const LP_SIDE_RANGE = 3; // both tokens, range centered
+
+export type LpSide = 1 | 2 | 3;
+
+/**
+ * How far outside the range its auto-close triggers sit, as a multiple of the
+ * range's own half-width.
+ *
+ * Proportional rather than fixed: a flat 10% buffer put the trigger for a 1%
+ * range nine range-widths away, so a position could sit out of range indefinitely
+ * without ever firing. At 1× the limits move with the preset — a 1% range closes
+ * 1% beyond its bound, a 20% range 20% beyond.
+ */
+const LIMIT_BUFFER_RATIO = 1;
+
+// ── State ──
+
+export interface LPState {
+  pool_address: string;
+  lp_provider: string;
+  lower_price: number;
+  upper_price: number;
+  lower_limit_price: number;
+  upper_limit_price: number;
+  side: LpSide;
+  base_amount: number;
+  quote_amount: number;
+  keep_position: boolean;
+  /** Meteora only: 0 Spot / 1 Curve / 2 Bid-Ask. Held as a string for SelectField. */
+  strategy_type: string;
+  /** Half-width of the auto-filled range, as a fraction of the current price. */
+  range_pct: number;
+  activePickField: string | null;
+  showAdvanced: boolean;
+  /**
+   * Whether the user has typed a pool or provider. A manual entry is the real
+   * answer for anyone who cares about fee tier or bin step, so it must survive
+   * every re-resolve of the auto-resolved pool.
+   */
+  poolTouched: boolean;
+}
+
+export type LPAction =
+  | { type: "SET_FIELD"; field: string; value: unknown }
+  | { type: "SET_CONNECTOR"; value: string }
+  | { type: "SET_PAIR"; value: string }
+  | { type: "RESOLVED"; pool: DexPoolInfo }
+  | { type: "AUTO_RANGE"; price: number }
+  | { type: "SET_SIDE"; value: LpSide; price: number | null }
+  | { type: "SET_RANGE_PCT"; value: number; price: number | null };
+
+const DEFAULTS: LPState = {
+  pool_address: "",
+  lp_provider: "",
+  lower_price: 0,
+  upper_price: 0,
+  lower_limit_price: 0,
+  upper_limit_price: 0,
+  side: LP_SIDE_RANGE,
+  base_amount: 0,
+  quote_amount: 0,
+  keep_position: true,
+  strategy_type: "0",
+  range_pct: 0.05,
+  activePickField: null,
+  showAdvanced: false,
+  poolTouched: false,
+};
+
+const STORAGE_KEY = "condor_lp_defaults";
+
+// The pool and the range belong to a pair, not to the user's habits, so neither is
+// persisted — only the shape of position they tend to open.
+const PERSISTED_FIELDS: (keyof LPState)[] = [
+  "side",
+  "base_amount",
+  "quote_amount",
+  "keep_position",
+  "strategy_type",
+  "range_pct",
+];
+
+function loadSavedDefaults(): LPState {
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY);
+    if (!raw) return DEFAULTS;
+    const saved = JSON.parse(raw);
+    const merged = { ...DEFAULTS };
+    for (const key of PERSISTED_FIELDS) {
+      if (key in saved && saved[key] !== undefined) {
+        (merged as Record<string, unknown>)[key] = saved[key];
+      }
+    }
+    return merged;
+  } catch {
+    return DEFAULTS;
+  }
+}
+
+function saveDefaults(state: LPState) {
+  const toSave: Record<string, unknown> = {};
+  for (const key of PERSISTED_FIELDS) toSave[key] = state[key];
+  localStorage.setItem(STORAGE_KEY, JSON.stringify(toSave));
+}
+
+/**
+ * Range bounds and auto-close triggers for a side, anchored on the current price.
+ *
+ * A single-sided position has to start out of range for its conversion to happen
+ * in the direction the tokens allow: quote-only (BUY) converts to base as the
+ * price *falls* through a range below it, base-only (SELL) converts to quote as
+ * the price *rises* through a range above it. Centering either one would leave
+ * half the range unusable.
+ */
+export function rangeForSide(side: LpSide, price: number, pct: number) {
+  let lower: number;
+  let upper: number;
+  if (side === LP_SIDE_BUY) {
+    lower = price * (1 - pct);
+    upper = price;
+  } else if (side === LP_SIDE_SELL) {
+    lower = price;
+    upper = price * (1 + pct);
+  } else {
+    lower = price * (1 - pct);
+    upper = price * (1 + pct);
+  }
+  const buffer = pct * LIMIT_BUFFER_RATIO;
+  return {
+    lower_price: lower,
+    upper_price: upper,
+    lower_limit_price: lower * (1 - buffer),
+    upper_limit_price: upper * (1 + buffer),
+  };
+}
+
+function lpReducer(state: LPState, action: LPAction): LPState {
+  switch (action.type) {
+    case "SET_FIELD": {
+      const touched =
+        action.field === "pool_address" || action.field === "lp_provider";
+      return {
+        ...state,
+        [action.field]: action.value,
+        ...(touched ? { poolTouched: true } : {}),
+      };
+    }
+    case "SET_CONNECTOR":
+    case "SET_PAIR":
+      // A pool address belongs to one pair on one chain. Carrying it across would
+      // submit a position in a pool that trades something else entirely.
+      return {
+        ...state,
+        pool_address: "",
+        lp_provider: "",
+        poolTouched: false,
+        lower_price: 0,
+        upper_price: 0,
+        lower_limit_price: 0,
+        upper_limit_price: 0,
+      };
+    case "RESOLVED": {
+      // Only a pool that can actually take a position is filled in. Handing over
+      // the address of a router pool would just build a payload the API rejects.
+      if (state.poolTouched || !action.pool.lp_supported) return state;
+      return {
+        ...state,
+        pool_address: action.pool.pool_address ?? "",
+        lp_provider: action.pool.lp_provider ?? "",
+      };
+    }
+    case "AUTO_RANGE":
+      return { ...state, ...rangeForSide(state.side, action.price, state.range_pct) };
+    case "SET_SIDE":
+      return {
+        ...state,
+        side: action.value,
+        ...(action.price && action.price > 0
+          ? rangeForSide(action.value, action.price, state.range_pct)
+          : {}),
+      };
+    case "SET_RANGE_PCT":
+      return {
+        ...state,
+        range_pct: action.value,
+        ...(action.price && action.price > 0
+          ? rangeForSide(state.side, action.price, action.value)
+          : {}),
+      };
+    default:
+      return state;
+  }
+}
+
+// ── Validation ──
+
+export function useLpValidation(state: LPState): ExecutorValidation {
+  return useMemo(() => {
+    const errors: string[] = [];
+    if (!state.pool_address) errors.push("Pool address required");
+    if (!state.lp_provider) errors.push("LP provider required (e.g. meteora/clmm)");
+    if (state.lower_price <= 0) errors.push("Lower price required");
+    if (state.upper_price <= 0) errors.push("Upper price required");
+    if (
+      state.lower_price > 0 &&
+      state.upper_price > 0 &&
+      state.upper_price <= state.lower_price
+    ) {
+      errors.push("Upper price must be above lower price");
+    }
+    if (state.base_amount <= 0 && state.quote_amount <= 0) {
+      errors.push("At least one amount required");
+    }
+    return { valid: errors.length === 0, errors };
+  }, [state]);
+}
+
+/**
+ * Things the schema permits but that are rarely meant. Kept apart from validation
+ * because none of them should block a create — a deliberately odd position is
+ * still a position.
+ */
+export function rangeWarnings(state: LPState, price: number | null): string[] {
+  const warnings: string[] = [];
+  const bothAmounts = state.base_amount > 0 && state.quote_amount > 0;
+
+  if (state.side === LP_SIDE_RANGE && !bothAmounts) {
+    warnings.push("RANGE is double-sided; only one amount is set");
+  }
+  if (state.side !== LP_SIDE_RANGE && bothAmounts) {
+    warnings.push("Single-sided side with both amounts set — one will be unused");
+  }
+  if (price && price > 0) {
+    if (state.side === LP_SIDE_BUY && state.lower_price > price) {
+      warnings.push("BUY (quote-only) usually ranges below the current price");
+    }
+    if (state.side === LP_SIDE_SELL && state.upper_price < price) {
+      warnings.push("SELL (base-only) usually ranges above the current price");
+    }
+  }
+  if (state.upper_limit_price > 0 && state.upper_limit_price <= state.upper_price) {
+    warnings.push("Upper limit sits inside the range");
+  }
+  if (state.lower_limit_price > 0 && state.lower_limit_price >= state.lower_price) {
+    warnings.push("Lower limit sits inside the range");
+  }
+  return warnings;
+}
+
+// ── Chart pick slots ──
+// One slot per price: the two bounds and both auto-close triggers. The lower
+// limit rides `limit2`, the slot for a price the panel draws itself as an extra
+// line rather than one the chart owns.
+const PICK_SLOT: Record<string, PickSlot> = {
+  upper_price: "start",
+  lower_price: "end",
+  upper_limit_price: "limit",
+  lower_limit_price: "limit2",
+};
+
+const SLOT_FIELD: Record<PickSlot, keyof LPState> = {
+  start: "upper_price",
+  end: "lower_price",
+  limit: "upper_limit_price",
+  limit2: "lower_limit_price",
+};
+
+export function isMeteoraProvider(provider: string): boolean {
+  return provider.toLowerCase().startsWith("meteora/");
+}
+
+// ── Hook ──
+
+export function useLpConfig(
+  server: string | null,
+  connector: string,
+  pair: string,
+  enabled: boolean,
+) {
+  const [state, dispatch] = useReducer(lpReducer, undefined, loadSavedDefaults);
+  const validation = useLpValidation(state);
+
+  const { data: pool, isFetching: poolFetching } = useQuery({
+    queryKey: ["dex-pool", server, connector, pair],
+    queryFn: () => api.getDexPool(server!, connector, pair),
+    enabled: enabled && !!server && !!connector && !!pair,
+    staleTime: 60 * 1000,
+  });
+
+  useEffect(() => {
+    if (pool) dispatch({ type: "RESOLVED", pool });
+  }, [pool]);
+
+  const chartProps: ChartPriceMapping = useMemo(
+    () => ({
+      startPrice: state.upper_price,
+      endPrice: state.lower_price,
+      limitPrice: state.upper_limit_price,
+      // ChartPriceMapping.side is 1 | 2 and only selects the picker's color, so
+      // RANGE collapses onto the BUY color rather than growing the union.
+      side: state.side === LP_SIDE_SELL ? 2 : 1,
+      minSpread: 0,
+      activePickField: PICK_SLOT[state.activePickField ?? ""] ?? null,
+      extraLines:
+        state.lower_limit_price > 0
+          ? [
+              {
+                price: state.lower_limit_price,
+                label: "Lower limit",
+                // Amber while armed, matching how the chart marks its own lines.
+                color:
+                  state.activePickField === "lower_limit_price"
+                    ? "#fbbf24"
+                    : getThemeColors().red,
+                lineStyle: "dotted" as const,
+                lineWidth: 1,
+              },
+            ]
+          : undefined,
+    }),
+    [
+      state.upper_price,
+      state.lower_price,
+      state.upper_limit_price,
+      state.lower_limit_price,
+      state.side,
+      state.activePickField,
+    ],
+  );
+
+  const buildPayload = (connectorName: string, tradingPair: string) => {
+    const config: Record<string, unknown> = {
+      // The NETWORK (solana-mainnet-beta), not the DEX — the API rejects
+      // `meteora/clmm` here with "Invalid network format". The DEX is lp_provider.
+      connector_name: connectorName,
+      lp_provider: state.lp_provider,
+      trading_pair: tradingPair,
+      pool_address: state.pool_address,
+      lower_price: state.lower_price,
+      upper_price: state.upper_price,
+      side: state.side,
+      base_amount: state.base_amount,
+      quote_amount: state.quote_amount,
+      keep_position: state.keep_position,
+    };
+    // Both default to null (no trigger); 0 is not a way to say "unset".
+    if (state.upper_limit_price > 0) config.upper_limit_price = state.upper_limit_price;
+    if (state.lower_limit_price > 0) config.lower_limit_price = state.lower_limit_price;
+    // strategyType is Meteora's alone — any other provider rejects extra_params.
+    if (isMeteoraProvider(state.lp_provider)) {
+      config.extra_params = { strategyType: Number(state.strategy_type) };
+    }
+    return { executor_type: "lp_executor" as const, config };
+  };
+
+  const save = () => saveDefaults(state);
+
+  const handleChartPriceSet = (field: PickSlot, price: number) => {
+    dispatch({ type: "SET_FIELD", field: SLOT_FIELD[field], value: price });
+    dispatch({ type: "SET_FIELD", field: "activePickField", value: null });
+  };
+
+  return {
+    state,
+    dispatch,
+    validation,
+    chartProps,
+    buildPayload,
+    save,
+    handleChartPriceSet,
+    pool,
+    poolFetching,
+  };
+}
+

From 4a75bad3df57ac4b4ae154d9f5557a4f8d886811 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Tue, 18 Aug 2026 18:17:03 +0300
Subject: [PATCH 113/116] (feat) fix order placement

---
 condor/web/routes/dex.py                    | 91 ++++++++++++++++++++-
 frontend/src/components/dex/LpPositions.tsx |  1 +
 frontend/src/lib/api.ts                     | 64 +++++++++++++--
 frontend/src/pages/Dex.tsx                  | 43 +++++++++-
 frontend/src/pages/DexPool.tsx              | 46 +++++++++--
 5 files changed, 223 insertions(+), 22 deletions(-)

diff --git a/condor/web/routes/dex.py b/condor/web/routes/dex.py
index 41dfc9c4..d44ad7b4 100644
--- a/condor/web/routes/dex.py
+++ b/condor/web/routes/dex.py
@@ -164,6 +164,7 @@ async def list_pools(
     if view == "token" and not _ADDRESS_RE.match(token):
         raise HTTPException(status_code=400, detail="Invalid token address")
 
+    before = _throttle_counter()
     result = await list_gecko_pools_page(
         network,
         view=view,
@@ -177,6 +178,9 @@ async def list_pools(
         "source": source,
         "page": page,
         "has_more": result["has_more"],
+        # Reported on the same response as the rows so the browser can say why a
+        # page came back short, without a second round-trip to find out.
+        "upstream": _upstream_state(_throttle_counter() > before),
     }
 
 
@@ -252,6 +256,66 @@ async def list_chains(
     return {"chains": chains}
 
 
+def _throttle_counter() -> int:
+    """Every refusal this process has made, as one monotonic number.
+
+    Both refusals count: a 429 from gecko and a request this process declined to
+    send because the shared budget was already spent. The second one leaves no
+    trace in ``rate_limited`` — it raises without opening the breaker — so a
+    counter is the only way a caller can ask "was *my* fetch throttled?".
+    """
+    from condor.pool_data import gecko_health
+
+    health = gecko_health()
+    return int(health.get("throttled_calls") or 0) + int(health.get("count_429") or 0)
+
+
+def _upstream_state(throttled_request: bool = False) -> dict:
+    """What GeckoTerminal's shared budget looks like right now.
+
+    Every DEX view — the pool browser, a pool's stats, its chart — reads the same
+    per-IP budget, and every failure downstream of it degrades to an empty list.
+    So "no pools on this chain" and "throttled, ask again in a moment" arrive at
+    the browser looking identical unless the state is reported alongside the rows.
+
+    ``throttled_request`` is the stronger signal of the two and belongs to the
+    call being answered: the budget can be spent without the breaker being open,
+    in which case ``rate_limited`` is False while the rows are still missing.
+    """
+    from condor.pool_data import gecko_health
+
+    health = gecko_health()
+    last_429 = health.get("last_429_age")
+    return {
+        "rate_limited": bool(health.get("rate_limited")),
+        "throttled_request": bool(throttled_request),
+        "retry_in": round(float(health.get("cooldown_remaining") or 0.0), 1),
+        "requests_last_minute": int(health.get("requests_last_minute") or 0),
+        "budget": int(health.get("budget") or 0),
+        "throttled_calls": int(health.get("throttled_calls") or 0),
+        "count_429": int(health.get("count_429") or 0),
+        "seconds_since_429": (
+            round(float(last_429), 1) if last_429 is not None else None
+        ),
+    }
+
+
+@router.get("/servers/{name}/dex/upstream")
+async def get_upstream(
+    name: str,
+    user: WebUser = Depends(require_server_access),
+):
+    """Whether GeckoTerminal is currently throttling Condor.
+
+    Reads process-local counters only — no outbound request — so the browser can
+    poll it while a banner counts a cooldown down without spending the very
+    budget it is waiting on. Declared above ``/dex/pools/{pool_address}`` for the
+    same reason ``pools-by-address`` is: a path segment would be read as an
+    address.
+    """
+    return _upstream_state()
+
+
 @router.get("/servers/{name}/dex/pools-by-address")
 async def list_pools_by_address(
     name: str,
@@ -274,8 +338,10 @@ async def list_pools_by_address(
 
     wanted = [a.strip() for a in (addresses or "").split(",") if a.strip()][:30]
     if not wanted:
-        return {"pools": []}
-    return {"pools": await fetch_pools_by_addresses(network, wanted)}
+        return {"pools": [], "upstream": _upstream_state()}
+    before = _throttle_counter()
+    pools = await fetch_pools_by_addresses(network, wanted)
+    return {"pools": pools, "upstream": _upstream_state(_throttle_counter() > before)}
 
 
 @router.get("/servers/{name}/dex/pools/{pool_address}")
@@ -287,8 +353,10 @@ async def get_pool(
 ):
     """One pool by address, so ``/dex/{network}/{address}`` renders from a URL alone.
 
-    404 when the pool is genuinely unknown *or* the lookup failed: either way the
-    workspace has nothing to draw, and the two are indistinguishable to the user.
+    404 when the pool is genuinely unknown, 503 when the lookup was refused by the
+    shared GeckoTerminal budget: the workspace has nothing to draw either way, but
+    only one of the two is worth retrying, and the user cannot tell them apart
+    unless the route does.
     """
 
     if not _POOL_ADDRESS_RE.match(pool_address):
@@ -296,8 +364,23 @@ async def get_pool(
 
     from condor.pool_data import fetch_pool_by_address
 
+    before = _throttle_counter()
     pool = await fetch_pool_by_address(network, pool_address)
     if not pool:
+        # A throttled lookup is a different answer from an unknown pool, and the
+        # difference is the whole point: one is worth retrying in a moment, the
+        # other never resolves. 503 rather than 404 so the browser can say so and
+        # offer a retry instead of sending the user back to the browser.
+        state = _upstream_state(_throttle_counter() > before)
+        if state["throttled_request"] or state["rate_limited"]:
+            wait = state["retry_in"] or 20
+            raise HTTPException(
+                status_code=503,
+                detail=(
+                    "GeckoTerminal is rate limiting Condor, so this pool could "
+                    f"not be read. Try again in about {wait:.0f}s."
+                ),
+            )
         raise HTTPException(status_code=404, detail="Pool not found")
     return pool
 
diff --git a/frontend/src/components/dex/LpPositions.tsx b/frontend/src/components/dex/LpPositions.tsx
index 365a95d8..0cb8319f 100644
--- a/frontend/src/components/dex/LpPositions.tsx
+++ b/frontend/src/components/dex/LpPositions.tsx
@@ -94,6 +94,7 @@ export function LpPositions({ server }: { server: string }) {
         Object.entries(byNetwork).map(([network, addresses]) =>
           api
             .getDexPoolsByAddress(server, network, addresses)
+            .then((r) => r.pools)
             .catch(() => [] as PoolSummary[]),
         ),
       );
diff --git a/frontend/src/lib/api.ts b/frontend/src/lib/api.ts
index 9211259a..ebe4004a 100644
--- a/frontend/src/lib/api.ts
+++ b/frontend/src/lib/api.ts
@@ -355,10 +355,35 @@ export interface PoolQuery {
   page?: number;
 }
 
+/**
+ * How much of the shared GeckoTerminal budget is left, and whether it just ran out.
+ *
+ * Every DEX view reads the same per-IP budget, and every failure behind it
+ * degrades to an empty list — so without this a throttled fetch and a chain with
+ * no pools look identical in the table.
+ */
+export interface DexUpstream {
+  /** The breaker is open: gecko answered 429 and Condor has stopped calling. */
+  rate_limited: boolean;
+  /** *This* response was short because the request was refused. Can be true while
+   *  `rate_limited` is false: a spent per-minute budget refuses without tripping. */
+  throttled_request: boolean;
+  /** Seconds left on the cooldown, at the time the response was produced. */
+  retry_in: number;
+  requests_last_minute: number;
+  budget: number;
+  /** Monotonic counters, so a poller can spot a refusal it did not witness. */
+  throttled_calls: number;
+  count_429: number;
+  seconds_since_429: number | null;
+}
+
 /** A page of pools. `has_more`, not a count — no upstream reports a total. */
 export interface PoolPage {
   pools: PoolSummary[];
   has_more: boolean;
+  /** Absent on the Gateway/Orca tabs, which do not read GeckoTerminal. */
+  upstream?: DexUpstream;
 }
 
 /** One venue GeckoTerminal indexes on a chain, for the browser's dex filter. */
@@ -1363,9 +1388,17 @@ export const api = {
     if (q.dexes?.length) params.set("dexes", q.dexes.join(","));
     params.set("limit", String(q.limit ?? 20));
     params.set("page", String(q.page ?? 1));
-    return apiFetch<{ pools: PoolSummary[]; has_more?: boolean }>(
-      `/api/v1/servers/${encodeURIComponent(server)}/dex/pools?${params}`,
-    ).then((r) => ({ pools: r.pools ?? [], has_more: !!r.has_more }));
+    return apiFetch<{
+      pools: PoolSummary[];
+      has_more?: boolean;
+      upstream?: DexUpstream;
+    }>(`/api/v1/servers/${encodeURIComponent(server)}/dex/pools?${params}`).then(
+      (r) => ({
+        pools: r.pools ?? [],
+        has_more: !!r.has_more,
+        upstream: r.upstream,
+      }),
+    );
   },
 
   /**
@@ -1389,10 +1422,29 @@ export const api = {
    * address, so its TVL and volume are re-read rather than replayed from
    * whenever it was starred.
    */
-  getDexPoolsByAddress: (server: string, network: string, addresses: string[]) =>
-    apiFetch<{ pools: PoolSummary[] }>(
+  getDexPoolsByAddress: (
+    server: string,
+    network: string,
+    addresses: string[],
+  ): Promise<PoolPage> =>
+    apiFetch<{ pools: PoolSummary[]; upstream?: DexUpstream }>(
       `/api/v1/servers/${encodeURIComponent(server)}/dex/pools-by-address?network=${encodeURIComponent(network)}&addresses=${encodeURIComponent(addresses.join(","))}`,
-    ).then((r) => r.pools ?? []),
+    ).then((r) => ({
+      pools: r.pools ?? [],
+      has_more: false,
+      upstream: r.upstream,
+    })),
+
+  /**
+   * Whether GeckoTerminal is currently throttling Condor.
+   *
+   * Reads process-local counters only, so polling it while a cooldown banner
+   * counts down costs nothing of the budget the banner is waiting on.
+   */
+  getDexUpstream: (server: string) =>
+    apiFetch<DexUpstream>(
+      `/api/v1/servers/${encodeURIComponent(server)}/dex/upstream`,
+    ),
 
   /** One pool by address, so /dex/{network}/{address} renders from the URL alone. */
   getDexPoolByAddress: (server: string, address: string, network: string) =>
diff --git a/frontend/src/pages/Dex.tsx b/frontend/src/pages/Dex.tsx
index 2b4fdd49..4f15ecae 100644
--- a/frontend/src/pages/Dex.tsx
+++ b/frontend/src/pages/Dex.tsx
@@ -7,7 +7,9 @@ import { NoServerCard } from "@/components/NoServerCard";
 import { LpPositions } from "@/components/dex/LpPositions";
 import { PoolBrowser } from "@/components/dex/PoolBrowser";
 import { PoolSourceTabs } from "@/components/dex/PoolSourceTabs";
+import { UpstreamNotice } from "@/components/dex/UpstreamNotice";
 import type { PoolSource } from "@/components/dex/pool-source";
+import { useDexUpstream } from "@/hooks/useDexUpstream";
 import { useServer } from "@/hooks/useServer";
 import { api, type PoolSummary } from "@/lib/api";
 import { useDexFavorites } from "@/lib/dexFavorites";
@@ -46,6 +48,9 @@ export function Dex() {
   const { server } = useServer();
   const navigate = useNavigate();
   const { favorites } = useDexFavorites();
+  // Everything on this page comes from one shared GeckoTerminal budget; when it
+  // is spent the tables empty out, so the reason is shown above them.
+  const upstream = useDexUpstream(server ?? null);
   const [source, setSource] = useState<PoolSource>({
     kind: "gecko",
     view: "trending",
@@ -125,7 +130,11 @@ export function Dex() {
     source.kind !== "favorites" &&
     (source.kind === "gateway" || !isSearch || isAddress);
 
-  const { data: pagedPools, isFetching } = useQuery({
+  const {
+    data: pagedPools,
+    isFetching,
+    dataUpdatedAt: poolsUpdatedAt,
+  } = useQuery({
     queryKey: [
       "dex-pools",
       server,
@@ -187,7 +196,11 @@ export function Dex() {
     [favorites, network],
   );
 
-  const { data: favoritePools = [], isFetching: favoritesFetching } = useQuery({
+  const {
+    data: favoritePage,
+    isFetching: favoritesFetching,
+    dataUpdatedAt: favoritesUpdatedAt,
+  } = useQuery({
     queryKey: ["dex-favorites", server, network, favoriteAddresses.join(",")],
     queryFn: () =>
       api.getDexPoolsByAddress(server!, network, favoriteAddresses),
@@ -195,6 +208,17 @@ export function Dex() {
       !!server && source.kind === "favorites" && !!favoriteAddresses.length,
     staleTime: POOL_STALE_MS,
   });
+  const favoritePools = favoritePage?.pools ?? [];
+
+  // A response knows it was throttled before the next poll of /dex/upstream does,
+  // and it is the response whose empty table the user is looking at.
+  const reportUpstream = upstream.report;
+  useEffect(() => {
+    reportUpstream(pagedPools?.upstream, poolsUpdatedAt);
+  }, [pagedPools, poolsUpdatedAt, reportUpstream]);
+  useEffect(() => {
+    reportUpstream(favoritePage?.upstream, favoritesUpdatedAt);
+  }, [favoritePage, favoritesUpdatedAt, reportUpstream]);
 
   if (!server) {
     return (
@@ -208,13 +232,22 @@ export function Dex() {
     ? favoritesFetching && !favoritePools.length
     : isFetching && !pagedPools;
 
+  // A throttled fetch and a chain with no pools both arrive as zero rows, and
+  // only one of them is worth waiting out — so the table says which it was.
+  const throttledPage =
+    (isFavorites ? favoritePage?.upstream : pagedPools?.upstream)
+      ?.throttled_request ?? false;
   const emptyMessage = isFavorites
-    ? "No favorites yet — star a pool to keep it here."
+    ? throttledPage
+      ? "GeckoTerminal is rate limiting Condor — your favorites will reappear in a moment."
+      : "No favorites yet — star a pool to keep it here."
     : isSearch && !isAddress
       ? debouncedQuery
         ? "That is not a pool or token address."
         : "Paste a pool or token address to find it."
-      : "No pools found.";
+      : throttledPage || upstream.limited
+        ? "GeckoTerminal is rate limiting Condor — no pools could be read. This clears on its own in a few seconds."
+        : "No pools found.";
 
   return (
     <div className="flex flex-col gap-4">
@@ -232,6 +265,8 @@ export function Dex() {
       <LpPositions server={server} />
 
       <div className="overflow-hidden rounded-lg border border-[var(--color-border)]">
+        <UpstreamNotice state={upstream} className="border-b" />
+
         <PoolSourceTabs
           source={source}
           onSourceChange={setSource}
diff --git a/frontend/src/pages/DexPool.tsx b/frontend/src/pages/DexPool.tsx
index ee1c716a..05070d75 100644
--- a/frontend/src/pages/DexPool.tsx
+++ b/frontend/src/pages/DexPool.tsx
@@ -7,6 +7,7 @@ import { NoServerCard } from "@/components/NoServerCard";
 import { LiquidityDepthColumn } from "@/components/dex/LiquidityDepthColumn";
 import { LpPositionBar } from "@/components/dex/LpPositionBar";
 import { PoolStats } from "@/components/dex/PoolStats";
+import { UpstreamNotice } from "@/components/dex/UpstreamNotice";
 import { LPConfigPanel } from "@/components/executor/LPConfigPanel";
 import { useLpConfig } from "@/components/executor/lp-config";
 import {
@@ -15,6 +16,7 @@ import {
 } from "@/components/executor/OrderConfigPanel";
 import { TradeBottomPane } from "@/components/trade/TradeBottomPane";
 import { TradeChart, type ChartPriceAxis } from "@/components/trade/TradeChart";
+import { useDexUpstream } from "@/hooks/useDexUpstream";
 import { useMainControllerData } from "@/hooks/useMainControllerData";
 import { usePairBalances } from "@/hooks/usePairBalances";
 import { useResizeDrag } from "@/hooks/useResizeDrag";
@@ -41,6 +43,9 @@ export function DexPool() {
   const navigate = useNavigate();
   const queryClient = useQueryClient();
   const { network = "", address = "" } = useParams();
+  // The pool, its stats and its candles all come from the same shared
+  // GeckoTerminal budget: when it is spent this page silently stops updating.
+  const upstream = useDexUpstream(server ?? null);
 
   const [wantedTab, setTab] = useState<Tab>("order");
   // 5m over 3 days, matching the executor pages. Not 1m: GeckoTerminal caps a
@@ -230,17 +235,38 @@ export function DexPool() {
   }
 
   if (poolError || !pool) {
+    // A pool that could not be *read* is not a pool that does not exist: the
+    // route answers 503 with a reason when GeckoTerminal refused, and retrying
+    // in a few seconds is the fix — not walking back to the browser.
+    const throttled = upstream.limited || /rate limit/i.test(poolError?.message ?? "");
     return (
       <div className="flex min-h-[60vh] flex-col items-center justify-center gap-3">
-        <p className="text-sm text-[var(--color-text-muted)]">
-          No pool at {address.slice(0, 8)}… on {network}.
+        <p className="max-w-md text-center text-sm text-[var(--color-text-muted)]">
+          {throttled
+            ? (poolError?.message ??
+              "GeckoTerminal is rate limiting Condor, so this pool could not be read.")
+            : `No pool at ${address.slice(0, 8)}… on ${network}.`}
         </p>
-        <button
-          onClick={() => navigate("/dex")}
-          className="rounded-md border border-[var(--color-border)] px-3 py-1.5 text-xs text-[var(--color-text-muted)] hover:text-[var(--color-text)]"
-        >
-          Back to pools
-        </button>
+        <div className="flex gap-2">
+          {throttled && (
+            <button
+              onClick={() =>
+                queryClient.invalidateQueries({
+                  queryKey: ["dex-pool-by-address", server, network, address],
+                })
+              }
+              className="rounded-md border border-[var(--color-border)] px-3 py-1.5 text-xs text-[var(--color-text)] hover:bg-[var(--color-surface-hover)]"
+            >
+              {upstream.retryIn > 0 ? `Retry (${upstream.retryIn}s)` : "Retry"}
+            </button>
+          )}
+          <button
+            onClick={() => navigate("/dex")}
+            className="rounded-md border border-[var(--color-border)] px-3 py-1.5 text-xs text-[var(--color-text-muted)] hover:text-[var(--color-text)]"
+          >
+            Back to pools
+          </button>
+        </div>
       </div>
     );
   }
@@ -252,6 +278,10 @@ export function DexPool() {
 
   return (
     <div className="-m-6 flex h-[calc(100%+3rem)] flex-col">
+      {/* Nothing on this page fails loudly when the budget is spent — the chart
+          just stops moving and the stats freeze — so it is said here instead. */}
+      <UpstreamNotice state={upstream} className="shrink-0 border-b" />
+
       {/* Top bar */}
       <div className="flex shrink-0 flex-wrap items-center gap-x-4 gap-y-2 border-b border-[var(--color-border)] px-3 py-2">
         <button

From 4758503c50ccd3bb976e81cddebd0ee60671d455 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Tue, 18 Aug 2026 19:02:51 +0300
Subject: [PATCH 114/116] (feat) adapt to telemetry

---
 condor/telemetry/outbox.py     | 11 +++++-
 condor/web/routes/dex.py       | 55 ++++++++++++++++++++++++++
 condor/web/routes/executors.py | 36 +++++++++++++++++
 frontend/src/lib/api.ts        | 24 ++++++++++++
 frontend/src/pages/DexPool.tsx | 70 +++++++++++++++++++++++++++++++++-
 5 files changed, 193 insertions(+), 3 deletions(-)

diff --git a/condor/telemetry/outbox.py b/condor/telemetry/outbox.py
index 48a96e8a..a11b7487 100644
--- a/condor/telemetry/outbox.py
+++ b/condor/telemetry/outbox.py
@@ -37,6 +37,11 @@
 MAX_OUTBOX_EVENTS = 5000
 MAX_OUTBOX_AGE_S = 7 * 24 * 3600
 MAX_BATCH_BYTES = 512 * 1024
+# Collectors cap an envelope by event count as well as by size — the reference
+# collector refuses more than 500 with 413 too_many_events. Splitting on bytes
+# alone let a backlog build envelopes no collector would ever accept, so the
+# outbox could never drain. Keep this at or below the smallest cap we target.
+MAX_BATCH_EVENTS = 500
 POST_TIMEOUT_S = 10
 
 
@@ -183,13 +188,15 @@ def purge() -> None:
 
 
 def batches(events: list[dict]) -> list[list[dict]]:
-    """Split into envelopes no bigger than :data:`MAX_BATCH_BYTES`."""
+    """Split into envelopes within both :data:`MAX_BATCH_BYTES` and
+    :data:`MAX_BATCH_EVENTS`."""
     out: list[list[dict]] = []
     current: list[dict] = []
     size = 0
     for event in events:
         length = len(json.dumps(event, separators=(",", ":")))
-        if current and size + length > MAX_BATCH_BYTES:
+        full = size + length > MAX_BATCH_BYTES or len(current) >= MAX_BATCH_EVENTS
+        if current and full:
             out.append(current)
             current, size = [], 0
         current.append(event)
diff --git a/condor/web/routes/dex.py b/condor/web/routes/dex.py
index d44ad7b4..3c5781dc 100644
--- a/condor/web/routes/dex.py
+++ b/condor/web/routes/dex.py
@@ -16,6 +16,7 @@
 import re
 
 from fastapi import APIRouter, Depends, HTTPException, Query
+from pydantic import BaseModel, Field
 
 from condor import dex_candles
 from condor.web.auth import require_server_access
@@ -316,6 +317,60 @@ async def get_upstream(
     return _upstream_state()
 
 
+class EnsureTokensRequest(BaseModel):
+    """The tokens a pool is made of, as the browser already knows them."""
+
+    network: str = Field(description="Gateway network id, e.g. solana-mainnet-beta")
+    addresses: list[str] = Field(
+        default_factory=list,
+        description="Token mints/contracts to register — a pool's base and quote",
+    )
+
+
+@router.post("/servers/{name}/dex/tokens")
+async def ensure_dex_tokens(
+    name: str,
+    body: EnsureTokensRequest,
+    user: WebUser = Depends(require_server_access),
+):
+    """Make sure Gateway's token list holds this pool's tokens.
+
+    Called when a pool workspace opens rather than when an order is placed,
+    because the panel needs the tokens *before* the trade: an unlisted mint reads
+    as a zero balance, which greys out the percentage presets and sizes an LP
+    position against a wallet that looks empty. Idempotent and memoized, so
+    re-opening a pool costs nothing.
+
+    Never fatal. A pool whose tokens could not be registered is still browsable,
+    chartable and (on Solana, where Gateway resolves a mint on chain) tradable —
+    so a failure is reported per token and left for the panel to surface, not
+    raised.
+    """
+    from condor.fetchers.gateway_tokens import ensure_tokens_listed, token_addresses
+    from condor.pool_data import GECKO_TO_GATEWAY_NETWORK, NETWORK_TO_GECKO
+
+    # Canonicalized rather than taken as given: a pool row can name its chain the
+    # gecko way (``solana``) while Gateway only answers to ``solana-mainnet-beta``.
+    gateway_network = GECKO_TO_GATEWAY_NETWORK.get(
+        NETWORK_TO_GECKO.get(body.network, "")
+    )
+    if not gateway_network:
+        raise HTTPException(status_code=400, detail="Unknown network")
+
+    addresses = token_addresses(*body.addresses)
+    if not addresses:
+        return {"tokens": {}}
+
+    cm = get_config_manager()
+    client = await cm.get_client(name)
+    try:
+        verdicts = await ensure_tokens_listed(client, gateway_network, addresses)
+    except Exception as e:
+        logger.warning("ensure tokens failed on %s: %s", gateway_network, e)
+        verdicts = {address: "failed" for address in addresses}
+    return {"tokens": verdicts}
+
+
 @router.get("/servers/{name}/dex/pools-by-address")
 async def list_pools_by_address(
     name: str,
diff --git a/condor/web/routes/executors.py b/condor/web/routes/executors.py
index cf5feb5c..26e2098a 100644
--- a/condor/web/routes/executors.py
+++ b/condor/web/routes/executors.py
@@ -303,6 +303,40 @@ async def executors_summary(
     return summary
 
 
+async def _ensure_dex_tokens_listed(client, config: dict) -> None:
+    """Register a DEX executor's tokens with Gateway before it is created.
+
+    The pool workspace already does this when it opens, so for the web UI this is
+    a no-op resolved from an in-process memo. It exists for the callers that never
+    open one — agents, Telegram, MCP — because an unlisted mint reads as a zero
+    balance in Gateway, which is enough to have an order rejected for funds the
+    wallet is holding.
+
+    Best effort by design: a token that cannot be registered is not a reason to
+    refuse an order Gateway may well execute anyway.
+    """
+    connector = str(config.get("connector_name") or "")
+    if not connector:
+        return
+    try:
+        from condor.fetchers.gateway_tokens import (
+            ensure_tokens_listed,
+            token_addresses,
+        )
+        from condor.pool_data import GECKO_TO_GATEWAY_NETWORK, NETWORK_TO_GECKO
+
+        # A CEX connector ("binance") maps to no chain and drops out here; only a
+        # Gateway network id ("solana-mainnet-beta") reaches the token list.
+        network = GECKO_TO_GATEWAY_NETWORK.get(NETWORK_TO_GECKO.get(connector, ""))
+        if not network:
+            return
+        addresses = token_addresses(config.get("trading_pair"))
+        if addresses:
+            await ensure_tokens_listed(client, network, addresses)
+    except Exception as e:
+        logger.warning("could not ensure tokens for %s: %s", connector, e)
+
+
 @router.post("/servers/{name}/executors")
 async def create_executor_endpoint(
     name: str,
@@ -316,6 +350,8 @@ async def create_executor_endpoint(
     # Inject executor type into config
     config = {**body.config, "type": body.executor_type}
 
+    await _ensure_dex_tokens_listed(client, config)
+
     from condor.fetchers.executors import create_executor
 
     try:
diff --git a/frontend/src/lib/api.ts b/frontend/src/lib/api.ts
index ebe4004a..dae2d617 100644
--- a/frontend/src/lib/api.ts
+++ b/frontend/src/lib/api.ts
@@ -378,6 +378,15 @@ export interface DexUpstream {
   seconds_since_429: number | null;
 }
 
+/**
+ * What became of one token Condor tried to register with Gateway.
+ *
+ * `symbol_taken` is the one worth surfacing: another token on the list already
+ * holds this ticker, so Gateway refused to save this one and its balance will
+ * keep reading 0 until a human decides which token owns the symbol.
+ */
+export type DexTokenVerdict = "listed" | "added" | "symbol_taken" | "failed";
+
 /** A page of pools. `has_more`, not a count — no upstream reports a total. */
 export interface PoolPage {
   pools: PoolSummary[];
@@ -1446,6 +1455,21 @@ export const api = {
       `/api/v1/servers/${encodeURIComponent(server)}/dex/upstream`,
     ),
 
+  /**
+   * Make sure Gateway's token list holds a pool's two tokens.
+   *
+   * Gateway resolves a swap by mint address on its own, but not a *balance*: it
+   * skips token accounts whose mint is not on the list, so an unregistered token
+   * reads as 0 and the panel greys out its percentage presets. Called when a pool
+   * opens rather than when an order is sent, and idempotent server-side, so
+   * re-opening the same pool costs nothing.
+   */
+  ensureDexTokens: (server: string, network: string, addresses: string[]) =>
+    apiFetch<{ tokens: Record<string, DexTokenVerdict> }>(
+      `/api/v1/servers/${encodeURIComponent(server)}/dex/tokens`,
+      { method: "POST", body: JSON.stringify({ network, addresses }) },
+    ),
+
   /** One pool by address, so /dex/{network}/{address} renders from the URL alone. */
   getDexPoolByAddress: (server: string, address: string, network: string) =>
     apiFetch<PoolSummary>(
diff --git a/frontend/src/pages/DexPool.tsx b/frontend/src/pages/DexPool.tsx
index 05070d75..9430b84f 100644
--- a/frontend/src/pages/DexPool.tsx
+++ b/frontend/src/pages/DexPool.tsx
@@ -1,5 +1,13 @@
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
-import { ArrowLeft, CheckCircle, ChevronLeft, ChevronRight, Copy, X } from "lucide-react";
+import {
+  AlertTriangle,
+  ArrowLeft,
+  CheckCircle,
+  ChevronLeft,
+  ChevronRight,
+  Copy,
+  X,
+} from "lucide-react";
 import { useEffect, useMemo, useState } from "react";
 import { useNavigate, useParams } from "react-router-dom";
 
@@ -106,6 +114,45 @@ export function DexPool() {
     staleTime: 60 * 1000,
   });
 
+  // Registering the pool's tokens with Gateway is part of opening the pool, not
+  // part of sending an order: an unlisted mint reads as a zero balance, so the
+  // percentage presets and the LP amounts would be sized against a wallet that
+  // looks empty long before anything is submitted. Idempotent and memoized
+  // server-side, so a reload or a second visit sends this and gets a no-op.
+  const { data: tokenVerdicts } = useQuery({
+    queryKey: ["dex-ensure-tokens", server, network, pool?.address],
+    queryFn: () =>
+      api
+        .ensureDexTokens(server!, network, [
+          pool!.base_token_address,
+          pool!.quote_token_address,
+        ])
+        .then((r) => r.tokens),
+    enabled:
+      !!server && !!network && !!(pool?.base_token_address || pool?.quote_token_address),
+    staleTime: Infinity,
+    retry: false,
+  });
+
+  // A token that was *just* added is one the portfolio was fetched without, so
+  // its balance is still missing from the copy the panels are reading.
+  useEffect(() => {
+    if (Object.values(tokenVerdicts ?? {}).includes("added")) {
+      queryClient.invalidateQueries({ queryKey: ["portfolio", server] });
+    }
+  }, [tokenVerdicts, queryClient, server]);
+
+  // Reported rather than swallowed: Gateway refuses to list a token whose ticker
+  // another token already holds, and the only visible symptom is a balance that
+  // stays 0 for a wallet that is not empty.
+  const unlistedTokens = useMemo(
+    () =>
+      Object.entries(tokenVerdicts ?? {})
+        .filter(([, verdict]) => verdict === "symbol_taken" || verdict === "failed")
+        .map(([address]) => address),
+    [tokenVerdicts],
+  );
+
   const { data: venues = [] } = useQuery({
     queryKey: ["venues", server],
     queryFn: () => api.getVenues(server!),
@@ -282,6 +329,27 @@ export function DexPool() {
           just stops moving and the stats freeze — so it is said here instead. */}
       <UpstreamNotice state={upstream} className="shrink-0 border-b" />
 
+      {/* Gateway lists a token by ticker, so a pool whose token shares a ticker
+          with one already on the list cannot be registered — and the only symptom
+          is a balance that reads 0 for a wallet that is not empty. */}
+      {unlistedTokens.length > 0 && (
+        <div
+          role="status"
+          className="flex shrink-0 flex-wrap items-center gap-x-2 gap-y-1 border-b border-amber-500/30 bg-amber-500/10 px-4 py-2 text-xs"
+        >
+          <AlertTriangle className="h-3.5 w-3.5 shrink-0 text-[var(--color-yellow)]" />
+          <span className="font-medium text-[var(--color-yellow)]">
+            {unlistedTokens.length === 1 ? "A token is" : "Tokens are"} not in
+            Gateway&apos;s token list
+          </span>
+          <span className="text-[var(--color-text-muted)]">
+            Balances for {unlistedTokens.map((a) => `${a.slice(0, 6)}…`).join(", ")}{" "}
+            will read 0 — add {unlistedTokens.length === 1 ? "it" : "them"} under
+            Gateway tokens to size orders from this wallet.
+          </span>
+        </div>
+      )}
+
       {/* Top bar */}
       <div className="flex shrink-0 flex-wrap items-center gap-x-4 gap-y-2 border-b border-[var(--color-border)] px-3 py-2">
         <button

From 7ea0efcb5fbfabc16bb6b630662955cf4843a623 Mon Sep 17 00:00:00 2001
From: cardosofede <federico.cardoso.e@gmail.com>
Date: Tue, 18 Aug 2026 19:08:33 +0300
Subject: [PATCH 115/116] (feat) add dex compoennets

---
 .../src/components/dex/UpstreamNotice.tsx     |  46 +++++++
 frontend/src/hooks/useDexUpstream.ts          | 126 ++++++++++++++++++
 2 files changed, 172 insertions(+)
 create mode 100644 frontend/src/components/dex/UpstreamNotice.tsx
 create mode 100644 frontend/src/hooks/useDexUpstream.ts

diff --git a/frontend/src/components/dex/UpstreamNotice.tsx b/frontend/src/components/dex/UpstreamNotice.tsx
new file mode 100644
index 00000000..016d6d7a
--- /dev/null
+++ b/frontend/src/components/dex/UpstreamNotice.tsx
@@ -0,0 +1,46 @@
+import { Gauge } from "lucide-react";
+
+import type { DexUpstreamState } from "@/hooks/useDexUpstream";
+
+/**
+ * "GeckoTerminal is throttling us", said where the missing data would have been.
+ *
+ * Everything on the DEX panel — pool rows, TVL, the chart — comes from one per-IP
+ * GeckoTerminal budget shared by every viewer and every polling chart, and every
+ * failure behind it degrades to an empty list. So the difference between "this
+ * chain has no pools" and "ask again in ten seconds" is invisible unless it is
+ * said out loud. Renders nothing while the budget is healthy.
+ */
+export function UpstreamNotice({
+  state,
+  className = "",
+}: {
+  state: DexUpstreamState;
+  className?: string;
+}) {
+  if (!state.limited) return null;
+
+  return (
+    <div
+      role="status"
+      className={`flex flex-wrap items-center gap-x-2 gap-y-1 border-amber-500/30 bg-amber-500/10 px-4 py-2 text-xs ${className}`}
+    >
+      <Gauge className="h-3.5 w-3.5 shrink-0 text-[var(--color-yellow)]" />
+      <span className="font-medium text-[var(--color-yellow)]">
+        Market data is rate limited
+      </span>
+      <span className="text-[var(--color-text-muted)]">
+        GeckoTerminal is throttling Condor, so pools and prices may be missing or
+        stale.
+        {state.retryIn > 0
+          ? ` Retrying in ${state.retryIn}s.`
+          : " Retrying shortly."}
+      </span>
+      {state.budget > 0 && (
+        <span className="ml-auto shrink-0 tabular-nums text-[var(--color-text-muted)]">
+          {state.requestsLastMinute}/{state.budget} req/min
+        </span>
+      )}
+    </div>
+  );
+}
diff --git a/frontend/src/hooks/useDexUpstream.ts b/frontend/src/hooks/useDexUpstream.ts
new file mode 100644
index 00000000..a6f0fcdd
--- /dev/null
+++ b/frontend/src/hooks/useDexUpstream.ts
@@ -0,0 +1,126 @@
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { useCallback, useEffect, useRef, useState } from "react";
+
+import { api, type DexUpstream } from "@/lib/api";
+
+/** Idle poll. Reads process-local counters, so it costs nothing upstream. */
+const POLL_HEALTHY_MS = 20_000;
+/** While throttled: often enough that the banner clears on its own. */
+const POLL_LIMITED_MS = 5_000;
+/**
+ * How long one refusal keeps the banner up.
+ *
+ * A spent per-minute budget refuses a request without opening the breaker, so
+ * there is no cooldown to count down against — the only evidence is a counter
+ * that ticked. Long enough to be read, short enough to clear itself once the
+ * window drains.
+ */
+const STICKY_MS = 30_000;
+
+export interface DexUpstreamState {
+  /** Show the notice: gecko is refusing, or refused something moments ago. */
+  limited: boolean;
+  /** Whole seconds left on the cooldown; 0 when there is no cooldown to wait on. */
+  retryIn: number;
+  requestsLastMinute: number;
+  budget: number;
+  /**
+   * Report the `upstream` block that came back with a pool response.
+   *
+   * The poll finds out within a few seconds anyway, but the request the user is
+   * looking at knows *now* — and the table they are staring at is the one that
+   * came back empty. `updatedAt` is when that response was received: a cached
+   * page re-rendered later carries a throttle flag that has long since expired.
+   */
+  report: (upstream: DexUpstream | undefined, updatedAt: number) => void;
+}
+
+/**
+ * Whether GeckoTerminal is throttling Condor, for the DEX views that depend on it.
+ *
+ * Every pool row, pool page and chart on the dashboard shares one per-IP budget,
+ * and everything behind that budget degrades to an empty list when it is spent.
+ * Without this the DEX panel shows "No pools found" for a chain with thousands of
+ * them, and a chart that simply stops moving — three failure modes that look like
+ * the product being broken rather than a limit that clears in seconds.
+ *
+ * Refills the DEX queries when the limit clears, so the tables come back on their
+ * own rather than waiting for the user to suspect a reload might help.
+ */
+export function useDexUpstream(server: string | null): DexUpstreamState {
+  const queryClient = useQueryClient();
+  const [stickyUntil, setStickyUntil] = useState(0);
+  const [now, setNow] = useState(() => Date.now());
+  const lastCounter = useRef<number | null>(null);
+  const wasLimited = useRef(false);
+
+  const { data, dataUpdatedAt } = useQuery({
+    queryKey: ["dex-upstream", server],
+    // The diff lives in the fetch rather than in an effect on its result: a
+    // refusal between two polls leaves no flag behind — only these monotonic
+    // counters move — and comparing them is something the fetch already knows
+    // how to do without a render pass in between.
+    queryFn: async () => {
+      const state = await api.getDexUpstream(server!);
+      const counter = state.throttled_calls + state.count_429;
+      const previous = lastCounter.current;
+      lastCounter.current = counter;
+      if ((previous !== null && counter > previous) || state.rate_limited) {
+        setNow(Date.now());
+        setStickyUntil(Date.now() + STICKY_MS);
+      }
+      return state;
+    },
+    enabled: !!server,
+    // Stops polling if the endpoint is not there (an older backend): a banner
+    // nobody can raise is not worth a request every twenty seconds.
+    retry: false,
+    refetchInterval: (query) =>
+      query.state.status === "error"
+        ? false
+        : query.state.data?.rate_limited
+          ? POLL_LIMITED_MS
+          : POLL_HEALTHY_MS,
+    // A throttled dashboard is exactly when a background tab should stop asking.
+    refetchIntervalInBackground: false,
+  });
+
+  const report = useCallback((upstream: DexUpstream | undefined, updatedAt: number) => {
+    if (!upstream || Date.now() - updatedAt > STICKY_MS) return;
+    if (upstream.throttled_request || upstream.rate_limited) {
+      setNow(Date.now());
+      setStickyUntil(Date.now() + STICKY_MS);
+    }
+  }, []);
+
+  const cooldownEnd =
+    data?.rate_limited && dataUpdatedAt
+      ? dataUpdatedAt + data.retry_in * 1000
+      : 0;
+  const limited = now < cooldownEnd || now < stickyUntil;
+
+  // Only while something is counting down: an idle DEX page re-renders nothing.
+  useEffect(() => {
+    if (!limited) return;
+    const id = setInterval(() => setNow(Date.now()), 1000);
+    return () => clearInterval(id);
+  }, [limited]);
+
+  useEffect(() => {
+    if (wasLimited.current && !limited) {
+      // The rows that came back empty are cached as if they were the answer.
+      for (const key of ["dex-pools", "dex-pool-by-address", "dex-favorites"]) {
+        queryClient.invalidateQueries({ queryKey: [key] });
+      }
+    }
+    wasLimited.current = limited;
+  }, [limited, queryClient]);
+
+  return {
+    limited,
+    retryIn: Math.max(0, Math.ceil((cooldownEnd - now) / 1000)),
+    requestsLastMinute: data?.requests_last_minute ?? 0,
+    budget: data?.budget ?? 0,
+    report,
+  };
+}

From b83f3b27bc57165d294b5fe1927193c63d5d2fcb Mon Sep 17 00:00:00 2001
From: Michael Feng <mifeng@gmail.com>
Date: Tue, 18 Aug 2026 11:12:27 -0700
Subject: [PATCH 116/116] (fix) label DEX chart interval/window controls, hide
 contradictory empty state

- Add "Interval" and "Window" labels with a divider in the DEX pool chart
  toolbar so the two button groups aren't ambiguous.
- Suppress the "No pools found." table when a pasted pool address already
  resolved to a direct match shown above it.
---
 frontend/src/pages/Dex.tsx     | 24 ++++++++++++++----------
 frontend/src/pages/DexPool.tsx |  3 +++
 2 files changed, 17 insertions(+), 10 deletions(-)

diff --git a/frontend/src/pages/Dex.tsx b/frontend/src/pages/Dex.tsx
index 4f15ecae..dc13e976 100644
--- a/frontend/src/pages/Dex.tsx
+++ b/frontend/src/pages/Dex.tsx
@@ -309,16 +309,20 @@ export function Dex() {
           </button>
         )}
 
-        <PoolBrowser
-          pools={pools}
-          isLoading={loading}
-          emptyMessage={emptyMessage}
-          showGatewayColumns={source.kind === "gateway"}
-          network={network}
-          page={isFavorites ? 1 : page}
-          hasMore={isFavorites ? false : !!pagedPools?.has_more}
-          onPageChange={setPage}
-        />
+        {/* The pasted-pool answer above already covers an empty search result —
+            showing "No pools found" under it would contradict what's right above it. */}
+        {!(pastedPool && !pools.length) && (
+          <PoolBrowser
+            pools={pools}
+            isLoading={loading}
+            emptyMessage={emptyMessage}
+            showGatewayColumns={source.kind === "gateway"}
+            network={network}
+            page={isFavorites ? 1 : page}
+            hasMore={isFavorites ? false : !!pagedPools?.has_more}
+            onPageChange={setPage}
+          />
+        )}
       </div>
     </div>
   );
diff --git a/frontend/src/pages/DexPool.tsx b/frontend/src/pages/DexPool.tsx
index 9430b84f..036ecb4e 100644
--- a/frontend/src/pages/DexPool.tsx
+++ b/frontend/src/pages/DexPool.tsx
@@ -371,6 +371,7 @@ export function DexPool() {
       {/* Interval / lookback */}
       <div className="flex shrink-0 items-center gap-4 border-b border-[var(--color-border)] px-3 py-1.5">
         <div className="flex items-center gap-1">
+          <span className="text-[11px] text-[var(--color-text-muted)]">Interval</span>
           {INTERVALS.map((iv) => (
             <button
               key={iv}
@@ -385,7 +386,9 @@ export function DexPool() {
             </button>
           ))}
         </div>
+        <div className="h-4 w-px bg-[var(--color-border)]" />
         <div className="flex items-center gap-1">
+          <span className="text-[11px] text-[var(--color-text-muted)]">Window</span>
           {LOOKBACK_OPTIONS.map((o) => (
             <button
               key={o.label}