@reefclaw/openclaw-plugin 0.1.1 → 0.1.3

package/bridge/bridge.d.ts

@@ -24,6 +24,16 @@ export declare class Bridge {
     private readonly listeners;
     /** rc_ connection token — also authenticates the webapp skill-content pull */
     private readonly connectionToken;
+    /** While the local SKILL.md is still a bootstrap (0.x), re-attempt the webapp
+     *  pull on a fixed cadence so a box whose one-shot startup pull failed — a
+     *  bad/rotated token during setup, a webapp blip, or an old connector build —
+     *  still self-heals off the bootstrap even if it never reconnects. Cleared the
+     *  moment the full trading SKILL.md (2.x) applies, and on stop(). */
+    private bootstrapHealTimer;
+    /** Guards against overlapping webapp pull chains (startup + reconnect + heal
+     *  timer) double-applying / double-notifying during the one-time bootstrap→
+     *  full transition. The chain that starts (attempt 1) owns the flag. */
+    private skillPullInFlight;
     constructor(provider: OpenClawProvider, connectorConfig: ConnectorConfig);
     /** Start the bridge: connect to relay + start provider */
     start(): void;
@@ -104,6 +114,23 @@ export declare class Bridge {
      * gate when enforced) as the relay pull path.
      */
     private pullSkillContentFromWebapp;
-    /** Check relay's latest SKILL.md version against local and auto-update if stale */
+    /** Start a bounded periodic re-pull of the full SKILL.md while the box is
+     *  still on the bootstrap (0.x). pullSkillContentFromWebapp() (fired once at
+     *  startup) is a one-shot with a finite retry burst; if every attempt fails —
+     *  rotated token during setup, webapp blip, or an old connector build — a box
+     *  that then stays stably connected (no reconnect to re-trigger the pull)
+     *  would remain stranded on the bootstrap forever. This interval re-attempts
+     *  every few minutes until the full 2.x skill applies, then retires itself.
+     *  Strict no-op once upgraded (guarded on version), so upgraded boxes add zero
+     *  steady-state webapp load. */
+    private startBootstrapHeal;
+    /** Stop the bootstrap heal timer (on successful upgrade or bridge stop). */
+    private stopBootstrapHeal;
+    /** On every relay (re)connect: (1) if still on the bootstrap SKILL.md, re-fire
+     *  the authenticated webapp pull — the relay's per-room store is empty for a
+     *  fresh user, so the webapp endpoint is the only source of the first full
+     *  copy and the one-shot in start() may have exhausted its retries during
+     *  setup; (2) apply any newer version the relay advertises (the OTA push
+     *  channel for updates once the store is populated). */
     private handleConnectAck;
 }

package/bridge/bridge.js

@@ -6,7 +6,7 @@ import { join } from 'path';
 import { homedir } from 'os';
 import { logger } from './logger.js';
 import { Connector } from './connector.js';
-import { readLocalSkillVersion, validateSkillContent, compareSemver } from './utils/skill-version.js';
+import { readLocalSkillVersion, readAgentVisibleSkillVersions, validateSkillContent, compareSemver } from './utils/skill-version.js';
 import { verifySkillSignature, signatureRequired, readLastAppliedSignedAtMs, recordAppliedSignedAt, } from './utils/skill-signing.js';
 import { isTradingMode, validateModeTransition, redactTokens } from '@reefclaw/shared';
 import { OPERATOR_WRITE_METHODS } from './types.js';
@@ -47,6 +47,19 @@ const CRITICAL_EVENTS = new Set([
     'skill_update_applied', // OTA SKILL.md confirmation
     // All chat events are on the 'chat' channel and always sent immediately
 ]);
+/** How often to re-attempt the webapp SKILL.md pull while still on a bootstrap
+ *  (0.x) version. Long enough to be negligible load, short enough to un-strand
+ *  a new user whose one-shot startup pull failed. */
+const BOOTSTRAP_SKILL_HEAL_INTERVAL_MS = 10 * 60_000; // 10 min
+/** True while the agent is still on the thin bootstrap SKILL.md and has NOT yet
+ *  received the full trading instructions. The bootstrap ships 0.0.x; the full
+ *  trading SKILL.md is 2.x — treat anything below 1.0.0 (or an unknown version)
+ *  as bootstrap so we keep pulling until the real skill lands. */
+function isBootstrapSkillVersion(version) {
+    if (!version)
+        return true;
+    return compareSemver('1.0.0', version) > 0; // '1.0.0' > version  ⟺  version < 1.0.0
+}
 export class Bridge {
     provider;
     connector;
@@ -79,6 +92,16 @@ export class Bridge {
     listeners = [];
     /** rc_ connection token — also authenticates the webapp skill-content pull */
     connectionToken;
+    /** While the local SKILL.md is still a bootstrap (0.x), re-attempt the webapp
+     *  pull on a fixed cadence so a box whose one-shot startup pull failed — a
+     *  bad/rotated token during setup, a webapp blip, or an old connector build —
+     *  still self-heals off the bootstrap even if it never reconnects. Cleared the
+     *  moment the full trading SKILL.md (2.x) applies, and on stop(). */
+    bootstrapHealTimer = null;
+    /** Guards against overlapping webapp pull chains (startup + reconnect + heal
+     *  timer) double-applying / double-notifying during the one-time bootstrap→
+     *  full transition. The chain that starts (attempt 1) owns the flag. */
+    skillPullInFlight = false;
     constructor(provider, connectorConfig) {
         this.provider = provider;
         this.currentSkillVersion = readLocalSkillVersion();
@@ -102,11 +125,17 @@ export class Bridge {
         // in the public npm package. Fire-and-forget with retries; the relay OTA
         // path (handleConnectAck) remains the push channel for updates.
         void this.pullSkillContentFromWebapp();
+        // The one-shot above has a finite retry burst; this keeps re-trying every
+        // few minutes until the full SKILL.md lands, so a box that stays connected
+        // without reconnecting can't be stranded on the bootstrap. No-op once
+        // upgraded (guarded on version).
+        this.startBootstrapHeal();
     }
     /** Stop the bridge: disconnect + stop provider */
     stop() {
         logger.info(TAG, 'Stopping bridge');
         this.stopThrottleTimer();
+        this.stopBootstrapHeal();
         this.unwireProviderEvents();
         this.connector.destroy();
         this.provider.stop();
@@ -808,6 +837,37 @@ export class Bridge {
                     logger.warn(TAG, `Failed to update workspace skill SKILL.md: ${scanErr instanceof Error ? scanErr.message : String(scanErr)}`);
                 }
             }
+            // 2d. Also write to the plugin-extension bundled skill directory — the
+            // chat-channel install layout (`/plugins install clawhub:...`) loads the
+            // agent-visible skill from ~/.openclaw/extensions/<plugin>/skills/, and a
+            // plugin (re)install resets that copy to the bundled bootstrap while the
+            // workspace copy above (our version tracker) survives. Without this
+            // write the agent stays on the bootstrap forever while the pull reports
+            // "already up to date" (observed live 2026-07-11).
+            const extensionsDir = join(homedir(), '.openclaw', 'extensions');
+            if (existsSync(extensionsDir)) {
+                try {
+                    for (const ext of readdirSync(extensionsDir, { withFileTypes: true })) {
+                        if (!ext.isDirectory() || !ext.name.includes('reefclaw'))
+                            continue;
+                        const extSkillsDir = join(extensionsDir, ext.name, 'skills');
+                        if (!existsSync(extSkillsDir))
+                            continue;
+                        for (const skillEntry of readdirSync(extSkillsDir, { withFileTypes: true })) {
+                            if (!skillEntry.isDirectory() || !skillEntry.name.includes('reefclaw'))
+                                continue;
+                            const extSkillMd = join(extSkillsDir, skillEntry.name, 'SKILL.md');
+                            if (existsSync(extSkillMd)) {
+                                writeFileSync(extSkillMd, content, 'utf-8');
+                                logger.info(TAG, `Updated extension skill SKILL.md: ${extSkillMd}`);
+                            }
+                        }
+                    }
+                }
+                catch (scanErr) {
+                    logger.warn(TAG, `Failed to update extension skill SKILL.md: ${scanErr instanceof Error ? scanErr.message : String(scanErr)}`);
+                }
+            }
             // 3. Invalidate skillsSnapshot cache WITHOUT wiping sessions.json
             // Previously we wrote '{}' to sessions.json which destroyed OpenClaw chat history.
             // Now we surgically remove only the skillsSnapshot key from each session entry,
@@ -916,6 +976,17 @@ export class Bridge {
      * gate when enforced) as the relay pull path.
      */
     async pullSkillContentFromWebapp(attempt = 1) {
+        // Only one pull chain at a time: startup, reconnect (handleConnectAck) and
+        // the bootstrap heal timer can each trigger a pull. Without this guard they
+        // could overlap during the one-time bootstrap→full transition and
+        // double-apply / double-notify the agent. The chain that starts (attempt 1)
+        // owns the flag; whichever attempt terminates the chain clears it. A retry
+        // (attempt > 1) is the same chain continuing, so it must NOT re-check/re-set.
+        if (attempt === 1) {
+            if (this.skillPullInFlight)
+                return;
+            this.skillPullInFlight = true;
+        }
         const MAX_ATTEMPTS = 5;
         // www is load-bearing: reefclaw.com 307-redirects and Node fetch strips the
         // Authorization header on cross-origin redirect (verified 2026-03-18).
@@ -927,21 +998,36 @@ export class Bridge {
             });
             if (res.status === 401 || res.status === 403) {
                 logger.warn(TAG, `SKILL.md webapp pull: not authorized (${res.status}) — connect the account first`);
-                return; // A bad token won't get better by retrying.
+                this.skillPullInFlight = false;
+                return; // A bad token won't get better by retrying within this chain.
             }
             if (!res.ok)
                 throw new Error(`HTTP ${res.status}`);
             const body = (await res.json());
             if (!body?.version || !body?.content) {
                 logger.warn(TAG, 'SKILL.md webapp pull: response missing version/content');
+                this.skillPullInFlight = false;
                 return;
             }
             this.currentSkillVersion = readLocalSkillVersion();
-            if (compareSemver(body.version, this.currentSkillVersion) <= 0) {
+            // The workspace tracker alone is NOT proof the agent has the full skill:
+            // a plugin (re)install resets the agent-visible extension copy to the
+            // bundled bootstrap while the workspace copy survives (observed live
+            // 2026-07-11 — agent stranded on 0.0.5 with the tracker at 2.20.4). If
+            // ANY agent-visible copy is behind the webapp version, re-apply anyway;
+            // applySkillUpdate is idempotent across all copies.
+            const staleAgentCopies = readAgentVisibleSkillVersions().filter((v) => compareSemver(body.version, v) > 0);
+            if (compareSemver(body.version, this.currentSkillVersion) <= 0 && staleAgentCopies.length === 0) {
                 logger.info(TAG, `SKILL.md webapp pull: local v${this.currentSkillVersion ?? 'unknown'} already >= webapp v${body.version} — nothing to do`);
+                this.skillPullInFlight = false;
                 return;
             }
-            logger.info(TAG, `SKILL.md webapp pull: local v${this.currentSkillVersion ?? 'unknown'} behind webapp v${body.version} — applying`);
+            if (staleAgentCopies.length > 0 && compareSemver(body.version, this.currentSkillVersion) <= 0) {
+                logger.info(TAG, `SKILL.md webapp pull: agent-visible skill copy at v${staleAgentCopies[0]} behind webapp v${body.version} (plugin reinstall reset it) — re-applying`);
+            }
+            else {
+                logger.info(TAG, `SKILL.md webapp pull: local v${this.currentSkillVersion ?? 'unknown'} behind webapp v${body.version} — applying`);
+            }
             const result = await this.applySkillUpdate({ version: body.version, content: body.content });
             this.emit('agent_state', 'skill_update_applied', {
                 event: 'skill_update_applied',
@@ -952,25 +1038,77 @@ export class Bridge {
             });
             if (!result.success)
                 logger.error(TAG, `SKILL.md webapp pull: apply failed: ${result.message}`);
+            this.skillPullInFlight = false;
+            // A successful apply moved us off the bootstrap — retire the heal timer.
+            if (result.success)
+                this.stopBootstrapHeal();
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
             if (attempt >= MAX_ATTEMPTS) {
                 logger.error(TAG, `SKILL.md webapp pull failed after ${MAX_ATTEMPTS} attempts: ${msg}`);
+                this.skillPullInFlight = false;
                 return;
             }
             const delayMs = attempt * 30_000;
             logger.warn(TAG, `SKILL.md webapp pull failed (attempt ${attempt}/${MAX_ATTEMPTS}): ${msg} — retrying in ${delayMs / 1000}s`);
+            // Keep skillPullInFlight = true: the chain continues on the scheduled retry.
             setTimeout(() => void this.pullSkillContentFromWebapp(attempt + 1), delayMs).unref?.();
         }
     }
-    /** Check relay's latest SKILL.md version against local and auto-update if stale */
+    /** Start a bounded periodic re-pull of the full SKILL.md while the box is
+     *  still on the bootstrap (0.x). pullSkillContentFromWebapp() (fired once at
+     *  startup) is a one-shot with a finite retry burst; if every attempt fails —
+     *  rotated token during setup, webapp blip, or an old connector build — a box
+     *  that then stays stably connected (no reconnect to re-trigger the pull)
+     *  would remain stranded on the bootstrap forever. This interval re-attempts
+     *  every few minutes until the full 2.x skill applies, then retires itself.
+     *  Strict no-op once upgraded (guarded on version), so upgraded boxes add zero
+     *  steady-state webapp load. */
+    startBootstrapHeal() {
+        if (this.bootstrapHealTimer)
+            return;
+        if (!isBootstrapSkillVersion(this.currentSkillVersion))
+            return; // already on the full skill
+        this.bootstrapHealTimer = setInterval(() => {
+            // Re-read from disk: the file may have been upgraded out-of-band (relay
+            // OTA push, manual SFTP) since we last cached it.
+            this.currentSkillVersion = readLocalSkillVersion();
+            if (!isBootstrapSkillVersion(this.currentSkillVersion)) {
+                this.stopBootstrapHeal();
+                return;
+            }
+            logger.info(TAG, `Still on bootstrap SKILL.md (v${this.currentSkillVersion ?? 'unknown'}) — re-attempting webapp pull`);
+            void this.pullSkillContentFromWebapp();
+        }, BOOTSTRAP_SKILL_HEAL_INTERVAL_MS);
+        this.bootstrapHealTimer.unref?.();
+    }
+    /** Stop the bootstrap heal timer (on successful upgrade or bridge stop). */
+    stopBootstrapHeal() {
+        if (this.bootstrapHealTimer) {
+            clearInterval(this.bootstrapHealTimer);
+            this.bootstrapHealTimer = null;
+        }
+    }
+    /** On every relay (re)connect: (1) if still on the bootstrap SKILL.md, re-fire
+     *  the authenticated webapp pull — the relay's per-room store is empty for a
+     *  fresh user, so the webapp endpoint is the only source of the first full
+     *  copy and the one-shot in start() may have exhausted its retries during
+     *  setup; (2) apply any newer version the relay advertises (the OTA push
+     *  channel for updates once the store is populated). */
     async handleConnectAck(payload) {
+        // Re-read local version (may have changed since startup)
+        this.currentSkillVersion = readLocalSkillVersion();
+        // Fresh-user self-heal: while still on the thin bootstrap SKILL.md, pull the
+        // full instructions from the webapp on this (re)connect. Guarded (in-flight)
+        // + downgrade-checked, so it's a strict no-op once upgraded.
+        if (isBootstrapSkillVersion(this.currentSkillVersion)) {
+            logger.info(TAG, `Connect ack while on bootstrap SKILL.md (v${this.currentSkillVersion ?? 'unknown'}) — pulling full instructions from webapp`);
+            void this.pullSkillContentFromWebapp();
+        }
         const latestVersion = payload.latestSkillVersion;
         if (!latestVersion)
             return;
-        // Re-read local version (may have changed since startup)
-        this.currentSkillVersion = readLocalSkillVersion();
         const cmp = compareSemver(latestVersion, this.currentSkillVersion);
         if (cmp === 0) {
             logger.debug(TAG, `SKILL.md up to date (v${latestVersion})`);

package/bridge/utils/skill-version.d.ts

@@ -2,6 +2,15 @@
 export declare function parseSkillVersion(content: string): string | null;
 /** Read current SKILL.md version from disk */
 export declare function readLocalSkillVersion(): string | null;
+/** Versions of the AGENT-VISIBLE reefclaw SKILL.md copies under the
+ *  plugin-extension layout (`~/.openclaw/extensions/<plugin>/skills/<skill>/`)
+ *  — what OpenClaw's skill loader actually reads on chat-channel installs.
+ *  A plugin (re)install resets these to the bundled bootstrap while the
+ *  workspace copy (the version tracker above) survives, so the tracker alone
+ *  cannot be trusted for "already up to date" (observed live 2026-07-11: agent
+ *  stranded on bootstrap 0.0.5 while the tracker read 2.20.4). Fail-soft:
+ *  unreadable dirs/files are skipped; no extensions dir → empty list. */
+export declare function readAgentVisibleSkillVersions(): string[];
 /**
  * Compare two semver strings.
  * Returns 1 if a > b, -1 if a < b, 0 if equal.

package/bridge/utils/skill-version.js

@@ -1,5 +1,5 @@
 // SKILL.md version parsing utility for OTA updates
-import { readFileSync } from 'fs';
+import { readFileSync, readdirSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
 const SKILL_MD_PATH = join(homedir(), '.openclaw', 'workspace', 'SKILL.md');
@@ -18,6 +18,50 @@ export function readLocalSkillVersion() {
         return null;
     }
 }
+/** Versions of the AGENT-VISIBLE reefclaw SKILL.md copies under the
+ *  plugin-extension layout (`~/.openclaw/extensions/<plugin>/skills/<skill>/`)
+ *  — what OpenClaw's skill loader actually reads on chat-channel installs.
+ *  A plugin (re)install resets these to the bundled bootstrap while the
+ *  workspace copy (the version tracker above) survives, so the tracker alone
+ *  cannot be trusted for "already up to date" (observed live 2026-07-11: agent
+ *  stranded on bootstrap 0.0.5 while the tracker read 2.20.4). Fail-soft:
+ *  unreadable dirs/files are skipped; no extensions dir → empty list. */
+export function readAgentVisibleSkillVersions() {
+    const versions = [];
+    const extensionsDir = join(homedir(), '.openclaw', 'extensions');
+    let extEntries;
+    try {
+        extEntries = readdirSync(extensionsDir, { withFileTypes: true });
+    }
+    catch {
+        return versions;
+    }
+    for (const ext of extEntries) {
+        if (!ext.isDirectory() || !ext.name.includes('reefclaw'))
+            continue;
+        const skillsDir = join(extensionsDir, ext.name, 'skills');
+        let skillEntries;
+        try {
+            skillEntries = readdirSync(skillsDir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const s of skillEntries) {
+            if (!s.isDirectory() || !s.name.includes('reefclaw'))
+                continue;
+            try {
+                const v = parseSkillVersion(readFileSync(join(skillsDir, s.name, 'SKILL.md'), 'utf-8'));
+                if (v)
+                    versions.push(v);
+            }
+            catch {
+                // unreadable/absent copy — nothing to report for this entry
+            }
+        }
+    }
+    return versions;
+}
 // 120KB — the full SKILL.md crossed 100KB at v2.20.0 (103.7KB), which silently
 // broke every OTA apply against the old 100KB cap. Keep comfortably under the
 // 128KiB Cloudflare Durable-Object per-value hard limit the relay stores into.

package/ccxt/binance-ban-gate.js

@@ -128,6 +128,12 @@ const CONTEXT_WEIGHT = {
     fetchOHLCV: 2,
     fetchFundingRate: 1,
     fetchOpenInterest: 1,
+    // Readiness gate's host→Binance reachability probe (fapiPublicGetTime, wt 1).
+    reachabilityProbe: 1,
+    // ExchangeInfoCache boot load — ccxt loadMarkets() → GET /fapi/v1/exchangeInfo,
+    // IP weight 1 (doc-verified developers.binance.com 2026-07-10). Was the
+    // known "ungated_ip" ccxt-internal call named in the window-summary comment.
+    loadMarkets: 1,
     fetchBalance: 5,
     fetchPositions: 5,
     // BinancePrivateApi.fetchOpenOrders merges TWO REST calls (regular
@@ -175,6 +181,11 @@ const NEVER_PACE = new Set([
     'createOrder', 'cancelOrder', 'cancelAllOrders', 'cancelOrderByClientId',
     'createBracketOrder', 'createListenKey', 'keepAliveListenKey', 'closeListenKey',
     'fetchTodayIncomeBreakdownForced',
+    // ExchangeInfoCache boot load: runs once per adapter init and a failure
+    // BLOCKS the adapter (no retry until restart), so a paced-out load would
+    // trade ~1 weight of relief for a dead adapter. Ban-gated + counted like
+    // the listenKey contexts, never shed.
+    'loadMarkets',
 ]);
 /** Low-priority contexts that shed FIRST under weight pressure (paced
  *  against COSMETIC_SOFT_CEILING, not the full ceiling). Two safe-to-shed
@@ -191,7 +202,7 @@ const NEVER_PACE = new Set([
 const SHED_FIRST = new Set([
     'fetchTodayIncomeBreakdown', 'fetchTransfers', 'fetchRecentTradedSymbols',
     'fetchTicker', 'fetchTickerRaw', 'fetchOHLCV', 'fetchOrderBook',
-    'fetchFundingRate', 'fetchOpenInterest',
+    'fetchFundingRate', 'fetchOpenInterest', 'reachabilityProbe',
 ]);
 let weightWindowStart = 0;
 let weightUsed = 0;

package/ccxt/binance-public.d.ts

@@ -15,4 +15,19 @@ export declare class BinancePublicApi {
     fetchOrderBook(symbol: string, limit?: number): Promise<OrderBookDepth | null>;
     /** Fetch OHLCV candles. Returns null on error. */
     fetchOHLCV(symbol: string, timeframe?: string, limit?: number): Promise<CcxtOHLCV[] | null>;
+    /** Probe Binance USD-M FUTURES reachability from this host — the readiness
+     *  gate's core signal. Calls the futures-explicit implicit method so it hits
+     *  `fapi.binance.com` (a bare `fetchTime()` on this instance resolves to spot
+     *  `api.binance.com`, since the public client doesn't set defaultType:'future').
+     *  HTTP 451 = Binance geo-restriction; the ban gate does NOT classify 451, so
+     *  we inspect the message here. Ban-gate compliant (assertNotBanned/noteSuccess/
+     *  noteBinanceError). Outcomes:
+     *   - 'reachable'   clean response (driftMs = serverTime − localTime)
+     *   - 'geo_blocked' HTTP 451 — host is in a restricted region (actionable)
+     *   - 'unknown'     the ban/weight gate paused us — NOT a host problem
+     *   - 'unreachable' network / DNS / timeout / other error */
+    probeReachability(): Promise<{
+        outcome: 'reachable' | 'geo_blocked' | 'unreachable' | 'unknown';
+        driftMs: number | null;
+    }>;
 }

package/ccxt/binance-public.js

@@ -2,7 +2,7 @@
 // No API keys required — only uses public market data.
 import { createRequire } from 'node:module';
 import { logger } from '../logger.js';
-import { assertNotBanned, noteBinanceError, noteSuccess } from './binance-ban-gate.js';
+import { assertNotBanned, noteBinanceError, noteSuccess, BinanceBannedError } from './binance-ban-gate.js';
 const TAG = 'binance-public';
 // Load ccxt via CJS require — OpenClaw's ESM loader gives wrong module shape
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -144,4 +144,37 @@ export class BinancePublicApi {
             return null;
         }
     }
+    /** Probe Binance USD-M FUTURES reachability from this host — the readiness
+     *  gate's core signal. Calls the futures-explicit implicit method so it hits
+     *  `fapi.binance.com` (a bare `fetchTime()` on this instance resolves to spot
+     *  `api.binance.com`, since the public client doesn't set defaultType:'future').
+     *  HTTP 451 = Binance geo-restriction; the ban gate does NOT classify 451, so
+     *  we inspect the message here. Ban-gate compliant (assertNotBanned/noteSuccess/
+     *  noteBinanceError). Outcomes:
+     *   - 'reachable'   clean response (driftMs = serverTime − localTime)
+     *   - 'geo_blocked' HTTP 451 — host is in a restricted region (actionable)
+     *   - 'unknown'     the ban/weight gate paused us — NOT a host problem
+     *   - 'unreachable' network / DNS / timeout / other error */
+    async probeReachability() {
+        try {
+            assertNotBanned('reachabilityProbe');
+            const r = await this.exchange.fapiPublicGetTime({});
+            noteSuccess();
+            const serverTime = Number(r?.serverTime);
+            const driftMs = Number.isFinite(serverTime) ? serverTime - Date.now() : null;
+            return { outcome: 'reachable', driftMs };
+        }
+        catch (err) {
+            noteBinanceError(err);
+            if (err instanceof BinanceBannedError) {
+                // Gate paused us (418/429 backoff or weight pacer) — we didn't actually
+                // reach the host, so the result is UNKNOWN, not a reachability failure.
+                return { outcome: 'unknown', driftMs: null };
+            }
+            const msg = err instanceof Error ? err.message : String(err);
+            const geo = msg.includes('451');
+            logger.warn(TAG, `probeReachability failed${geo ? ' (HTTP 451 geo-block)' : ''}: ${msg}`);
+            return { outcome: geo ? 'geo_blocked' : 'unreachable', driftMs: null };
+        }
+    }
 }

package/config/agent-config-client.d.ts

@@ -10,6 +10,19 @@ export interface AgentGates {
     exitGate?: 'off' | 'shadow' | 'observe' | 'enforce';
     positionReviewMode?: 'off' | 'shadow' | 'observe' | 'enforce';
 }
+/** Server-resolved entitlement verdict (webapp lib/entitlements.ts, computed
+ *  from the users row and delivered on the config channel). The plugin NEVER
+ *  re-derives billing state — it consumes `paidAccess` as-is. Absent field =
+ *  unknown = the entitlement gate fails OPEN (older webapp, outage, garbage):
+ *  billing enforcement must never depend on this read succeeding; the
+ *  server-side 403 walls (webapp Pro routes + intel) are the hard layer. */
+export interface AgentEntitlement {
+    state: 'active' | 'trialing' | 'grace' | 'expired' | 'none';
+    paidAccess: boolean;
+    tier?: string;
+    expiresAt?: string;
+    graceUntil?: string;
+}
 /** The slice of /api/internal/config the plugin consumes today. `limits`
  *  arrives in the payload but is deliberately not modeled yet. */
 export interface AgentConfig {
@@ -18,6 +31,8 @@ export interface AgentConfig {
         disabled: string[];
     };
     gates: AgentGates;
+    /** Absent when the server omitted it or the field failed validation. */
+    entitlement?: AgentEntitlement;
 }
 /** Hardcoded safe default — identical to pre-central behavior (nothing
  *  disabled, no central gate values → local file / defaults rule). */
@@ -29,6 +44,13 @@ export declare function defaultAgentConfig(): AgentConfig;
  * the plugin doesn't already consider safe).
  */
 export declare function validateAgentConfig(raw: unknown): AgentConfig | null;
+/** Per-field entitlement validation: a structurally-valid `{state, paidAccess}`
+ *  pair (state in the enum, paidAccess a real boolean) is kept; ANYTHING else
+ *  → undefined, and an absent entitlement makes the gate fail open. Garbage
+ *  can pause new entries only by forging a syntactically-perfect verdict —
+ *  and even then it can never touch closes/stops/emergency (those aren't in
+ *  the gated set at all — see entitlement-gate.ts). */
+export declare function validateEntitlement(raw: unknown): AgentEntitlement | undefined;
 /** Version-monotonic acceptance (basic rollback/replay protection): a fetched
  *  config older than what we already applied is rejected. Equal versions are
  *  acceptable (idempotent re-apply is a no-op for the gate). */

package/config/agent-config-client.js

@@ -23,6 +23,13 @@ const TAG = 'agent-config';
  *  because exitGate + positionReviewMode use identical values; a future gate
  *  with a different enum gets its own constant. */
 const MODE_LADDER_VALUES = new Set(['off', 'shadow', 'observe', 'enforce']);
+const ENTITLEMENT_STATES = new Set([
+    'active',
+    'trialing',
+    'grace',
+    'expired',
+    'none',
+]);
 /** Hardcoded safe default — identical to pre-central behavior (nothing
  *  disabled, no central gate values → local file / defaults rule). */
 export function defaultAgentConfig() {
@@ -51,7 +58,43 @@ export function validateAgentConfig(raw) {
     if (!Array.isArray(disabledRaw))
         return null;
     const disabled = disabledRaw.filter((v) => typeof v === 'string' && TOOL_NAME_RE.test(v));
-    return { version, tools: { disabled }, gates: validateGates(obj.gates) };
+    const config = {
+        version,
+        tools: { disabled },
+        gates: validateGates(obj.gates),
+    };
+    const entitlement = validateEntitlement(obj.entitlement);
+    if (entitlement)
+        config.entitlement = entitlement;
+    return config;
+}
+/** Per-field entitlement validation: a structurally-valid `{state, paidAccess}`
+ *  pair (state in the enum, paidAccess a real boolean) is kept; ANYTHING else
+ *  → undefined, and an absent entitlement makes the gate fail open. Garbage
+ *  can pause new entries only by forging a syntactically-perfect verdict —
+ *  and even then it can never touch closes/stops/emergency (those aren't in
+ *  the gated set at all — see entitlement-gate.ts). */
+export function validateEntitlement(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return undefined;
+    const obj = raw;
+    const state = obj.state;
+    const paidAccess = obj.paidAccess;
+    if (typeof state !== 'string' || !ENTITLEMENT_STATES.has(state))
+        return undefined;
+    if (typeof paidAccess !== 'boolean')
+        return undefined;
+    const entitlement = {
+        state: state,
+        paidAccess,
+    };
+    if (typeof obj.tier === 'string')
+        entitlement.tier = obj.tier;
+    if (typeof obj.expiresAt === 'string')
+        entitlement.expiresAt = obj.expiresAt;
+    if (typeof obj.graceUntil === 'string')
+        entitlement.graceUntil = obj.graceUntil;
+    return entitlement;
 }
 /** Per-field gate validation (§5b): a structurally-absent/garbage `gates`
  *  becomes `{}` (no central values → local config rules); each known gate is

package/config/agent-config-poller.d.ts

@@ -1,4 +1,4 @@
-import { type AgentConfig, type AgentGates } from './agent-config-client.js';
+import { type AgentConfig, type AgentEntitlement, type AgentGates } from './agent-config-client.js';
 import type { ToolGate } from './tool-gate.js';
 export declare function resolvePollIntervalMs(): number;
 export interface AgentConfigPollerOptions {
@@ -9,6 +9,13 @@ export interface AgentConfigPollerOptions {
     gateStore?: {
         apply(gates: AgentGates): void;
     };
+    /** Entitlement consumer (account-level enforcement). Optional, wired from
+     *  index.ts with the module singleton `entitlementGate`. Receives the
+     *  config's entitlement slice — including `undefined` when the server
+     *  omitted it, which clears any held verdict (fail-open). */
+    entitlementGate?: {
+        apply(entitlement: AgentEntitlement | undefined): void;
+    };
     apiBaseUrl: string;
     token: string;
     fetchImpl?: typeof fetch;

package/config/agent-config-poller.js

@@ -54,6 +54,7 @@ export function startAgentConfigPoller(opts) {
         current = fetched;
         opts.gate.apply(fetched);
         opts.gateStore?.apply(fetched.gates);
+        opts.entitlementGate?.apply(fetched.entitlement);
         return true;
     };
     const poll = async (isBoot) => {

package/config/entitlement-gate.d.ts

@@ -0,0 +1,51 @@
+import type { AgentEntitlement } from './agent-config-client.js';
+/** The ONLY tools an expired entitlement may pause. Deliberately a denylist
+ *  (not "everything except safety"): a tool added tomorrow is un-gated by
+ *  default, which is the conservative failure mode in a trading product.
+ *  Intel/data tools are NOT here — the intelligence service and webapp 403
+ *  those server-side with the same actionable message. */
+export declare const ENTITLEMENT_GATED_TOOLS: ReadonlySet<string>;
+export type EntitlementGateMode = 'enforce' | 'shadow' | 'off';
+export declare function resolveEntitlementGateMode(): EntitlementGateMode;
+/** Structured, agent-visible result for a blocked call. Worded so the agent
+ *  stops cleanly (no retry loop), keeps managing the existing book, and tells
+ *  the operator exactly how to restore service. */
+export declare function entitlementBlockedResult(name: string): {
+    ok: false;
+    error: 'entitlement_expired';
+    tool: string;
+    message: string;
+};
+/** Minimal structural view of a registered plugin tool — same shape as
+ *  tool-gate.ts GateablePluginTool (kept local to avoid a cross-module type
+ *  dependency for one interface). */
+export interface EntitlementGateableTool {
+    name: string;
+    execute: (...args: any[]) => any;
+}
+export declare class EntitlementGate {
+    private readonly mode;
+    private entitlement;
+    /** Avoids log spam: one line per state transition, not per blocked call. */
+    private lastLoggedKey;
+    constructor(mode?: EntitlementGateMode);
+    getMode(): EntitlementGateMode;
+    getEntitlement(): AgentEntitlement | undefined;
+    /** Apply the entitlement slice of a validated config (poller path).
+     *  `undefined` (server omitted it / validation dropped it) CLEARS the held
+     *  verdict — the gate then fails open rather than enforcing a stale one
+     *  the server no longer asserts. */
+    apply(entitlement: AgentEntitlement | undefined): void;
+    /** Should this call be blocked? Non-gated names short-circuit FIRST (the
+     *  safety set can never be touched, in any mode, with any payload); then
+     *  only an explicit server verdict of paidAccess=false blocks. */
+    isBlocked(name: string): boolean;
+    /** Wrap a tool's execute with the gate check — same hot-apply pattern as
+     *  ToolGate.wrapTool (state is consulted per call, not at registration). */
+    wrapTool<T extends EntitlementGateableTool>(tool: T, jsonResult: (data: unknown) => unknown): T;
+    /** Test-only. */
+    __reset(): void;
+}
+/** Module singleton — one gate per plugin process, shared by the poller
+ *  (writer) and the tool-wrap in index.ts (consumer), mirroring gateStore. */
+export declare const entitlementGate: EntitlementGate;