@reefclaw/connect 0.1.11 → 0.1.12

package/assets/bridge/gateway/heartbeat-cron.d.ts

@@ -0,0 +1,27 @@
+export declare const HEARTBEAT_CRON_NAME = "reefclaw-heartbeat";
+export declare const HEARTBEAT_EVERY_MS: number;
+export declare const HEARTBEAT_MESSAGE: string;
+export interface CronRpcClient {
+    sendRpc(method: string, params?: Record<string, unknown>): Promise<unknown>;
+}
+/**
+ * Whether an existing cron job counts as "the heartbeat already exists".
+ * Union of the two matchers already in the codebase: the old setup path
+ * matched /reefclaw/, while resolveHeartbeatSeconds() (the cadence reader that
+ * drives the dashboard header) matches /heart\s*beat/. A job satisfying either
+ * must suppress creation — prod/wisekid boxes carry heartbeat jobs whose names
+ * predate the reefclaw- prefix, and a duplicate 15m heartbeat would double the
+ * agent's token burn.
+ */
+export declare function isHeartbeatLikeName(name: unknown): boolean;
+export type EnsureHeartbeatOutcome = 'already_ensured' | 'found_existing' | 'created' | 'failed';
+/**
+ * Ensure a heartbeat cron exists. Non-fatal by contract: every failure path
+ * returns 'failed' rather than throwing, and only success writes the marker so
+ * a transient gateway error retries on the next boot.
+ */
+export declare function ensureHeartbeatCron(opts: {
+    rpc: CronRpcClient;
+    markerPath: string;
+    log: (msg: string) => void;
+}): Promise<EnsureHeartbeatOutcome>;

package/assets/bridge/gateway/heartbeat-cron.js

@@ -0,0 +1,85 @@
+// Ensures the ReefClaw heartbeat cron job exists — once per install — via
+// gateway RPC (`cron.list` / `cron.add`).
+//
+// This replaces the old setup-time shell-out to the openclaw CLI. The CLI's
+// cron commands are themselves gateway RPC clients, so shelling out bought
+// nothing except a subprocess + PATH dependency — and it ran at
+// setup time, when the gateway is typically NOT up yet (setup's printed next
+// step is "Start your OpenClaw agent"), which is why creation silently
+// no-op'd on fresh installs without a running gateway. The bridge holds an
+// authenticated gateway WS by construction, so the ensure runs there instead.
+//
+// Once-per-install semantics: a marker file records that the ensure has run to
+// completion. Without it, a user who deliberately deleted their heartbeat cron
+// would get it resurrected on every bridge boot — the old setup-time path ran
+// once, and that operator-override behaviour must be preserved.
+import { existsSync, mkdirSync, writeFileSync } from 'fs';
+import { dirname } from 'path';
+export const HEARTBEAT_CRON_NAME = 'reefclaw-heartbeat';
+export const HEARTBEAT_EVERY_MS = 15 * 60 * 1000;
+// Byte-identical to the message the setup-time CLI path created, so new jobs
+// match every existing install's job.
+export const HEARTBEAT_MESSAGE = 'Heartbeat. Run SESSION START mandatory checks, then the full Decision Loop (Steps 0-9) from SKILL.md. ' +
+    'Check tradingMode from fetch_balance — it is your source of truth for paper vs live. ' +
+    'Use tools in parallel where possible.';
+/**
+ * Whether an existing cron job counts as "the heartbeat already exists".
+ * Union of the two matchers already in the codebase: the old setup path
+ * matched /reefclaw/, while resolveHeartbeatSeconds() (the cadence reader that
+ * drives the dashboard header) matches /heart\s*beat/. A job satisfying either
+ * must suppress creation — prod/wisekid boxes carry heartbeat jobs whose names
+ * predate the reefclaw- prefix, and a duplicate 15m heartbeat would double the
+ * agent's token burn.
+ */
+export function isHeartbeatLikeName(name) {
+    return typeof name === 'string' && /reefclaw|heart\s*beat/i.test(name);
+}
+/**
+ * Ensure a heartbeat cron exists. Non-fatal by contract: every failure path
+ * returns 'failed' rather than throwing, and only success writes the marker so
+ * a transient gateway error retries on the next boot.
+ */
+export async function ensureHeartbeatCron(opts) {
+    const { rpc, markerPath, log } = opts;
+    try {
+        if (existsSync(markerPath))
+            return 'already_ensured';
+        // includeDisabled: a job the user disabled still means "exists" — re-adding
+        // a duplicate next to a deliberately-disabled one is worse than doing nothing.
+        const listResp = (await rpc.sendRpc('cron.list', { includeDisabled: true }));
+        const jobs = Array.isArray(listResp?.jobs) ? listResp.jobs : null;
+        if (!jobs) {
+            log('Heartbeat cron: skipped (cron.list returned no job list)');
+            return 'failed';
+        }
+        const existing = jobs.find((j) => isHeartbeatLikeName(j?.name));
+        if (existing) {
+            writeMarker(markerPath, { ensuredAt: new Date().toISOString(), found: String(existing.name) });
+            log(`Heartbeat cron: already exists (${String(existing.name)})`);
+            return 'found_existing';
+        }
+        // Parity with the params the CLI built for the old setup command
+        // (`openclaw cron add --name reefclaw-heartbeat --every 15m --session isolated --message ...`):
+        // isolated agentTurn defaults to delivery announce on the 'last' channel.
+        await rpc.sendRpc('cron.add', {
+            name: HEARTBEAT_CRON_NAME,
+            enabled: true,
+            schedule: { kind: 'every', everyMs: HEARTBEAT_EVERY_MS },
+            sessionTarget: 'isolated',
+            wakeMode: 'now',
+            payload: { kind: 'agentTurn', message: HEARTBEAT_MESSAGE },
+            delivery: { mode: 'announce', channel: 'last' },
+        });
+        writeMarker(markerPath, { ensuredAt: new Date().toISOString(), created: HEARTBEAT_CRON_NAME });
+        log(`Heartbeat cron: created (${HEARTBEAT_CRON_NAME}, every 15m)`);
+        return 'created';
+    }
+    catch (err) {
+        log(`Heartbeat cron: skipped (${err instanceof Error ? err.message.split('\n')[0] : String(err)})`);
+        return 'failed';
+    }
+}
+function writeMarker(markerPath, data) {
+    mkdirSync(dirname(markerPath), { recursive: true });
+    writeFileSync(markerPath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+}

package/assets/bridge/providers/gateway.d.ts

@@ -29,6 +29,8 @@ export declare class GatewayProvider implements OpenClawProvider {
     private agentIdentity;
     /** Emit the one-time rollout probe (gateway response shape) only on the first attempt. */
     private loggedAgentIdentityProbe;
+    /** One-shot latch for the boot-time heartbeat-cron ensure (re-armed on failure). */
+    private heartbeatCronEnsureStarted;
     /** Live heartbeat cadence (seconds), read from the OpenClaw cron store; cached 60s. */
     private heartbeatSeconds?;
     private heartbeatReadAtMs;

package/assets/bridge/providers/gateway.js

@@ -11,16 +11,26 @@ import { GatewayWsClient } from '../gateway/gateway-ws-client.js';
 import { discoverTools } from '../gateway/tool-discovery.js';
 import { EventParser, mapCcxtBalance, mapCcxtOrder, extractLiquidationFields, extractBracketField, } from '../gateway/event-parser.js';
 import { Poller } from '../gateway/poller.js';
+import { ensureHeartbeatCron } from '../gateway/heartbeat-cron.js';
 import { computeEquity as _computeEquity, computePositionNotional as _computePositionNotional, computeRiskMetrics as _computeRiskMetrics, DEFAULT_RISK_LIMITS, } from './risk-calculator.js';
 import { executeKill as _executeKill, executeFlatten as _executeFlatten, executePause as _executePause, executeResume as _executeResume, } from './emergency-commands.js';
 import { executeSetTradingMode, executeGetBracketConfig, executeSetBracketRequirement, executeSetExchangeCredentials, executeTestExchangeCredentials, executeClearExchangeCredentials, } from './onboarding-commands.js';
 const TAG = 'gateway';
-// ---- Session NAV persistence ----
-// Persists sessionStartNav per date so Day P&L survives skill restarts.
-const SESSION_NAV_FILENAME = 'session-nav.json';
+// ---- Day-start NAV persistence ----
+// Persists sessionStartNav (the UTC-day P&L anchor) per date so Day P&L
+// survives skill restarts. The file was historically named session-nav.json;
+// renamed to day-start-nav.json 2026-07-22 — "session" was a misnomer (the
+// value anchors the trading DAY, not any auth/session state) and tripped
+// ClawHub's sensitive-file-read heuristic. Reads fall back to the legacy name
+// once, writes go to the new name only.
+const DAY_NAV_FILENAME = 'day-start-nav.json';
+const LEGACY_DAY_NAV_FILENAME = 'session-nav.json';
 const TRADING_MODE_FILENAME = 'trading-mode.json';
-function getSessionNavPath() {
-    return join(homedir(), '.openclaw', 'workspace', SESSION_NAV_FILENAME);
+function getDayNavPath() {
+    return join(homedir(), '.openclaw', 'workspace', DAY_NAV_FILENAME);
+}
+function getLegacyDayNavPath() {
+    return join(homedir(), '.openclaw', 'workspace', LEGACY_DAY_NAV_FILENAME);
 }
 function getTradingModePath() {
     return join(homedir(), '.openclaw', 'workspace', TRADING_MODE_FILENAME);
@@ -40,17 +50,20 @@ export function shouldAnchorSessionNav(args) {
     return args.mode === 'PAPER' && args.sessionDate !== args.today; // paper midnight rollover
 }
 function loadSessionStartNav() {
-    try {
-        const raw = readFileSync(getSessionNavPath(), 'utf-8');
-        const data = JSON.parse(raw);
-        if (data.date === todayDateStr() && typeof data.sessionStartNav === 'number' && data.sessionStartNav > 0) {
-            return data.sessionStartNav;
+    for (const path of [getDayNavPath(), getLegacyDayNavPath()]) {
+        try {
+            const raw = readFileSync(path, 'utf-8');
+            const data = JSON.parse(raw);
+            if (data.date === todayDateStr() && typeof data.sessionStartNav === 'number' && data.sessionStartNav > 0) {
+                return data.sessionStartNav;
+            }
+            return null; // Different day or invalid — don't let a stale legacy file shadow it
+        }
+        catch {
+            /* missing or corrupt — try the legacy name */
         }
-        return null; // Different day or invalid
-    }
-    catch {
-        return null; // File doesn't exist or is corrupt
     }
+    return null;
 }
 /**
  * Persisted across skill restarts so the FIRST snapshot the gateway emits
@@ -90,7 +103,11 @@ function saveSessionStartNav(nav) {
         const dir = join(homedir(), '.openclaw', 'workspace');
         mkdirSync(dir, { recursive: true });
         const data = { date: todayDateStr(), sessionStartNav: nav };
-        writeFileSync(getSessionNavPath(), JSON.stringify(data, null, 2), 'utf-8');
+        writeFileSync(getDayNavPath(), JSON.stringify(data, null, 2), 'utf-8');
+        try {
+            unlinkSync(getLegacyDayNavPath());
+        }
+        catch { /* legacy file already gone */ }
     }
     catch (err) {
         logger.warn(TAG, `Failed to save session NAV: ${err instanceof Error ? err.message : String(err)}`);
@@ -122,6 +139,8 @@ export class GatewayProvider {
     agentIdentity = {};
     /** Emit the one-time rollout probe (gateway response shape) only on the first attempt. */
     loggedAgentIdentityProbe = false;
+    /** One-shot latch for the boot-time heartbeat-cron ensure (re-armed on failure). */
+    heartbeatCronEnsureStarted = false;
     /** Live heartbeat cadence (seconds), read from the OpenClaw cron store; cached 60s. */
     heartbeatSeconds;
     heartbeatReadAtMs = 0;
@@ -1070,6 +1089,24 @@ export class GatewayProvider {
         // every (re)connect so a model swap — which restarts the gateway and drops
         // this socket — is reflected on the next handshake.
         void this.refreshAgentIdentity();
+        // Ensure the heartbeat cron exists — via gateway RPC, once per install
+        // (marker-file guarded; a deliberate operator delete is never resurrected).
+        // Lives here instead of setup because setup runs before the gateway is up.
+        if (!this.heartbeatCronEnsureStarted) {
+            this.heartbeatCronEnsureStarted = true;
+            const ws = this.wsClient;
+            if (ws) {
+                void ensureHeartbeatCron({
+                    rpc: ws,
+                    markerPath: join(homedir(), '.openclaw', 'workspace', 'heartbeat-cron-ensured.json'),
+                    log: (msg) => logger.info(TAG, msg),
+                }).then((outcome) => {
+                    // A transient failure retries on the next (re)connect, not just next boot.
+                    if (outcome === 'failed')
+                        this.heartbeatCronEnsureStarted = false;
+                });
+            }
+        }
         // Start periodic agent state emission (every 5s)
         if (!this.agentStateInterval) {
             this.agentStateInterval = setInterval(() => {
@@ -1589,7 +1626,11 @@ export class GatewayProvider {
                     this.hasReceivedPositions = false;
                     this.pendingEmptyPoll = false;
                     try {
-                        unlinkSync(getSessionNavPath());
+                        unlinkSync(getDayNavPath());
+                    }
+                    catch { /* ok if missing */ }
+                    try {
+                        unlinkSync(getLegacyDayNavPath());
                     }
                     catch { /* ok if missing */ }
                     logger.info(TAG, `Session start NAV reset on mode change (${prevMode} → ${this.tradingMode})`);

package/assets/bridge/setup.js

@@ -1,7 +1,6 @@
 // Interactive setup helper for the ReefClaw skill.
 // Validates token format, tests relay connection, saves to OpenClaw config.
 import WebSocket from 'ws';
-import { execSync } from 'node:child_process';
 import { writeOpenClawConfig } from './config.js';
 import { logger } from './logger.js';
 const TAG = 'setup';
@@ -149,8 +148,12 @@ export async function runSetup(tokenOrBundle, userId, relayUrl) {
     }
     // Save to config
     writeOpenClawConfig(token, resolvedUserId, resolvedRelayUrl);
-    // Create heartbeat cron job if none exists
-    ensureHeartbeatCron();
+    // Heartbeat cron is ensured by the bridge at first gateway connect (via
+    // cron.list/cron.add RPC — see gateway/heartbeat-cron.ts). Setup can't do it:
+    // the gateway isn't running yet at this point, which is also why the old
+    // setup-time shell-out to the openclaw CLI silently no-op'd on fresh
+    // installs (the CLI's cron commands are gateway RPC clients too).
+    console.log('  Heartbeat cron: created automatically when the agent first connects (every 15m)');
     console.log('');
     console.log('  Setup complete! Token saved to ~/.openclaw/config.json');
     console.log('');
@@ -161,54 +164,6 @@ export async function runSetup(tokenOrBundle, userId, relayUrl) {
     console.log('    4. Your agent checks the market every 15 minutes (adjustable via chat)');
     console.log('');
 }
-// ---- Heartbeat cron ----
-/**
- * Ensures a heartbeat cron job exists for ReefClaw.
- * Checks `openclaw cron list` for an existing job with "reefclaw" in the name.
- * If none found, creates one with 15m default interval.
- * Non-fatal — if openclaw CLI isn't available or cron fails, setup still succeeds.
- */
-function ensureHeartbeatCron() {
-    try {
-        // Check if a reefclaw cron already exists
-        const listOutput = execSync('openclaw cron list --json 2>/dev/null', {
-            encoding: 'utf-8',
-            timeout: 15_000,
-        });
-        // Look for any job with "reefclaw" in the name
-        try {
-            const jobs = JSON.parse(listOutput);
-            const existing = (Array.isArray(jobs) ? jobs : []).find((j) => j.name?.toLowerCase().includes('reefclaw'));
-            if (existing) {
-                console.log(`  Heartbeat cron: already exists (${existing.name})`);
-                return;
-            }
-        }
-        catch {
-            // JSON parse failed — maybe not JSON output, check raw text
-            if (listOutput.toLowerCase().includes('reefclaw')) {
-                console.log('  Heartbeat cron: already exists');
-                return;
-            }
-        }
-        // No existing job — create one
-        console.log('  Creating heartbeat cron (every 15m)...');
-        execSync('openclaw cron add --name reefclaw-heartbeat --every 15m --session isolated ' +
-            "--message 'Heartbeat. Run SESSION START mandatory checks, then the full Decision Loop (Steps 0-9) from SKILL.md. Check tradingMode from fetch_balance — it is your source of truth for paper vs live. Use tools in parallel where possible.' 2>&1", { encoding: 'utf-8', timeout: 15_000 });
-        console.log('  Heartbeat cron: created (every 15 minutes)');
-        console.log('  Tip: Ask your agent "change heartbeat to 10 minutes" to adjust');
-    }
-    catch (err) {
-        // Non-fatal — user can create cron manually or agent can create it on first session
-        const msg = err instanceof Error ? err.message : String(err);
-        if (msg.includes('not found') || msg.includes('ENOENT')) {
-            console.log('  Heartbeat cron: skipped (openclaw CLI not in PATH)');
-        }
-        else {
-            console.log(`  Heartbeat cron: skipped (${msg.split('\n')[0]})`);
-        }
-    }
-}
 function printSetupInstructions() {
     console.log('  To connect your OpenClaw agent to ReefClaw:');
     console.log('');

package/dist/deps.js

@@ -5,10 +5,10 @@
 import { writeFileSync, cpSync, mkdirSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { run } from './exec.js';
-export function writePackageJson(dir, name, deps, extra = {}) {
+export function writePackageJson(dir, name, deps, extra = {}, version = '0.1.0') {
     const pkg = {
         name,
-        version: '0.1.0',
+        version,
         private: true,
         type: 'module',
         main: 'index.js',

package/dist/plugin.js

@@ -1,6 +1,7 @@
 // Install + register the ReefClaw trading plugin (reefclaw-paper-trading) into
 // the user's OpenClaw. Mirrors deploy-full.py: place dist, install deps, vendor
 // shared, then `openclaw plugins install --link`.
+import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { PLUGIN_DIR, assetsDir, ASSET_PLUGIN, ASSET_SHARED } from './paths.js';
 import { copyAsset, writePackageJson, npmInstall, vendorShared } from './deps.js';
@@ -8,6 +9,21 @@ import { run, which } from './exec.js';
 import { step, ok, info, warn, fail } from './ui.js';
 // Plugin runtime deps (mirror plugin/package.json). ws + ccxt; ccxt is large.
 const PLUGIN_DEPS = { ccxt: '^4.4.0', ws: '^8.18.0' };
+/** Version for the placed package.json — read from the bundled manifest (which
+ *  bundle-assets stamps from the published plugin version). Falls back to the
+ *  historical 0.1.0 placeholder so a missing/old manifest can't break installs. */
+function readBundledManifestVersion(pluginDir) {
+    try {
+        const manifest = JSON.parse(readFileSync(join(pluginDir, 'openclaw.plugin.json'), 'utf-8'));
+        if (typeof manifest.version === 'string' && manifest.version.length > 0) {
+            return manifest.version;
+        }
+    }
+    catch {
+        /* fall through to placeholder */
+    }
+    return '0.1.0';
+}
 export function installPlugin() {
     step('Installing the ReefClaw trading plugin');
     const assets = assetsDir();
@@ -17,9 +33,10 @@ export function installPlugin() {
     // (2026.6+ hard-fails without it). The placed dir holds the built dist at top
     // level, so the entry is ./index.js — NOT ./src/index.ts like the repo's
     // plugin/package.json (see CLAUDE.md "dist/package.json's openclaw entry").
-    writePackageJson(PLUGIN_DIR, 'reefclaw-paper-trading', PLUGIN_DEPS, {
-        openclaw: { extensions: ['./index.js'] },
-    });
+    // Version comes from the bundled manifest (stamped at bundle time from the
+    // published plugin version) so package.json and openclaw.plugin.json agree —
+    // the same package/manifest coherence ClawHub validates on the npm channel.
+    writePackageJson(PLUGIN_DIR, 'reefclaw-paper-trading', PLUGIN_DEPS, { openclaw: { extensions: ['./index.js'] } }, readBundledManifestVersion(PLUGIN_DIR));
     info('installing plugin dependencies (this can take a minute — ccxt is large)…');
     if (!npmInstall(PLUGIN_DIR)) {
         warn('npm install reported a problem; the plugin may still work if deps resolved.');
@@ -31,16 +48,27 @@ export function installPlugin() {
     const cli = which('openclaw');
     if (!cli) {
         fail('the `openclaw` CLI is not on your PATH — cannot register the plugin.');
-        info(`Once OpenClaw is on PATH, run:  openclaw plugins install --link ${PLUGIN_DIR}`);
+        info(`Once OpenClaw is on PATH, run:  openclaw plugins install --force --link ${PLUGIN_DIR}`);
         return { registered: false };
     }
+    // --force is REQUIRED on openclaw >= 2026.7.2 (issue #216): non-ClawHub
+    // sources (incl. local paths) need an acknowledgement, and in a non-TTY
+    // context the install is cancelled with "rerun with --force" instead of
+    // prompting. Acknowledging is correct here — the "source" is our own bundled
+    // plugin the user explicitly chose to install by running this installer.
+    // On <= 2026.7.1, --force only means overwrite-an-existing-install, which
+    // also makes installer re-runs idempotent instead of failing on the exists
+    // check. Verified against both dists' plugins-install command + the beta's
+    // confirmNonClawHubInstall (install cancelled when !TTY && !force).
     info('registering the plugin with OpenClaw…');
-    const r = run('openclaw', ['plugins', 'install', '--link', PLUGIN_DIR], { timeoutMs: 300_000 });
+    const r = run('openclaw', ['plugins', 'install', '--force', '--link', PLUGIN_DIR], {
+        timeoutMs: 300_000,
+    });
     if (!r.ok) {
-        warn('`openclaw plugins install --link` returned non-zero:');
+        warn('`openclaw plugins install --force --link` returned non-zero:');
         if (r.stderr.trim())
             info(r.stderr.trim().split('\n').slice(-3).join('\n'));
-        info(`Retry manually:  openclaw plugins install --link ${PLUGIN_DIR}`);
+        info(`Retry manually:  openclaw plugins install --force --link ${PLUGIN_DIR}`);
         return { registered: false };
     }
     ok('plugin registered with OpenClaw');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reefclaw/connect",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "description": "One-command installer that connects your OpenClaw agent to ReefClaw (paper trading, no exchange keys).",
   "type": "module",
   "bin": {

package/assets/plugin/audit/mode-transition-audit.d.ts

@@ -1,11 +0,0 @@
-import type { TradingMode } from '../types.js';
-export interface ModeTransitionAuditEntry {
-    ts: string;
-    previousMode: TradingMode;
-    targetMode: TradingMode;
-    acknowledged: boolean;
-    ok: boolean;
-    reason?: string;
-    testnet?: boolean;
-}
-export declare function recordModeTransition(entry: Omit<ModeTransitionAuditEntry, 'ts'>, pluginId?: string): void;

package/assets/plugin/audit/mode-transition-audit.js

@@ -1,29 +0,0 @@
-// Mode-transition audit — append-only JSONL record of every set_trading_mode call.
-//
-// Written BEFORE the adapter swap (so even a crashed transition leaves a trail)
-// and updated with the outcome. Intended for post-incident review and regulatory
-// defence ("the operator acknowledged the LIVE transition at 2026-04-20T14:32:11Z").
-//
-// Path: ~/.openclaw/plugins/<pluginId>/mode-transitions.jsonl
-// Append-only; never truncated. One JSON object per line.
-import { appendFileSync, existsSync, mkdirSync } from 'node:fs';
-import { join } from 'node:path';
-import { logger, formatError } from '../logger.js';
-import { resolvePluginsBaseDir } from '../util/plugin-paths.js';
-const TAG = 'mode-audit';
-function resolvePath(pluginId) {
-    const dir = join(resolvePluginsBaseDir(), pluginId ?? 'reefclaw-paper-trading');
-    if (!existsSync(dir))
-        mkdirSync(dir, { recursive: true });
-    return join(dir, 'mode-transitions.jsonl');
-}
-export function recordModeTransition(entry, pluginId) {
-    const full = { ts: new Date().toISOString(), ...entry };
-    try {
-        appendFileSync(resolvePath(pluginId), JSON.stringify(full) + '\n', 'utf8');
-        logger.info(TAG, `${full.previousMode} → ${full.targetMode} ok=${full.ok} ack=${full.acknowledged}`);
-    }
-    catch (err) {
-        logger.error(TAG, `Failed to write audit entry: ${formatError(err)}`);
-    }
-}

package/assets/plugin/balance-utils.d.ts

@@ -1,36 +0,0 @@
-import type { CcxtBalance } from './types.js';
-/**
- * Read the total quote-currency balance from a CCXT balance map.
- *
- * Uses the PRIMARY funded currency only — whichever of USDT/USDC has
- * the larger balance. Summing both was incorrect because Binance
- * cross-margin accounting reports position margin/value as a phantom
- * balance in the settlement currency (e.g., opening an ATOM/USDT
- * position with a USDC-funded account creates a USDT "balance" entry
- * equal to the position's notional, inflating getQuoteBalance by the
- * position value and causing the KPI to double-count).
- *
- * For wallet/equity/NAV reads on Binance Futures, prefer
- * `getQuoteWalletBalance(balance)` — it handles BNFCR.
- */
-export declare function getQuoteBalance(balanceMap: Record<string, number> | undefined): number;
-/**
- * Read the effective wallet-equivalent quote balance from a Binance Futures
- * fetchBalance response, including the BNFCR realized-PnL accumulator.
- *
- * Why this exists: Binance multi-asset accounts settle realized PnL into
- * BNFCR (negative when net-loss, positive when net-gain). CCXT's `total`
- * map carries `marginBalance` (= walletBalance + uPnl), so the BNFCR line
- * mixes uPnl into the total, which double-counts when the caller adds
- * position uPnl on top. This helper reads `info.assets[i].walletBalance`
- * directly, which excludes uPnl by construction.
- *
- * Returns max(USDT_wallet, USDC_wallet) + BNFCR_wallet. BNFCR is added
- * (not max'd) because it is independent of the funded stablecoin — a
- * USDC-funded account with cumulative losses shows USDC unchanged plus
- * BNFCR negative; the user's true wallet is the sum.
- *
- * Falls back to `getQuoteBalance(balance.total)` when `info.assets` is
- * absent (mock balances in unit tests, non-Binance exchanges).
- */
-export declare function getQuoteWalletBalance(balance: CcxtBalance | null | undefined): number;

package/assets/plugin/balance-utils.js

@@ -1,98 +0,0 @@
-// Utility for reading quote-currency balance from CCXT balance objects.
-// Binance USDⓈ-M Futures settles in USDT or USDC — accounts may hold either or both.
-// On multi-asset accounts a third asset, BNFCR, accumulates realized PnL as a
-// signed wallet line (negative = cumulative loss, positive = cumulative gain).
-/**
- * Read the total quote-currency balance from a CCXT balance map.
- *
- * Uses the PRIMARY funded currency only — whichever of USDT/USDC has
- * the larger balance. Summing both was incorrect because Binance
- * cross-margin accounting reports position margin/value as a phantom
- * balance in the settlement currency (e.g., opening an ATOM/USDT
- * position with a USDC-funded account creates a USDT "balance" entry
- * equal to the position's notional, inflating getQuoteBalance by the
- * position value and causing the KPI to double-count).
- *
- * For wallet/equity/NAV reads on Binance Futures, prefer
- * `getQuoteWalletBalance(balance)` — it handles BNFCR.
- */
-export function getQuoteBalance(balanceMap) {
-    if (!balanceMap)
-        return 0;
-    const usdt = balanceMap.USDT ?? 0;
-    const usdc = balanceMap.USDC ?? 0;
-    // Use whichever currency has the larger wallet balance (the funded one).
-    // If both are zero, return 0. If both are funded, use the larger.
-    return Math.max(usdt, usdc);
-}
-/**
- * Read the effective wallet-equivalent quote balance from a Binance Futures
- * fetchBalance response, including the BNFCR realized-PnL accumulator.
- *
- * Why this exists: Binance multi-asset accounts settle realized PnL into
- * BNFCR (negative when net-loss, positive when net-gain). CCXT's `total`
- * map carries `marginBalance` (= walletBalance + uPnl), so the BNFCR line
- * mixes uPnl into the total, which double-counts when the caller adds
- * position uPnl on top. This helper reads `info.assets[i].walletBalance`
- * directly, which excludes uPnl by construction.
- *
- * Returns max(USDT_wallet, USDC_wallet) + BNFCR_wallet. BNFCR is added
- * (not max'd) because it is independent of the funded stablecoin — a
- * USDC-funded account with cumulative losses shows USDC unchanged plus
- * BNFCR negative; the user's true wallet is the sum.
- *
- * Falls back to `getQuoteBalance(balance.total)` when `info.assets` is
- * absent (mock balances in unit tests, non-Binance exchanges).
- */
-export function getQuoteWalletBalance(balance) {
-    if (!balance)
-        return 0;
-    // Prefer Binance's own account-level wallet aggregate when present.
-    // `/fapi/v3/account` (CCXT passes it through verbatim at `info`) returns
-    // `totalWalletBalance` — in Multi-Assets Mode this is the USD-denominated
-    // sum across all margin assets, with each non-USD collateral valued at
-    // Binance's live index price (verified against developers.binance.com →
-    // Account Information V3, 2026-05-16). It also excludes uPnL by
-    // construction (marginBalance = walletBalance + uPnL), matching this
-    // function's "wallet, uPnL added by caller" contract.
-    //
-    // Why this beats the per-asset reconstruction below: summing
-    // `max(USDT,USDC) + BNFCR` values USDC at FACE 1.0000, but Binance values
-    // USDC collateral at the live USDC/USD index (~0.9998). That made the
-    // dashboard wallet permanently ~$0.2 high vs the Binance app on this
-    // account (always-on, same-sign, slowly varying with the USDC peg —
-    // 2026-05-16 "figures slightly off always"). totalWalletBalance is the
-    // exact number the app's Futures "Wallet Balance" shows. The read path is
-    // already REST (`LiveAdapter.getBalance` → `fetchBalance()` every poll),
-    // so this is zero freshness regression — same cadence, correct value.
-    const info = balance?.info;
-    if (info && info.totalWalletBalance != null) {
-        const twb = parseFloat(String(info.totalWalletBalance));
-        if (Number.isFinite(twb))
-            return twb;
-    }
-    // Fallback (no Binance aggregate — non-Binance exchange, mock balances in
-    // unit tests, or a WS-store-derived balance object): the legacy
-    // face-value per-asset reconstruction. Carries the documented ~USDC-index
-    // drift but is the best available when the aggregate is absent.
-    const assets = balance?.info?.assets;
-    if (!Array.isArray(assets))
-        return getQuoteBalance(balance.total);
-    let usdt = 0;
-    let usdc = 0;
-    let bnfcr = 0;
-    for (const a of assets) {
-        if (!a || typeof a.asset !== 'string')
-            continue;
-        const wb = parseFloat(String(a.walletBalance ?? 0));
-        if (!Number.isFinite(wb))
-            continue;
-        if (a.asset === 'USDT')
-            usdt = wb;
-        else if (a.asset === 'USDC')
-            usdc = wb;
-        else if (a.asset === 'BNFCR')
-            bnfcr = wb;
-    }
-    return Math.max(usdt, usdc) + bnfcr;
-}

package/assets/plugin/ccxt/binance-ban-gate.d.ts

@@ -1,47 +0,0 @@
-/** Thrown by `assertNotBanned` while the gate is closed. Carries the
- *  remaining cooldown so callers/telemetry can reason about it. Methods
- *  catch this in their existing catch block — it is NOT meant to escape
- *  the API layer with special handling; it degrades to the method's normal
- *  failure contract. */
-export declare class BinanceBannedError extends Error {
-    readonly retryAfterMs: number;
-    constructor(retryAfterMs: number, context: string);
-}
-/** Thrown by the proactive weight pacer. Subclass of BinanceBannedError so
- *  every `instanceof BinanceBannedError` check and every method's existing
- *  catch keep working unchanged — it degrades to the same null/[]/throw
- *  contract (treated exactly like a transient fetch failure). The distinct
- *  name lets journal/telemetry tell prevention apart from a real IP ban. */
-export declare class BinanceWeightPacedError extends BinanceBannedError {
-    constructor(retryAfterMs: number, context: string);
-}
-/** Fast pre-flight check. Call as the first line inside a Binance call's
- *  try-block. Throws `BinanceBannedError` (no network) while the gate is
- *  open. */
-export declare function assertNotBanned(context: string): void;
-/** Inspect a failed call's error and arm/extend the gate on a Binance
- *  rate-limit signal. Non-rate-limit errors are ignored (normal transient
- *  handling stays in the caller). Safe to call with any error shape. */
-export declare function noteBinanceError(err: unknown): void;
-/** Relax the soft-429 ladder after a clean call. (A hard 418 window is NOT
- *  shortened by this — only Binance's stated expiry clears it.) */
-export declare function noteSuccess(): void;
-/** Reconcile the local weight estimate against Binance truth from a response
- *  header (`x-mbx-used-weight-1m`). Best-effort: callers pass whatever header
- *  bag they have; absent/garbage values are ignored. The local estimate
- *  leads (counts in-flight calls Binance hasn't tallied yet), so we take the
- *  MAX within the window — never let a lagging header lower our guard. A
- *  header far BELOW the estimate means Binance's minute rolled; re-anchor the
- *  window to Binance's clock so we don't shed for a stale local total. */
-export declare function noteResponseWeight(headers: Record<string, string> | undefined | null): void;
-/** Test/diagnostic helper — current gate state. */
-export declare function getBanGateState(): {
-    banUntilMs: number;
-    remainingMs: number;
-    rateLimitStep: number;
-    weightUsed: number;
-    weightCeiling: number;
-    cosmeticCeiling: number;
-};
-/** Test-only reset. Not used in production code paths. */
-export declare function __resetBanGateForTests(): void;