solana-traderclaw 1.0.146 → 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";
@@ -48,6 +48,7 @@ import { Type } from "@sinclair/typebox";
 import kayba, { SpanType } from "@kayba_ai/tracing";
 import * as fs from "fs";
 import * as path from "path";
+import { fileURLToPath } from "node:url";
 import { homedir } from "os";
 
 // lib/x-client.mjs
@@ -783,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];
@@ -802,6 +806,23 @@ 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);
+    const packageRoot = path.dirname(path.dirname(distPath));
+    const mdPath = path.join(packageRoot, "lib", "status-queries.md");
+    return fs.readFileSync(mdPath, "utf-8");
+  } catch {
+    return void 0;
+  }
+})();
 function __solanaTraderDisposePreviousLifecycle(logger) {
   const prev = __solanaTraderGlobalSingletonHolder[SOLANA_TRADER_LIFECYCLE_SINGLETON_KEY];
   if (!prev) return;
@@ -2053,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",
@@ -2062,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 })
       }),
@@ -2074,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.",
@@ -2460,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}`),
@@ -2471,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",
@@ -3021,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",
@@ -4298,6 +4377,14 @@ ${String(params.summary)}
           content: "# Live alpha status queries \u2014 always call the tool\n\nWhen the user asks anything about CURRENT alpha activity, call the matching tool **on this turn**. Do NOT answer from memory, heartbeat history, journal logs, or earlier turn context \u2014 alpha signals are not journalled per-message, so 'I don't see any / 0' is wrong by default.\n\n## Routing\n\n| User question shape | Tool(s) to call | Key fields in response |\n|---|---|---|\n| how many alpha signals / are we getting alpha / activity since gateway start | `solana_alpha_signals` (unseen:false) | stats.messageCount, stats.lifetimeUptimeSeconds, stats.lastEventTs, subscribed, bufferSize |\n| is alpha connected / healthy / stream status | `solana_alpha_signals` (unseen:false) | subscribed, stats.reconnectAttempt, stats.unhealthyStreak, stats.circuitBackoff, stats.lastEventTs |\n| how many alpha signals in last hour / today / this week / since <day> | `solana_alpha_signals` (live state) **AND** `solana_alpha_history` (days=\u2026 or compute from window) | live: stats.messageCount + bufferSize; historical: pings[] in window |\n| any alpha on token <X> (recent / historical) | `solana_alpha_signals` for in-buffer signals, then `solana_alpha_history` (tokenAddress=X, days=N) for older | both responses merged by ts |\n| what alpha sources / channels are active | `solana_alpha_sources` | sources[] (name, type, count, avgScore) |\n| latest signals / new signals | `solana_alpha_signals` (unseen:false) | signals[] sorted newest last |\n\n## Field meanings \u2014 IMPORTANT\n\n`solana_alpha_signals` returns `stats` with both lifetime and current-WS fields. Use LIFETIME fields for user-facing answers:\n\n- `stats.messageCount` = **lifetime** total alpha_signal messages received since the gateway process started. Survives plugin re-registers and WS reconnects. **This is the headline number.**\n- `stats.lifetimeUptimeSeconds` = seconds since the first WS open in this process.\n- `stats.lastEventTs` = wall-clock ms of the most recent signal (lifetime).\n- `stats.firstConnectedAt` = wall-clock ms of the first WS open in this process.\n\nDebug-only (do NOT report these as 'totals' \u2014 they reset on every WS reconnect / plugin re-register):\n\n- `stats.currentWsMessageCount` \u2014 messages since the current WS opened.\n- `stats.uptimeSeconds` \u2014 current WS uptime.\n- `stats.connectedAt` \u2014 current WS open ts.\n\n## When to also call `solana_alpha_history`\n\nCall `solana_alpha_history` in addition to `solana_alpha_signals` whenever the user's window pre-dates the current gateway-process lifetime (e.g. `stats.lifetimeUptimeSeconds` is shorter than the asked window, or `stats.messageCount` is 0 because the gateway just restarted). Tier=enterprise returns up to 200 pings, up to ~1 year back.\n\n## Reply template (live-only)\n\n```\nLive alpha state:\n- subscribed: <bool>\n- lifetime: <messageCount> messages over <lifetimeUptimeSeconds>s (\u2248 <rate>/min) since gateway start\n- last signal: <Xs/Xm ago> (lastEventTs)\n- buffer (deduped): <bufferSize>\n- reconnects: <reconnectAttempt>, unhealthy streak: <unhealthyStreak>\n```\n\n## Reply template (with historical window, e.g. 'last hour')\n\n```\nAlpha activity (<window>):\n- live (gateway lifetime): <messageCount> messages over <lifetimeUptimeSeconds>s\n- historical (`solana_alpha_history` days=<N>): <pings.length> pings\n- combined unique within <window>: <merged count>\n- subscribed: <bool>, last signal: <ago>\n```\n\nThis routing overrides any heartbeat-cycle 'minimal calls' cap: ad-hoc user status questions are NOT subject to per-cycle envelopes.\n",
           source: "solana-trader:live-queries"
         });
+        if (__solanaTraderStatusQueriesMd) {
+          context.bootstrapFiles.push({
+            name: "STATUS_QUERIES.md",
+            path: "STATUS_QUERIES.md",
+            content: __solanaTraderStatusQueriesMd,
+            source: "solana-trader:status-queries"
+          });
+        }
         api.logger.info(`[solana-trader] Bootstrap: injected ${context.bootstrapFiles.length} files for agent ${bootAgentId}`);
       },
       {

package/dist/src/bitquery-ws.js

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

package/lib/status-queries.md

@@ -0,0 +1,103 @@
+# Live status queries — always call the tool, never answer from memory
+
+When the user asks any question about **current alpha stream state**, you MUST call the matching plugin tool **on this turn**, then summarize what the tool returned. Do NOT answer from memory, heartbeat history, journal logs, log snippets, or earlier conversation context: alpha counts grow second-by-second and stale answers (especially "none" / "zero") are wrong by default.
+
+## Why this rule exists
+
+The plugin does NOT log every received alpha signal to the journal (that would be noisy at sustained throughput). Signal counts and the buffer of recent signals live **only inside the running plugin process** and are exposed via these tools. If you don't call the tool, you have no data — you only have the absence of log lines, which is not the same thing.
+
+The heartbeat history (`memory/<date>.md`, `MEMORY.md`) only captures signals the agent **personally evaluated** during a heartbeat cycle. It is NOT a record of what the WebSocket received. Using heartbeat history to answer "how many signals" gives a count that is typically much smaller than the real number (because most signals never reach a cycle where the agent processes them).
+
+## Alpha question → tool routing
+
+When the user's question matches a row in column 1, call the tool(s) in column 2 (always on this turn, before replying), read the response, and answer from that data.
+
+| User question (or similar) | Call this tool | What to report back |
+|---|---|---|
+| "how many alpha signals have we gotten?" / "are we getting alpha?" / "anything from alpha lately?" | `solana_alpha_signals` (with `unseen: false`) | `stats.messageCount` (LIFETIME — survives re-registers/reconnects), `stats.lifetimeUptimeSeconds`, `stats.lastEventTs`, `subscribed`, `bufferSize` |
+| "what's the alpha stream doing right now?" / "is alpha connected?" / "alpha health?" | `solana_alpha_signals` (with `unseen: false`) | `subscribed`, `stats.reconnectAttempt`, `stats.unhealthyStreak`, `stats.circuitBackoff`, `stats.lastEventTs` (interpret as "Xs ago") |
+| "how many alpha signals in the last hour / today / this week / since Monday?" | `solana_alpha_signals` (live) **AND** `solana_alpha_history` (`days=` covering the window) | Live: `stats.messageCount` since gateway start + signals in `signals[]` within the window. Historical: pings in window from REST. Report both. |
+| "any alpha on `<token>` recently / in the last 24h?" | `solana_alpha_signals` (filter `signals[]` by `tokenAddress`/`tokenSymbol`) **AND** `solana_alpha_history` (`tokenAddress=<addr>&days=N`) | Merge live + historical signals for that token by timestamp. |
+| "what alpha sources are active?" / "which channels are sending signals?" | `solana_alpha_sources` | `sources` array — name, type, count, avgScore per channel |
+| "show me the latest alpha signals" / "new signals?" | `solana_alpha_signals` (with `unseen: false` for full buffer, `unseen: true` only if you intend to consume) | Up to N signals: token, source, kind, signalStage, marketCap, systemScore, ts |
+
+## `stats` fields — what to use vs. what to ignore
+
+`solana_alpha_signals` returns a `stats` object with both **lifetime** and **per-current-WS** fields. **Always quote the lifetime fields to the user.**
+
+USE these for user-facing answers (stable across plugin re-registers and WS reconnects):
+
+- `stats.messageCount` — **lifetime** total alpha_signal messages received since the gateway process started.
+- `stats.lifetimeUptimeSeconds` — seconds since the first WebSocket open in this gateway process.
+- `stats.lastEventTs` — wall-clock ms of the most recent signal (lifetime).
+- `stats.firstConnectedAt` — wall-clock ms of the first WS open in this process.
+
+DO NOT use as "totals" (they reset on every WS reconnect / plugin re-register, which happens every agent turn — so the numbers are misleading as standalone answers):
+
+- `stats.currentWsMessageCount` — messages since the CURRENT WS opened. Useful only for debugging "why is the WS cycling?".
+- `stats.uptimeSeconds` — current WS uptime.
+- `stats.connectedAt` — current WS open ts.
+
+## When to also call `solana_alpha_history`
+
+The live tool gives you "messages since this gateway process started" and a buffer of ~200 deduped signals. For windows that exceed those:
+
+- The asked window predates `stats.firstConnectedAt` (e.g. user asks "last 24h" but gateway started 2h ago).
+- The user asks about a specific date or named window ("yesterday", "since Monday", "last week").
+- The buffer is empty (e.g. just after a gateway restart) but the user is asking about a real time range.
+
+…ALSO call `solana_alpha_history` (`days=N` covering the window) and combine the two responses. Tier=enterprise → up to 200 results back ~1 year.
+
+## How to answer (template — live-only)
+
+After the tool returns, structure your reply like this so the user can verify you queried live data:
+
+```
+Live alpha state (as of <now>):
+- subscribed: <subscribed>
+- lifetime: <stats.messageCount> messages over <stats.lifetimeUptimeSeconds>s (≈ <rate>/min) since gateway start
+- last signal: <stats.lastEventTs as "Xs/Xm ago">
+- buffer (deduped, ≤200): <bufferSize>
+- reconnects: <stats.reconnectAttempt>, unhealthy streak: <stats.unhealthyStreak>
+
+Top sources (from `solana_alpha_sources`):
+- <sourceName> (<sourceType>): <count> signals, avg score <avgScore>
+
+Sample of latest signals (newest first):
+- <tokenSymbol> (<tokenName>) — <kind>/<signalStage>, MC $<marketCap>, score <systemScore>, from <sourceName>, <ts ago>
+```
+
+## How to answer (template — when window > gateway lifetime)
+
+```
+Alpha activity (<window>):
+- live (gateway lifetime, <lifetimeUptimeSeconds>s): <messageCount> messages, currently <bufferSize> in buffer
+- historical (`solana_alpha_history` days=<N>): <pings.length> pings in window
+- combined unique: <merged count>
+- subscribed: <bool>, last signal: <ago>
+
+Top historical sources / tokens: …
+```
+
+## Common mistakes to avoid
+
+- **Don't answer "zero" or "none" without calling the tool.** "I don't see any in the logs / heartbeat history" is wrong — signals are NOT logged per-message and heartbeat history only captures what the agent itself touched.
+- **Don't reuse a count from earlier in the conversation.** The buffer is continuously updated; quote only freshly-fetched numbers.
+- **Don't quote `currentWsMessageCount` or `uptimeSeconds` as "totals".** Those reset every time you (or anyone) interacts with the agent, because each interaction re-registers the plugin. Always use `stats.messageCount` and `stats.lifetimeUptimeSeconds` for user-facing answers.
+- **Don't mix heartbeat history with live tool data without flagging it.** If the user asks "how many in the last hour" and you can only see live state, say so and call `solana_alpha_history` to fill the window.
+- **Don't claim "the stream is offline" from log gaps alone.** Check `subscribed` and `stats.lastEventTs` — a stream can be healthy with low-traffic minutes.
+- **Don't paste raw JSON to the user.** Summarize per the templates above; offer raw JSON only if asked.
+
+## When the user does NOT need a tool call
+
+These are NOT live-state queries; answer from your knowledge:
+
+- "how does the alpha stream work?" (explain the design from `skills/solana-trader/refs/alpha-signals.md` if available)
+- "what's a `ca_drop`?" (definition)
+- "which alpha sources are premium?" (static info from refs)
+
+## Related
+
+- `HEARTBEAT.md` — per-heartbeat cycle envelope (separate from ad-hoc Q&A).
+- `skills/solana-trader/refs/alpha-signals.md` — full alpha pipeline reference.
+- Tool catalog: `solana_alpha_subscribe`, `solana_alpha_unsubscribe`, `solana_alpha_signals`, `solana_alpha_sources`, `solana_alpha_history`.

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.146",
+  "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/AGENTS.md

@@ -127,3 +127,21 @@ These are permanent directives. They apply every session, every cycle, without e
 4. **Always check kill switch before new entries.** Call `solana_killswitch_status()` before any new trade execution. If active, halt immediately — no exceptions, no overrides.
 
 5. **Always report every cycle.** Never run a silent heartbeat. Every cycle produces a report: what you scanned, what you found, what you did, what you skipped and why. Crypto is 24/7. Every cycle reports.
+
+## Live status questions → ALWAYS call the tool
+
+When the user asks about the **current** state of the alpha stream (counts, sources, recent signals, subscription health, or any time window), you MUST call the matching plugin tool **on the same turn** before replying. Do not answer "zero / none / I don't see anything" from memory, heartbeat history, journal logs, or log impressions — signals are not logged per-message; they live only inside the running plugin (live state) and the orchestrator REST (historical) and are surfaced via tools.
+
+See `STATUS_QUERIES.md` (auto-injected by the plugin at every register) for the full question → tool routing table, field semantics (lifetime vs. current-WS), and the standard answer template. The short version:
+
+| Question shape | Tool(s) to call |
+|---|---|
+| "how many alpha signals / are we getting alpha?" | `solana_alpha_signals` (`unseen: false`) — quote `stats.messageCount` (LIFETIME, survives re-registers) and `stats.lifetimeUptimeSeconds` |
+| "is alpha connected / healthy?" | `solana_alpha_signals` (`unseen: false`) — read `subscribed`, `stats.lastEventTs`, `stats.reconnectAttempt`, `stats.unhealthyStreak`, `stats.circuitBackoff` |
+| "how many in last hour / today / since `<day>`?" / "any alpha on `<token>` in 24h?" | `solana_alpha_signals` (live) **AND** `solana_alpha_history` (`days=N` covering the window, `tokenAddress=` when filtering) |
+| "which alpha sources / channels?" | `solana_alpha_sources` |
+| "latest / new alpha signals?" | `solana_alpha_signals` (with or without `unseen: true` depending on intent) |
+
+Field reminder: use `stats.messageCount` and `stats.lifetimeUptimeSeconds` as the headline numbers. Do NOT quote `stats.currentWsMessageCount` or `stats.uptimeSeconds` as "totals" — they reset on every plugin re-register (every agent turn / Telegram message).
+
+This rule applies to all sessions — direct chats, Telegram, anywhere the user asks. It overrides the heartbeat-cycle envelope: ad-hoc live-state questions are NOT subject to the "minimal per-cycle calls" cap.

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 |