solana-traderclaw 1.0.145 → 1.0.147

package/dist/{chunk-ZUY36F4Q.js → chunk-GX4HA22L.js}

@@ -141,12 +141,19 @@ var AlphaStreamManager = class {
     return this.subscribed && this.ws !== null && this.ws.readyState === 1;
   }
   getStats() {
+    const ls = this.config.lifetimeState;
+    const lifetimeMessageCount = ls ? ls.lifetimeMessageCount : this.messageCount;
+    const firstConnectedAt = ls && ls.firstConnectedAt > 0 ? ls.firstConnectedAt : this.connectedAt;
+    const lifetimeLastEventTs = ls && ls.lifetimeLastEventTs > 0 ? ls.lifetimeLastEventTs : this.lastEventTs;
     return {
       subscribed: this.isSubscribed(),
-      messageCount: this.messageCount,
-      lastEventTs: this.lastEventTs,
+      messageCount: lifetimeMessageCount,
+      currentWsMessageCount: this.messageCount,
+      lastEventTs: lifetimeLastEventTs,
       connectedAt: this.connectedAt,
+      firstConnectedAt,
       uptimeSeconds: this.connectedAt ? Math.floor((Date.now() - this.connectedAt) / 1e3) : 0,
+      lifetimeUptimeSeconds: firstConnectedAt ? Math.floor((Date.now() - firstConnectedAt) / 1e3) : 0,
       reconnectAttempt: this.reconnectAttempt,
       unhealthyStreak: this.unhealthyStreak,
       circuitBackoff: this.unhealthyStreak >= CIRCUIT_UNHEALTHY_THRESHOLD
@@ -200,6 +207,9 @@ var AlphaStreamManager = class {
       this.ws.on("open", () => {
         clearTimeout(connectTimeout);
         this.connectedAt = Date.now();
+        if (this.config.lifetimeState && this.config.lifetimeState.firstConnectedAt === 0) {
+          this.config.lifetimeState.firstConnectedAt = this.connectedAt;
+        }
         this.reconnectAttempt = 0;
         this.log("info", "WebSocket connected, waiting for server handshake...");
         pingInterval = setInterval(() => {
@@ -286,6 +296,10 @@ var AlphaStreamManager = class {
       case "alpha_signal": {
         this.messageCount++;
         this.lastEventTs = Date.now();
+        if (this.config.lifetimeState) {
+          this.config.lifetimeState.lifetimeMessageCount++;
+          this.config.lifetimeState.lifetimeLastEventTs = this.lastEventTs;
+        }
         const data = msg.data;
         if (data) {
           const signal = {

package/dist/index.js

@@ -19,7 +19,7 @@ import {
 } from "./chunk-3UQIQJPQ.js";
 import {
   AlphaStreamManager
-} from "./chunk-ZUY36F4Q.js";
+} from "./chunk-GX4HA22L.js";
 import {
   BitqueryStreamManager
 } from "./chunk-S2DLZKMQ.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
@@ -777,6 +778,41 @@ var SOLANA_TRADER_LIFECYCLE_SINGLETON_KEY = Symbol.for(
   "openclaw.solana-trader.lifecycle.v1"
 );
 var __solanaTraderGlobalSingletonHolder = globalThis;
+var SOLANA_TRADER_ALPHA_BUFFER_SINGLETON_KEY = Symbol.for(
+  "openclaw.solana-trader.alpha-buffer.v1"
+);
+var SOLANA_TRADER_ALPHA_LIFETIME_SINGLETON_KEY = Symbol.for(
+  "openclaw.solana-trader.alpha-lifetime.v1"
+);
+var __solanaTraderAlphaSingletonHolder = globalThis;
+function getOrCreateAlphaBuffer() {
+  const existing = __solanaTraderAlphaSingletonHolder[SOLANA_TRADER_ALPHA_BUFFER_SINGLETON_KEY];
+  if (existing) return existing;
+  const fresh = new AlphaBuffer();
+  __solanaTraderAlphaSingletonHolder[SOLANA_TRADER_ALPHA_BUFFER_SINGLETON_KEY] = fresh;
+  return fresh;
+}
+function getOrCreateAlphaLifetimeState() {
+  const existing = __solanaTraderAlphaSingletonHolder[SOLANA_TRADER_ALPHA_LIFETIME_SINGLETON_KEY];
+  if (existing) return existing;
+  const fresh = {
+    lifetimeMessageCount: 0,
+    firstConnectedAt: 0,
+    lifetimeLastEventTs: 0
+  };
+  __solanaTraderAlphaSingletonHolder[SOLANA_TRADER_ALPHA_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;
@@ -2572,11 +2608,13 @@ ${notes}
         async () => get("/api/agents/active")
       )
     });
-    const alphaBuffer = new AlphaBuffer();
+    const alphaBuffer = getOrCreateAlphaBuffer();
+    const alphaLifetimeState = getOrCreateAlphaLifetimeState();
     const alphaStreamManager = new AlphaStreamManager({
       wsUrl: orchestratorUrl.replace(/^http/, "ws").replace(/\/$/, "") + "/ws",
       getAccessToken: () => sessionManager.getAccessToken(),
       buffer: alphaBuffer,
+      lifetimeState: alphaLifetimeState,
       agentId: config.agentId,
       logger: {
         info: (msg) => api.logger.info(`[solana-trader] ${msg}`),
@@ -2799,7 +2837,7 @@ ${notes}
     });
     api.registerTool({
       name: "solana_alpha_signals",
-      description: "Get buffered alpha signals from the SpyFly stream. By default returns only unseen signals and marks them as seen. Use minScore to filter low-quality signals. Poll this every heartbeat cycle in Step 1.5b. Returns signals sorted by ingestion time (newest last).",
+      description: "Read the live alpha-stream state and buffered signals from the running plugin. **Single source of truth** for any 'how many alpha signals / are we getting alpha / is alpha connected / latest signals' question \u2014 call it on the same turn. Signals are NOT logged per-message, so the journal/heartbeat-history will look empty; only this tool returns the real count.\n\nReturned shape: { signals[], count, bufferSize, subscribed, stats }.\n\nHEADLINE FIELDS for live status answers:\n - stats.messageCount = total alpha_signal messages this gateway process has received (survives plugin re-registers and WS reconnects). Use this for 'how many signals so far' answers.\n - stats.lifetimeUptimeSeconds = seconds since the first WS connect in this gateway process. Divide messageCount/lifetimeUptimeSeconds to get rate.\n - stats.lastEventTs = wall-clock ms of the most recent alpha_signal (lifetime).\n - subscribed = current WS is in subscribed state.\n - stats.reconnectAttempt, stats.unhealthyStreak, stats.circuitBackoff = health signals.\n\nDebug-only fields (do NOT report to users as 'totals'):\n - stats.currentWsMessageCount = messages since the CURRENT WS connect (resets on every reconnect; misleading as a 'total').\n - stats.uptimeSeconds = uptime of the current WS connect.\n - stats.connectedAt = ts of the current WS open.\n\nFor windows beyond what bufferSize covers (\u2248200 signals), or after a gateway restart wiped the lifetime counters, fall through to `solana_alpha_history` (REST, tier=enterprise \u2192 up to 200 results, last 12+ months).\n\nParams: pass unseen:false when the user is asking about overall state (don't mutate _seen). Pass unseen:true (default) only during heartbeat polling to mark and consume new signals. Use minScore to filter low-quality. Returns signals sorted by ingestion time (newest last).",
       parameters: Type.Object({
         minScore: Type.Optional(Type.Number({ description: "Minimum systemScore threshold (0-100). Signals below this are excluded." })),
         chain: Type.Optional(Type.String({ description: "Filter by chain (e.g., 'solana'). BSC is already filtered at ingestion." })),
@@ -2824,7 +2862,7 @@ ${notes}
     });
     api.registerTool({
       name: "solana_alpha_history",
-      description: "Query historical alpha signal data via the SpyFly REST API (GET /api/pings). Returns up to 1 year of stored signals for source reputation analysis, post-downtime catch-up, and strategy learning. Tier-gated: starter=10, pro=50, enterprise=200 results. 99.99% of tokens are dead but source patterns are invaluable.",
+      description: "Query historical alpha signal data via the orchestrator REST API (GET /api/pings). Use this whenever the user asks about an ALPHA window that extends beyond what `solana_alpha_signals` can cover, e.g.:\n - 'how many alpha signals in the last hour / today / this week / since Monday'\n - 'any alpha on <token> in the last 24h'\n - 'PAIN/$X signals from yesterday'\n - any time the live buffer is empty or just reconnected but the user is asking about a real time window.\n\nReturns up to 1 year of stored signals. Tier-gated by your account (starter=10, pro=50, enterprise=200 results). Combine with `solana_alpha_signals` (live state) to answer 'we've received N signals lifetime in this gateway, plus M historical in the window you asked about'.\n\nParams: tokenAddress, channelId, limit, days (lookback window). 99.99% of tokens are dead but source patterns are invaluable.",
       parameters: Type.Object({
         tokenAddress: Type.Optional(Type.String({ description: "Filter by token mint address" })),
         channelId: Type.Optional(Type.String({ description: "Filter by source channel ID" })),
@@ -2848,7 +2886,7 @@ ${notes}
     });
     api.registerTool({
       name: "solana_alpha_sources",
-      description: "Get per-source statistics from the alpha signal buffer \u2014 signal count, average systemScore, and source type for each channel. Use for quick reputation checks during signal processing and to identify high-quality vs low-quality sources.",
+      description: "Get per-source statistics from the alpha signal buffer \u2014 signal count, average systemScore, and source type for each channel. Call this when the user asks 'which alpha sources / channels are active', 'where are signals coming from', or any breakdown-by-source question. Always live; never answer source breakdowns from memory. Use also for quick reputation checks during signal processing.",
       parameters: Type.Object({}),
       execute: wrapExecute("solana_alpha_sources", async () => ({
         sources: alphaBuffer.getSourceStatsAll(),
@@ -4265,6 +4303,20 @@ ${String(params.summary)}
           content: entitlementMd,
           source: "solana-trader:entitlements-digest"
         });
+        context.bootstrapFiles.push({
+          name: "live-queries.md",
+          path: "live-queries.md",
+          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/alpha-ws.js

@@ -2,7 +2,7 @@ import {
   ALPHA_INGESTION_STALE_MS,
   ALPHA_STALE_GRACE_AFTER_CONNECT_MS,
   AlphaStreamManager
-} from "../chunk-ZUY36F4Q.js";
+} from "../chunk-GX4HA22L.js";
 export {
   ALPHA_INGESTION_STALE_MS,
   ALPHA_STALE_GRACE_AFTER_CONNECT_MS,

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solana-traderclaw",
-  "version": "1.0.145",
+  "version": "1.0.147",
   "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/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.