solana-traderclaw 1.0.147 → 1.0.148

package/config/gateway-v1-upgraded.json5

@@ -80,11 +80,11 @@
       // ── Portfolio Maintenance ───────────────────────────────────────
       {
         id: "subscription-cleanup",
-        schedule: "15 */8 * * *",
+        schedule: "15 */2 * * *",
         agentId: "main",
         sessionTarget: "isolated",
         delivery: { mode: "announce", channel: "last", bestEffort: true },
-        message: "CRON_JOB: subscription_cleanup\n\nsolana_positions for open CAs → solana_bitquery_subscriptions for active subs (if AUTH_SCOPE_MISSING, log and stop) → match subs to positions → solana_bitquery_unsubscribe orphaned subs → solana_memory_write tag 'subscription_cleanup'. Summarize before/after counts.",
+        message: "CRON_JOB: subscription_cleanup\n\nGOAL: Keep Bitquery subscriptions healthy — one realtimeTokenPricesSolana per OPEN position, total active subs UNDER 20. Do NOT touch alpha (solana_alpha_unsubscribe forbidden).\n\nSTEP 1 — Baseline:\n  solana_runtime_status → note alphaStream.subscribed + bitqueryStream\n  solana_positions → open position CAs (mint addresses)\n  solana_bitquery_subscriptions → active subs + connectedWebSocketClients (if AUTH_SCOPE_MISSING, log and stop)\n\nSTEP 2 — Compute targets:\n  expectedSubs = count(open positions)\n  healthy TCP clients to orchestrator WS ≈ 1–2 (not 10+)\n  per-client Bitquery sub cap = 20 (OPENCLAW_WS_MAX_SUBS_PER_CLIENT)\n\nSTEP 3 — Reconcile:\n  Each active subscription where variables.token NOT in open CAs → solana_bitquery_unsubscribe({ subscriptionId })\n  Each open CA missing realtimeTokenPricesSolana → solana_bitquery_subscribe({ templateKey: \"realtimeTokenPricesSolana\", variables: { token: \"<CA>\" }, agentId: \"main\" })\n  Subs nearing 24h expiry or subscription_expiring → solana_bitquery_subscription_reopen\n\nSTEP 4 — Escalate if still unhealthy after reconcile:\n  If reported activeSubscriptionCount > 20 OR subscribe errors WS_PER_KEY_LIMIT / WS_SUBSCRIPTION_LIMIT_REACHED OR absurd connectedWebSocketClients:\n    solana_memory_write tag subscription_cleanup severity CRITICAL — gateway restart may be required to drop leaked TCP sockets (cron cannot restart the gateway).\n\nSTEP 5 — Report:\n  solana_memory_write tag subscription_cleanup — before/after: openPositions, activeSubs, connectedWebSocketClients, orphansRemoved, subsAdded, reopenedCount.",
         enabled: true
       },
 

package/config/gateway-v1.json5

@@ -69,11 +69,11 @@
       // ── Portfolio Maintenance ───────────────────────────────────────
       {
         id: "subscription-cleanup",
-        schedule: "15 */8 * * *",
+        schedule: "15 */2 * * *",
         agentId: "main",
         sessionTarget: "isolated",
         delivery: { mode: "announce", channel: "last", bestEffort: true },
-        message: "CRON_JOB: subscription_cleanup\n\nsolana_positions for open CAs → solana_bitquery_subscriptions for active subs (if AUTH_SCOPE_MISSING, log and stop) → match subs to positions → solana_bitquery_unsubscribe orphaned subs → solana_memory_write tag 'subscription_cleanup'. Summarize before/after counts.",
+        message: "CRON_JOB: subscription_cleanup\n\nGOAL: Keep Bitquery subscriptions healthy — one realtimeTokenPricesSolana per OPEN position, total active subs UNDER 20. Do NOT touch alpha (solana_alpha_unsubscribe forbidden).\n\nSTEP 1 — Baseline:\n  solana_runtime_status → note alphaStream.subscribed + bitqueryStream\n  solana_positions → open position CAs (mint addresses)\n  solana_bitquery_subscriptions → active subs + connectedWebSocketClients (if AUTH_SCOPE_MISSING, log and stop)\n\nSTEP 2 — Compute targets:\n  expectedSubs = count(open positions)\n  healthy TCP clients to orchestrator WS ≈ 1–2 (not 10+)\n  per-client Bitquery sub cap = 20 (OPENCLAW_WS_MAX_SUBS_PER_CLIENT)\n\nSTEP 3 — Reconcile:\n  Each active subscription where variables.token NOT in open CAs → solana_bitquery_unsubscribe({ subscriptionId })\n  Each open CA missing realtimeTokenPricesSolana → solana_bitquery_subscribe({ templateKey: \"realtimeTokenPricesSolana\", variables: { token: \"<CA>\" }, agentId: \"main\" })\n  Subs nearing 24h expiry or subscription_expiring → solana_bitquery_subscription_reopen\n\nSTEP 4 — Escalate if still unhealthy after reconcile:\n  If reported activeSubscriptionCount > 20 OR subscribe errors WS_PER_KEY_LIMIT / WS_SUBSCRIPTION_LIMIT_REACHED OR absurd connectedWebSocketClients:\n    solana_memory_write tag subscription_cleanup severity CRITICAL — gateway restart may be required to drop leaked TCP sockets (cron cannot restart the gateway).\n\nSTEP 5 — Report:\n  solana_memory_write tag subscription_cleanup — before/after: openPositions, activeSubs, connectedWebSocketClients, orphansRemoved, subsAdded, reopenedCount.",
         enabled: true
       },
 

package/dist/{chunk-S2DLZKMQ.js → chunk-QIURFAOS.js}

@@ -62,23 +62,72 @@ var BitqueryStreamManager = class {
   async unsubscribe(subscriptionId) {
     this.activeSubscriptions.delete(subscriptionId);
     if (!this.ws || this.ws.readyState !== 1) {
+      this.disconnectIfIdle();
       return { unsubscribed: true };
     }
     return new Promise((resolve) => {
+      const finish = () => {
+        resolve({ unsubscribed: true });
+        this.disconnectIfIdle();
+      };
       const timeout = setTimeout(() => {
         this.pendingUnsubscribes.delete(subscriptionId);
-        resolve({ unsubscribed: true });
+        finish();
       }, 1e4);
-      this.pendingUnsubscribes.set(subscriptionId, { resolve, timeout });
+      this.pendingUnsubscribes.set(subscriptionId, { resolve: finish, timeout });
       try {
         this.ws.send(JSON.stringify({ type: "bitquery_unsubscribe", subscriptionId }));
       } catch {
         clearTimeout(timeout);
         this.pendingUnsubscribes.delete(subscriptionId);
-        resolve({ unsubscribed: true });
+        finish();
       }
     });
   }
+  /** Best-effort: notify orchestrator before gateway reconnect / dispose clears local mux. Sequential to avoid reorder races on the FIFO pending queue. */
+  async unsubscribeAll() {
+    const ids = [...this.activeSubscriptions.keys()];
+    let errors = 0;
+    for (const id of ids) {
+      try {
+        await this.unsubscribe(id);
+      } catch {
+        errors += 1;
+      }
+    }
+    this.disconnectIfIdle();
+    return { attempted: ids.length, errors };
+  }
+  /** WebSocket OPEN (TCP connected), not necessarily post-auth Bitquery-ready. */
+  isWebsocketOpen() {
+    return this.ws !== null && this.ws.readyState === 1;
+  }
+  getActiveTokens() {
+    const out = [];
+    for (const sub of this.activeSubscriptions.values()) {
+      const t = sub.variables?.token;
+      if (typeof t === "string" && t.trim()) out.push(t.trim());
+    }
+    return [...new Set(out)];
+  }
+  getActiveSubscriptionIds() {
+    return [...this.activeSubscriptions.keys()];
+  }
+  getStats() {
+    const ls = this.config.lifetimeState;
+    return {
+      lifetimeConnectCount: ls?.lifetimeConnectCount ?? 0,
+      reconnectAttempt: this.reconnectAttempt,
+      intentionalClose: this.intentionalClose,
+      websocketOpen: this.isWebsocketOpen(),
+      authenticated: this.authenticated,
+      activeSubscriptionCount: this.activeSubscriptions.size
+    };
+  }
+  bumpLifetimeConnect() {
+    const ls = this.config.lifetimeState;
+    if (ls) ls.lifetimeConnectCount += 1;
+  }
   /** Close the WS if no active subscriptions remain. */
   disconnectIfIdle() {
     if (this.activeSubscriptions.size === 0) {
@@ -190,6 +239,7 @@ var BitqueryStreamManager = class {
       ws.on("open", () => {
         clearTimeout(connectTimeout);
         this.reconnectAttempt = 0;
+        this.bumpLifetimeConnect();
         this.log("info", "Connected");
         pingInterval = setInterval(() => {
           if (!this.ws || this.ws.readyState !== 1) return;
@@ -274,7 +324,7 @@ var BitqueryStreamManager = class {
         if (pending) {
           clearTimeout(pending.timeout);
           this.pendingUnsubscribes.delete(subscriptionId);
-          pending.resolve({ unsubscribed: true });
+          pending.resolve();
         }
         this.disconnectIfIdle();
         break;
@@ -286,6 +336,7 @@ var BitqueryStreamManager = class {
           "WS_SUBSCRIBE_VALIDATION_ERROR",
           "BITQUERY_SUBSCRIPTION_TEMPLATE_NOT_FOUND",
           "WS_SUBSCRIPTION_LIMIT_REACHED",
+          "WS_PER_KEY_LIMIT",
           "WS_BRIDGE_UNAVAILABLE"
         ].includes(code)) {
           const pending = this.pendingSubscribeQueue.shift();
@@ -309,7 +360,7 @@ var BitqueryStreamManager = class {
     this.pendingSubscribeQueue = [];
     for (const [, pending] of this.pendingUnsubscribes) {
       clearTimeout(pending.timeout);
-      pending.resolve({ unsubscribed: true });
+      pending.resolve();
     }
     this.pendingUnsubscribes.clear();
   }

package/dist/index.js

@@ -22,7 +22,7 @@ import {
 } from "./chunk-GX4HA22L.js";
 import {
   BitqueryStreamManager
-} from "./chunk-S2DLZKMQ.js";
+} from "./chunk-QIURFAOS.js";
 import {
   shouldSyncGatewayCredentials
 } from "./chunk-R24UDHQG.js";
@@ -784,6 +784,9 @@ var SOLANA_TRADER_ALPHA_BUFFER_SINGLETON_KEY = Symbol.for(
 var SOLANA_TRADER_ALPHA_LIFETIME_SINGLETON_KEY = Symbol.for(
   "openclaw.solana-trader.alpha-lifetime.v1"
 );
+var SOLANA_TRADER_BITQUERY_LIFETIME_SINGLETON_KEY = Symbol.for(
+  "openclaw.solana-trader.bitquery-lifetime.v1"
+);
 var __solanaTraderAlphaSingletonHolder = globalThis;
 function getOrCreateAlphaBuffer() {
   const existing = __solanaTraderAlphaSingletonHolder[SOLANA_TRADER_ALPHA_BUFFER_SINGLETON_KEY];
@@ -803,6 +806,13 @@ function getOrCreateAlphaLifetimeState() {
   __solanaTraderAlphaSingletonHolder[SOLANA_TRADER_ALPHA_LIFETIME_SINGLETON_KEY] = fresh;
   return fresh;
 }
+function getOrCreateBitqueryLifetimeState() {
+  const existing = __solanaTraderAlphaSingletonHolder[SOLANA_TRADER_BITQUERY_LIFETIME_SINGLETON_KEY];
+  if (existing) return existing;
+  const fresh = { lifetimeConnectCount: 0 };
+  __solanaTraderAlphaSingletonHolder[SOLANA_TRADER_BITQUERY_LIFETIME_SINGLETON_KEY] = fresh;
+  return fresh;
+}
 var __solanaTraderStatusQueriesMd = (() => {
   try {
     const distPath = fileURLToPath(import.meta.url);
@@ -2064,7 +2074,7 @@ ${notes}
     });
     api.registerTool({
       name: "trade_size_limit_get",
-      description: "Read the per-wallet maximum **buy** size in SOL enforced by the API (stored in `wallet.limits.maxTradeSizeSol`; platform default 1.5 SOL when unset). Always use this before sizing buys; never guess the limit.",
+      description: "Read the effective per-wallet **maximum buy** size in SOL from `GET /api/wallet/max-trade-size` (merges `buyAmounts.maxBuyAmountSol` with legacy `maxTradeSizeSol`). There is no platform default cap when unset \u2014 use the response before sizing buys.",
       parameters: Type.Object({}),
       execute: wrapExecute(
         "trade_size_limit_get",
@@ -2073,7 +2083,7 @@ ${notes}
     });
     api.registerTool({
       name: "trade_size_limit_set",
-      description: "Set the per-wallet maximum buy size in SOL (persisted on the wallet `limits` JSON). Subject to a platform ceiling.",
+      description: "Set the maximum buy size in SOL via `PUT /api/wallet/max-trade-size`. The server also mirrors this into `buyAmounts.maxBuyAmountSol` and sets `buyAmountEnforcement` to `hard` when it was `off`, so executes clamp to this max without denying the trade.",
       parameters: Type.Object({
         maxTradeSizeSol: Type.Number({ exclusiveMinimum: 0 })
       }),
@@ -2085,6 +2095,44 @@ ${notes}
         })
       )
     });
+    const buyAmountSolOptional = Type.Union([
+      Type.Number({ exclusiveMinimum: 0 }),
+      Type.Null()
+    ]);
+    api.registerTool({
+      name: "buy_amount_policy_get",
+      description: "Read `buyAmountEnforcement` and `buyAmounts` (fixed / min / max buy in SOL) from the wallet trading policy \u2014 same settings as the dashboard **Buy amount** card. Use when the user enforces sizing so you do not fight precheck/execute clamps.",
+      parameters: Type.Object({}),
+      execute: wrapExecute("buy_amount_policy_get", async () => {
+        const data = await get(`/api/wallet/trading-policy?walletId=${walletId}`);
+        return {
+          buyAmountEnforcement: data.buyAmountEnforcement ?? "off",
+          buyAmounts: data.buyAmounts ?? {}
+        };
+      })
+    });
+    api.registerTool({
+      name: "buy_amount_policy_set",
+      description: "Update buy sizing policy (`PATCH /api/wallet/trading-policy`). `hard` clamps each buy to fixed or min/max SOL without denying for size alone. `soft` only adds warnings; requested size still runs. Pass `null` for a bound to clear it.",
+      parameters: Type.Object({
+        buyAmountEnforcement: Type.Optional(
+          Type.Union([Type.Literal("off"), Type.Literal("soft"), Type.Literal("hard")])
+        ),
+        fixedBuyAmountSol: Type.Optional(buyAmountSolOptional),
+        minBuyAmountSol: Type.Optional(buyAmountSolOptional),
+        maxBuyAmountSol: Type.Optional(buyAmountSolOptional)
+      }),
+      execute: wrapExecute("buy_amount_policy_set", async (_id, params) => {
+        const body = { walletId };
+        if (params.buyAmountEnforcement !== void 0) body.buyAmountEnforcement = params.buyAmountEnforcement;
+        const buyAmounts = {};
+        if (params.fixedBuyAmountSol !== void 0) buyAmounts.fixedBuyAmountSol = params.fixedBuyAmountSol;
+        if (params.minBuyAmountSol !== void 0) buyAmounts.minBuyAmountSol = params.minBuyAmountSol;
+        if (params.maxBuyAmountSol !== void 0) buyAmounts.maxBuyAmountSol = params.maxBuyAmountSol;
+        if (Object.keys(buyAmounts).length) body.buyAmounts = buyAmounts;
+        return patch("/api/wallet/trading-policy", body);
+      })
+    });
     api.registerTool({
       name: "risk_management_set_default",
       description: "Save per-wallet default exit parameters (`tpExits`, `slExits`, `trailingStop.levels`) applied on buys that omit risk fields. Same shape as trade execute exit payloads.",
@@ -2471,9 +2519,11 @@ ${notes}
         })
       )
     });
+    const bitqueryLifetimeState = getOrCreateBitqueryLifetimeState();
     const bitqueryStreamManager = new BitqueryStreamManager({
       wsUrl: orchestratorUrl.replace(/^http/, "ws").replace(/\/$/, "") + "/ws",
       walletId,
+      lifetimeState: bitqueryLifetimeState,
       getAccessToken: () => sessionManager.getAccessToken(),
       logger: {
         info: (msg) => api.logger.info(`[solana-trader] ${msg}`),
@@ -2482,10 +2532,16 @@ ${notes}
       }
     });
     __solanaTraderDisposers.push(() => {
-      try {
-        bitqueryStreamManager.close();
-      } catch {
-      }
+      void (async () => {
+        try {
+          await bitqueryStreamManager.unsubscribeAll();
+        } catch {
+        }
+        try {
+          bitqueryStreamManager.close();
+        } catch {
+        }
+      })();
     });
     api.registerTool({
       name: "solana_bitquery_subscribe",
@@ -3032,18 +3088,30 @@ ${notes}
     });
     api.registerTool({
       name: "solana_runtime_status",
-      description: "Return plugin runtime diagnostics including startup-gate cache, alpha stream status, and latest forwarding probe result.",
+      description: "Return plugin runtime diagnostics: startup-gate cache, alpha stream (lifetime stats vs current socket), Bitquery mux (lifetime connect count, websocket/auth flags, tracked subscription IDs + mint tokens vs orchestrator diagnostics from solana_bitquery_subscriptions), and latest forwarding probe result. Use subscription_cleanup cron baseline.",
       parameters: Type.Object({}),
-      execute: wrapExecute("solana_runtime_status", async () => ({
-        startupGate: startupGateState,
-        alphaStream: {
-          subscribed: alphaStreamManager.isSubscribed(),
-          ingestionStale: alphaStreamManager.isIngestionStale(),
-          stats: alphaStreamManager.getStats(),
-          bufferSize: alphaBuffer.getBufferSize()
-        },
-        lastForwardProbe: lastForwardProbeState
-      }))
+      execute: wrapExecute("solana_runtime_status", async () => {
+        const bitqueryStats = bitqueryStreamManager.getStats();
+        const wsOpen = bitqueryStreamManager.isWebsocketOpen();
+        return {
+          startupGate: startupGateState,
+          alphaStream: {
+            subscribed: alphaStreamManager.isSubscribed(),
+            ingestionStale: alphaStreamManager.isIngestionStale(),
+            stats: alphaStreamManager.getStats(),
+            bufferSize: alphaBuffer.getBufferSize()
+          },
+          bitqueryStream: {
+            stats: bitqueryStats,
+            connected: wsOpen && bitqueryStats.authenticated,
+            websocketOpen: wsOpen,
+            activeSubscriptionCount: bitqueryStats.activeSubscriptionCount,
+            activeSubscriptionIds: bitqueryStreamManager.getActiveSubscriptionIds(),
+            activeTokens: bitqueryStreamManager.getActiveTokens()
+          },
+          lastForwardProbe: lastForwardProbeState
+        };
+      })
     });
     api.registerTool({
       name: "solana_state_save",

package/dist/src/bitquery-ws.js

@@ -1,6 +1,6 @@
 import {
   BitqueryStreamManager
-} from "../chunk-S2DLZKMQ.js";
+} from "../chunk-QIURFAOS.js";
 export {
   BitqueryStreamManager
 };

package/openclaw.plugin.json

@@ -252,6 +252,8 @@
       "x_search_tweets",
       "risk_management_get_default",
       "risk_management_set_default",
+      "buy_amount_policy_get",
+      "buy_amount_policy_set",
       "trade_size_limit_get",
       "trade_size_limit_set",
       "position_risk_management_update"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solana-traderclaw",
-  "version": "1.0.147",
+  "version": "1.0.148",
   "description": "TraderClaw V1-Upgraded — Solana trading for OpenClaw with intelligence lab, tool envelopes, prompt scrubbing, read-only X social intel, and split skill docs",
   "type": "module",
   "main": "./dist/index.js",

package/skills/solana-trader/SKILL.md

@@ -75,12 +75,22 @@ Configured by the user on the **Buy Strategy** page. Checks token metrics before
 
 **Agent impact:** When `hard`, if you try to buy a token outside user bounds, the orchestrator returns a denial. Do not retry with the same token. Report the bound that was exceeded.
 
-### Soft-Enforced Limits (size reduction, not denial)
+### Buy Amount Policy (`buyAmountEnforcement`)
+
+Configured on the **Buy Strategy** page (SOL sizing). This is separate from **buy filters** (market cap, liquidity, etc.).
 
-Some limits adjust position size rather than deny outright:
+| Mode | Behavior |
+|---|---|
+| `off` | No discretionary buy-amount policy. **Exception:** if the user previously set only legacy `maxTradeSizeSol` / `trade_size_limit_set` with no `buyAmounts` keys, the orchestrator still clamps buys to that maximum. |
+| `soft` | Buy runs at your requested `sizeSol`, but precheck/execute include **warnings** in `metadata.reasons` when fixed/min/max bounds are violated. |
+| `hard` | Buy **size is clamped** to the configured fixed SOL amount, or bounded by min/max SOL. Trades are **not** denied for sizing alone. Precheck returns `metadata.cappedSizeSol`; when it changed, `metadata.buyAmountAdjusted` is true and execute may include `policySizing`. |
+
+**Tools:** `buy_amount_policy_get`, `buy_amount_policy_set`, and `trade_size_limit_get` / `trade_size_limit_set` (max SOL, mirrored into `buyAmounts`).
+
+### Soft-Enforced Limits (size reduction, not denial)
 
-- **Top-10 holder concentration** (`maxTop10ConcentrationPct` in buy filters, if `soft`): When the top 10 wallets own too high a percentage, the orchestrator halves the proposed buy size.
-- **Max position USD** (`maxPositionUsd`): Orchestrator caps buy size to this limit silently if your proposed size exceeds it.
+- **Buy amount `hard` mode** and **legacy max trade size** clamp executed buy size. Treat precheck `metadata.cappedSizeSol` as authoritative when present; align execute `sizeSol` with that value to avoid policy drift.
+- Older notes about automatic halving from top-10 concentration or silent `maxPositionUsd` caps may not match every response — **always trust `solana_trade_precheck` metadata** over static tables.
 
 ### Risk Exit Enforcement (`riskEnforcement`)
 
@@ -719,3 +729,4 @@ All decision making, evaluation, and learning MUST use SOL-based values.
 | `bitquery-schema.md` | Bitquery v2 EAP schema reference |
 | `query-catalog.md` | Bitquery query template catalog |
 | `websocket-streaming.md` | WebSocket message contract and subscription lifecycle |
+| `refs/ws-subscription-health.md` | Cron + mux health, 20-cap, leaked-socket escalation |

package/skills/solana-trader/refs/cron-jobs.md

@@ -95,13 +95,22 @@ At start of every cron job, check whether sufficient new data exists since last
 
 ## Job: `subscription_cleanup`
 
-**Schedule:** Every 8 hours, offset by 15 min (`15 */8 * * *`) — 3 runs/day
+**Schedule:** Every 2 hours, offset by 15 min (`15 */2 * * *`) — ~12 runs/day
 
-**Purpose:** Manage Bitquery subscription lifecycle — remove orphaned subscriptions, reopen expiring ones.
+**Purpose:** Keep Bitquery subscription count healthy — remove orphaned subscriptions, reopen expiring streams, reconcile against **open positions**, and guard the **under-20 logical subscription cap** per client. Helps avoid `WS_SUBSCRIPTION_LIMIT_REACHED`; **never** unsubscribes alpha.
 
-**Tools:** `solana_positions`, `solana_bitquery_subscriptions`, `solana_bitquery_unsubscribe`, `solana_bitquery_subscription_reopen`, `solana_memory_write`
+**Tools:** `solana_runtime_status`, `solana_positions`, `solana_bitquery_subscriptions`, `solana_bitquery_subscribe`, `solana_bitquery_unsubscribe`, `solana_bitquery_subscription_reopen`, `solana_memory_write`
 
-**Workflow:** List open position CAs → list active subs (if AUTH_SCOPE_MISSING, log and stop) → match subs to positions → unsubscribe orphans → write tag 'subscription_cleanup'.
+**Workflow:**
+1. `solana_runtime_status` → local alpha + Bitquery mux snapshot (`bitqueryStream`).
+2. `solana_positions` → open mint addresses.
+3. `solana_bitquery_subscriptions` → orchestrator diagnostics (subscriber counts / connected websocket clients — field names mirror API response).
+4. Unsubscribe mismatched streams → subscribe missing `realtimeTokenPricesSolana` with **`agentId` matching the cron job's agent**.
+5. `solana_bitquery_subscription_reopen` for subs nearing TTL.
+6. If limits persist (`WS_PER_KEY_LIMIT`, stalled counts, absurd client fan-out) log **CRITICAL** via `solana_memory_write` — leaked TCP sockets may require a **manual gateway restart** (outside agent tools).
+7. Memory tag **`subscription_cleanup`** with before / after telemetry.
+
+See also: `refs/ws-subscription-health.md`.
 
 **Configuration:**
 - Model: Haiku (mechanical — match subs to positions, unsubscribe orphans)
@@ -209,9 +218,9 @@ At start of every cron job, check whether sufficient new data exists since last
 | 2 | `trust-refresh` | `0 */8 * * *` | 3 | Haiku | off | on | none |
 | 3 | `meta-rotation` | `30 */8 * * *` | 3 | Sonnet | off | on | announce/last |
 | 4 | `strategy-evolution` | `0 6 * * *` | 1 | Sonnet | **on** | **off** | announce/last |
-| 5 | `subscription-cleanup` | `15 */8 * * *` | 3 | Haiku | off | on | announce/last |
+| 5 | `subscription-cleanup` | `15 */2 * * *` | ~12 | Haiku | off | on | announce/last |
 | 6 | `daily-performance-report` | `0 4 * * *` | 1 | Sonnet | off | **off** | announce/telegram |
 | 7 | `intelligence-lab-eval` | `0 16 * * *` | 1 | Sonnet | **on** | **off** | none |
 | 8 | `memory-trim` | `0 3 * * *` | 1 | Haiku | off | on | none |
 | 9 | `balance-watchdog` | `0 */2 * * *` | 12 | Haiku | off | on | announce/telegram |
-| | **Total** | | **31** | | | | |
+| | **Total** | | **40** | | | | |

package/skills/solana-trader/refs/trade-execution.md

@@ -5,8 +5,8 @@
 Call `solana_trade_precheck` with your intended trade parameters.
 
 - **If `approved: false` with hard denials:** STOP. Do not trade. Journal the denial reason.
-- **If approved with soft flags:** Reduce size to `cappedSizeSol`. Consider SERVER_MANAGED. Tighten stops.
-- **If approved cleanly:** Proceed to execute.
+- **If approved with clamps or sizing notes:** When precheck sets `metadata.cappedSizeSol`, use it as the executed buy size for the matching `trade_execute`. If `metadata.buyAmountAdjusted` is true (or execute returns `policySizing`), the orchestrator changed your requested `sizeSol` (buy-amount policy **hard** mode or legacy max). For buy-amount **soft** mode, you may keep your requested size but review `metadata.reasons`.
+- **If approved cleanly:** Proceed to execute with the intended size (still reconcile with `cappedSizeSol` when the server provides one).
 
 **Non-negotiable:** Never override hard denials. Never argue with the policy engine.
 

package/skills/solana-trader/refs/ws-subscription-health.md

@@ -0,0 +1,40 @@
+# WebSocket + subscription health
+
+Use this alongside `websocket-streaming.md` when diagnosing Bitquery churn, orphaned subscriptions, or `WS_PER_KEY_LIMIT` / subscription-cap errors.
+
+## Two connection types
+
+1. **Alpha stream** — one WebSocket carrying buffered `alpha_signal` traffic. Managed by `solana_alpha_subscribe`; the plugin watchdog reconnects automatically. Cron and subscription cleanup **must never** call `solana_alpha_unsubscribe` unless deliberately shutting alpha down.
+
+2. **Bitquery mux** — one WebSocket from the gateway plugin carries many **logical subscriptions** (`bitquery_subscribe` / `bitquery_unsubscribe`). The orchestrator multiplexes upstream Bitquery streams. Steady state is typically **one** plugin Bitquery client + **one** alpha client (**~2 TCP connections**) to TraderClaw, not one socket per mint.
+
+## Health signals
+
+**Good**
+
+- Orchestrator diagnostics (`solana_bitquery_subscriptions`): Bitquery subscriber counts aligned with **open positions** (usually one `realtimeTokenPricesSolana` per mint you hold).
+- Active Bitquery subscriptions **below 20** per client (`OPENCLAW_WS_MAX_SUBS_PER_CLIENT` default — see `websocket-streaming.md`).
+- Plugin `solana_runtime_status.bitqueryStream` matches intuition: sane `activeSubscriptionCount`, tokens match `solana_positions` mints.
+
+**Bad**
+
+- Subscriptions still listed for mints **without** an open position (heartbeat Step 7 missed or failed).
+- `activeSubscriptionCount` **at or above 20**, or subscribe errors **`WS_SUBSCRIPTION_LIMIT_REACHED`**.
+- **`WS_PER_KEY_LIMIT`** or very high **TCP** connection counts to `api.traderclaw.ai` (**25** API-key ceiling) despite few logical subs — indicates **orphan TCP / leaked clients** across plugin lifecycle. Unsubscribe tools alone cannot always drop leaked sockets.
+
+## What `subscription_cleanup` does
+
+Scheduled job **`subscription_cleanup`** (OpenClaw cron store, id `subscription-cleanup`):
+
+- Baseline via `solana_runtime_status`, `solana_positions`, `solana_bitquery_subscriptions`.
+- Unsubscribe Bitquery subscriptions whose token is **not** in open positions (`solana_bitquery_unsubscribe`).
+- Subscribe **`realtimeTokenPricesSolana`** for any open CA missing coverage; pass **`agentId` matching your trading agent** (job agent id — `main` on V1 installs).
+- Reopen nearing-expiry subscriptions (`solana_bitquery_subscription_reopen`).
+- Writes memory tag **`subscription_cleanup`** with before/after metrics.
+
+Escalate with **CRITICAL** in memory when limits persist after reconcile; **restart the gateway** is the corrective action for leaked TLS sockets (`systemctl --user restart openclaw-gateway`).
+
+## Operational rule of thumb
+
+- **Logical Bitquery subscriptions** should mirror **open positions** (typically one price stream per held mint). Keep count **below 20** (`OPENCLAW_WS_MAX_SUBS_PER_CLIENT`).
+- **Outbound TLS sessions** from the gateway toward TraderClaw should stay near **two** — one mux for Bitquery, one for Alpha — unless you know you intentionally run multiple clients.

package/skills/solana-trader/workspace/TOOLS.md

@@ -27,7 +27,7 @@ Every tool has a mandatory trigger — when the trigger condition is met, you MU
 | `solana_gateway_credentials_set` | Register gateway URL and token | When gateway is not registered (startup) |
 | `solana_gateway_forward_probe` | Test forwarding path health | Startup sequence; when events stop arriving |
 
-### Wallet & Capital (11)
+### Wallet & Capital (13)
 | Tool | Purpose | When to Call |
 |---|---|---|
 | `solana_wallets` | List all wallets | Startup; when user asks about wallets |
@@ -39,8 +39,10 @@ Every tool has a mandatory trigger — when the trigger condition is met, you MU
 | `solana_killswitch_status` | Check kill switch state | Step 0 every heartbeat |
 | `risk_management_get_default` | Read per-wallet default TP/SL/trailing used when buys omit risk | Before relying on implicit defaults; after user asks about protection |
 | `risk_management_set_default` | Save per-wallet default exit plan for future buys | When user or policy wants custom defaults instead of platform system default |
-| `trade_size_limit_get` | Read max **buy** size (SOL) from wallet `limits` (default 1.5) | Before every buy or when user asks about size limits |
-| `trade_size_limit_set` | Set max **buy** size (SOL) on wallet `limits` | When user asks to change the per-order cap |
+| `trade_size_limit_get` | Read effective max **buy** size (SOL); merges legacy max with `buyAmounts.max` | Before every buy or when user asks about size limits |
+| `trade_size_limit_set` | Set max buy SOL (also mirrors into buy-amount max + hard enforcement when off) | When user asks to change the per-order cap |
+| `buy_amount_policy_get` | Read `buyAmountEnforcement` and fixed/min/max buy SOL | Before sizing when user may clamp or warn on amount |
+| `buy_amount_policy_set` | Update buy amount policy (off/soft/hard + bounds) | When user configures buy sizing on the Buy Strategy card |
 | `position_risk_management_update` | Adjust TP/SL/trailing **numbers** on an open position (same level count) | After entry when refining exits without removing levels |
 
 ### Scanning & Discovery (4)
@@ -120,9 +122,9 @@ Every tool has a mandatory trigger — when the trigger condition is met, you MU
 | `solana_bitquery_catalog` | Run pre-built template | Step 2: MANDATORY for FRESH tokens (first100Buyers, devHoldings); Step 2: website metadata check for tokens >0.60 |
 | `solana_bitquery_query` | Run custom raw GraphQL | When no catalog template fits your query need |
 | `solana_bitquery_subscribe` | Subscribe to real-time stream | Step 5: after every successful buy (realtimeTokenPricesSolana); startup for discovery streams |
-| `solana_bitquery_unsubscribe` | Unsubscribe from stream | Step 7: after every exit; `subscription_cleanup` cron for orphaned subscriptions |
-| `solana_bitquery_subscriptions` | List active subscriptions | Step 1: check for buffered events; `subscription_cleanup` cron |
-| `solana_bitquery_subscription_reopen` | Renew expiring subscription | `subscription_cleanup` cron for subscriptions nearing 24h expiry |
+| `solana_bitquery_unsubscribe` | Unsubscribe from stream | Step 7: after every exit; `subscription_cleanup` cron (`refs/ws-subscription-health.md`) |
+| `solana_bitquery_subscriptions` | List active subscriptions | Step 1: check for buffered events; `subscription_cleanup` cron diagnostics |
+| `solana_bitquery_subscription_reopen` | Renew expiring subscription | `subscription_cleanup` cron (24h TTL) |
 
 ### Memory & State (13)
 | Tool | Purpose | When to Call |
@@ -191,7 +193,7 @@ Every tool has a mandatory trigger — when the trigger condition is met, you MU
 ### Runtime (3)
 | Tool | Purpose | When to Call |
 |---|---|---|
-| `solana_runtime_status` | Plugin runtime health | Diagnostics; when tools behave unexpectedly |
+| `solana_runtime_status` | Plugin runtime health (alpha + Bitquery mux) | Diagnostics; `subscription_cleanup` cron baseline (`refs/ws-subscription-health.md`) |
 | `solana_agent_sessions` | List agent sessions | Diagnostics; when checking session state |
 | `solana_classify_deployer_risk` | Deployer risk (alias) | Same as `solana_compute_deployer_risk` — use either |