@reefclaw/openclaw-plugin 0.1.23 → 0.1.24

package/bridge/providers/emergency-commands.js

@@ -219,6 +219,97 @@ export async function executeFlatten(ctx, cachedPositions) {
     const details = `Closed ${succeeded}/${openPositions.length} positions`;
     return { action: 'flatten', executed: true, timestamp: new Date().toISOString(), details };
 }
+const PROPOSAL_CANCEL_TIMEOUT_MS = 3_000;
+/**
+ * Cancel the tenant's outstanding approval-mode proposals because trading is
+ * being halted.
+ *
+ * Kill / Flatten / Pause previously left pending proposals alone, so an
+ * approval landing seconds after a kill still opened a brand-new position —
+ * hard expiry was the only bound (design doc §10 row 13). The plugin holds no
+ * halt state and there is no skill→plugin channel for one, so the halt is
+ * applied at the webapp, where proposals actually live. That is sufficient:
+ * the plugin's listener can only fire rows returned by /pending-decisions,
+ * which requires status='approved', and a cancelled row can never be approved.
+ *
+ * ★ FAIL-SOFT, NEVER FAIL-BLOCKING. This must not delay or abort a kill. Any
+ * error returns a *reported* failure rather than throwing — a halt that
+ * cancelled positions but couldn't confirm proposals is still a halt, and the
+ * operator needs to be told which half is uncertain rather than getting a
+ * clean green.
+ *
+ * ★ Proposals a listener already CLAIMED are not cancelled — a claim is taken
+ * immediately before order submission, so such a row may already be live at
+ * the exchange. We surface the count instead of asserting a cancellation we
+ * cannot guarantee.
+ */
+export async function cancelPendingProposals(operatorToken, reason, fetchImpl = fetch) {
+    const none = { cancelled: 0, inFlight: 0, detail: null };
+    if (!operatorToken)
+        return none;
+    // www is load-bearing: reefclaw.com 307-redirects and Node fetch strips the
+    // Authorization header on a cross-origin redirect (same as bridge.ts).
+    const base = (process.env.REEFCLAW_API_URL || 'https://www.reefclaw.com').replace(/\/$/, '');
+    try {
+        const res = await fetchImpl(`${base}/api/internal/proposed_orders/cancel-all`, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${operatorToken}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({ reason }),
+            signal: AbortSignal.timeout(PROPOSAL_CANCEL_TIMEOUT_MS),
+        });
+        if (!res.ok) {
+            logger.warn(TAG, `proposal cancel-all returned ${res.status} (reason=${reason})`);
+            return {
+                ...none,
+                detail: `could not confirm pending trade proposals were cancelled (HTTP ${res.status}) — check the dashboard`,
+            };
+        }
+        const body = (await res.json());
+        const cancelled = typeof body.cancelled === 'number' ? body.cancelled : 0;
+        const inFlightRows = Array.isArray(body.inFlight) ? body.inFlight : [];
+        const parts = [];
+        if (cancelled > 0) {
+            parts.push(`${cancelled} pending trade proposal${cancelled === 1 ? '' : 's'} cancelled`);
+        }
+        if (inFlightRows.length > 0) {
+            const named = inFlightRows
+                .slice(0, 3)
+                .map((r) => `${r.symbol ?? '?'} ${r.side ?? '?'}`)
+                .join(', ');
+            parts.push(`⚠ ${inFlightRows.length} approved proposal${inFlightRows.length === 1 ? '' : 's'} ` +
+                `already executing and could NOT be cancelled (${named}) — verify on the exchange`);
+        }
+        if (cancelled > 0 || inFlightRows.length > 0) {
+            logger.info(TAG, `proposal cancel-all (${reason}): cancelled=${cancelled} inFlight=${inFlightRows.length}`);
+        }
+        return {
+            cancelled,
+            inFlight: inFlightRows.length,
+            detail: parts.length > 0 ? parts.join('; ') : null,
+        };
+    }
+    catch (err) {
+        // Timeout / network / malformed body. Report, never throw — the halt itself
+        // must complete regardless.
+        logger.warn(TAG, `proposal cancel-all failed (reason=${reason}): ${err instanceof Error ? err.message : String(err)}`);
+        return {
+            ...none,
+            detail: 'could not reach the server to cancel pending trade proposals — check the dashboard',
+        };
+    }
+}
+/** Fold a proposal-cancel summary into an EmergencyResult's details line. */
+export function withProposalDetail(result, summary) {
+    if (!summary.detail)
+        return result;
+    return {
+        ...result,
+        details: result.details ? `${result.details}. ${summary.detail}` : summary.detail,
+    };
+}
 // ---- Sync commands (pure state transitions) ----
 /**
  * Pause: prevent new entries, keep existing positions.

package/bridge/providers/gateway.d.ts

@@ -2,6 +2,7 @@ import type { OpenClawProvider, ProviderEvents, ProviderEventName, ExchangeCrede
 import type { EmergencyAction, ReconciliationSnapshot, TradingMode } from '../types.js';
 import type { GatewayConfig } from '../gateway/gateway-config.js';
 import { type GetBracketConfigOutcome, type SetBracketRequirementOutcome, type BracketRequirementFlag, type SetTradingModeOutcome, type SetExchangeCredentialsOutcome, type TestExchangeCredentialsOutcome, type ClearExchangeCredentialsOutcome } from './onboarding-commands.js';
+import { type ConnectorUpdateOutcome } from './connector-update.js';
 /** Decide whether the session-start-NAV anchor needs to be (re)set. Pure so it
  *  can be unit-tested without the full provider. Returns true when the anchor
  *  has never been set, OR — for PAPER only — when it belongs to a previous UTC
@@ -239,6 +240,28 @@ export declare class GatewayProvider implements OpenClawProvider {
             v: number;
         };
     }): Promise<HlSubmitApprovalOutcome>;
+    /**
+     * Operator-only. Update the ReefClaw connector on this box to the latest
+     * published version.
+     *
+     * Runs `npx -y @reefclaw/connect@latest` over the gateway's PTY. There is no
+     * command/version/args parameter and there never should be — the whole
+     * security argument for this feature is that the string is a constant (see
+     * providers/connector-update.ts).
+     *
+     * The installer restarts the gateway when it finishes, which kills both the
+     * PTY and this process's own transport. That is the SUCCESS path: we report
+     * `restarting` and the dashboard waits for the reconnect.
+     */
+    updateConnector(args: {
+        acknowledgeOpenPositions?: boolean;
+    }): Promise<ConnectorUpdateOutcome>;
+    /**
+     * Poll the PTY and emit progress until the command finishes or the gateway
+     * restart takes the session (and us) down.
+     */
+    private streamConnectorUpdate;
+    private emitConnectorUpdate;
     /** Operator-only. Approval/balance status of the provisioned HL wallet. */
     getHlAgentWalletStatus(): Promise<HlAgentWalletStatusOutcome>;
     /** Operator-only. Read the current bracket-orders config from the plugin. */
@@ -414,7 +437,9 @@ export declare class GatewayProvider implements OpenClawProvider {
      * hardcoded 1800 and `agents.defaults.heartbeat` are both stale/wrong once
      * the operator edits the cron (`openclaw cron ... --every 15m`). Drives both
      * the "beat every Nm" label and the unresponsive (2×) threshold. Cached 60s;
-     * returns undefined (caller defaults to 1800) when unreadable.
+     * returns undefined (caller defaults to 1800) when unreadable. On 2026.7.x
+     * (no jobs.json) the value is fed by refreshHeartbeatHealth() from the
+     * cron.list RPC instead; the file read here is the legacy fallback.
      */
     private resolveHeartbeatSeconds;
     /** Build agent state from internal fields (used by both emitAgentState and getSnapshot). */

package/bridge/providers/gateway.js

@@ -16,8 +16,9 @@ import { Poller } from '../gateway/poller.js';
 import { ensureHeartbeatCron, isHeartbeatLikeName } from '../gateway/heartbeat-cron.js';
 import { parseIdentityName } from '../utils/identity-name.js';
 import { computeEquity as _computeEquity, computePositionNotional as _computePositionNotional, computeRiskMetrics as _computeRiskMetrics, DEFAULT_RISK_LIMITS, DRAWDOWN_ZONE_THRESHOLDS, TENANT_LIMIT_BOUNDS, boundedNum, validateDrawdownLadder, } from './risk-calculator.js';
-import { executeKill as _executeKill, executeFlatten as _executeFlatten, executePause as _executePause, executeResume as _executeResume, } from './emergency-commands.js';
+import { executeKill as _executeKill, executeFlatten as _executeFlatten, executePause as _executePause, executeResume as _executeResume, cancelPendingProposals, withProposalDetail, } from './emergency-commands.js';
 import { executeSetTradingMode, executeGetBracketConfig, executeSetBracketRequirement, executeSetExchangeCredentials, executeTestExchangeCredentials, executeClearExchangeCredentials, executeProvisionHlAgentWallet, executeHlAgentWalletStatus, executeSubmitHlAgentApproval, } from './onboarding-commands.js';
+import { startConnectorUpdate, readTerminalText, closeTerminal, classifyTransportLoss, isCredibleCompletion, parseDoneSentinel, } from './connector-update.js';
 const TAG = 'gateway';
 // ---- Day-start NAV persistence ----
 // Persists sessionStartNav (the UTC-day P&L anchor) per date so Day P&L
@@ -304,6 +305,7 @@ export class GatewayProvider {
         chatMessageChunk: new Set(),
         chatMessageEnd: new Set(),
         chatStreamingKeepAlive: new Set(),
+        connectorUpdate: new Set(),
         marketStructure: new Set(),
         cryptoMetrics: new Set(),
         volumeAnalysis: new Set(),
@@ -588,6 +590,13 @@ export class GatewayProvider {
     // ---- Emergency command implementations (delegated to emergency-commands.ts) ----
     async executeKill() {
         const ctx = { http: this.http, toolMap: this.toolMap, symbol: this.config.symbol };
+        // Approval-mode proposals are cancelled CONCURRENTLY with the exchange
+        // work, started first: a pending proposal approved mid-kill would open a
+        // brand-new position while we cancel orders. Kicking it off here (rather
+        // than awaiting it before the kill) means it wins essentially every race
+        // without adding a single millisecond to the kill path. Fail-soft — it
+        // reports into `details`, it can never throw or block.
+        const proposalCancel = cancelPendingProposals(this.config.connectionToken, 'kill_switch');
         // Pass a FRESH, all-symbols order snapshot so Kill cancels every working
         // order portfolio-wide and correctly identifies (and preserves) protective
         // reduceOnly brackets. On a failed fresh read Kill still runs against the
@@ -597,21 +606,28 @@ export class GatewayProvider {
         const result = await _executeKill(ctx, freshOrders, this.openOrders);
         this.agentMode = 'STOPPED';
         this.emitAgentState();
-        return result;
+        return withProposalDetail(result, await proposalCancel);
     }
     async executeFlatten() {
         const ctx = { http: this.http, toolMap: this.toolMap, symbol: this.config.symbol };
+        // Started before the closes, awaited after — see executeKill.
+        const proposalCancel = cancelPendingProposals(this.config.connectionToken, 'flatten');
         const result = await _executeFlatten(ctx, this.positions);
         this.agentMode = 'STOPPED';
         this.emitAgentState();
-        return result;
+        return withProposalDetail(result, await proposalCancel);
     }
-    executePause() {
+    async executePause() {
         const { result, newMode } = _executePause(this.agentMode);
         if (newMode !== this.agentMode) {
             this.agentMode = newMode;
             this.emitAgentState();
         }
+        // A pending proposal IS a new entry, which is exactly what Pause forbids.
+        // No exchange work here, so awaiting directly costs nothing.
+        if (result.executed) {
+            return withProposalDetail(result, await cancelPendingProposals(this.config.connectionToken, 'pause'));
+        }
         return result;
     }
     executeResume() {
@@ -709,6 +725,105 @@ export class GatewayProvider {
     async submitHlAgentApproval(args) {
         return executeSubmitHlAgentApproval({ http: this.http, toolMap: this.toolMap, operatorToken: this.config.connectionToken }, args);
     }
+    /**
+     * Operator-only. Update the ReefClaw connector on this box to the latest
+     * published version.
+     *
+     * Runs `npx -y @reefclaw/connect@latest` over the gateway's PTY. There is no
+     * command/version/args parameter and there never should be — the whole
+     * security argument for this feature is that the string is a constant (see
+     * providers/connector-update.ts).
+     *
+     * The installer restarts the gateway when it finishes, which kills both the
+     * PTY and this process's own transport. That is the SUCCESS path: we report
+     * `restarting` and the dashboard waits for the reconnect.
+     */
+    async updateConnector(args) {
+        const ws = this.wsClient;
+        if (!ws) {
+            return { ok: false, status: 'failed', message: 'Not connected to the OpenClaw gateway.' };
+        }
+        const rpc = (method, params) => ws.sendRpc(method, params);
+        const openPositionCount = this.positions.filter((p) => Math.abs(Number(p.contracts) || 0) > 0).length;
+        const started = await startConnectorUpdate(rpc, {
+            acknowledgeOpenPositions: args.acknowledgeOpenPositions,
+            openPositionCount,
+        });
+        if (started.status !== 'started' || !started.sessionId)
+            return started;
+        // Stream progress in the background; the RPC returns as soon as the command
+        // is running so the browser is never left waiting on a minutes-long call.
+        void this.streamConnectorUpdate(rpc, started.sessionId);
+        return started;
+    }
+    /**
+     * Poll the PTY and emit progress until the command finishes or the gateway
+     * restart takes the session (and us) down.
+     */
+    async streamConnectorUpdate(rpc, sessionId) {
+        const POLL_MS = 1500;
+        // Generous: an npm install on a small VPS is slow. The gateway restart
+        // normally ends this loop long before the cap.
+        const MAX_POLLS = 240;
+        let lastEmitted = '';
+        // A single failed read is not proof the gateway went away — it could be a
+        // transient RPC error under install load. Require two in a row before
+        // declaring the restart, so we do not flip the dashboard into "restarting"
+        // while the update is in fact still running.
+        let consecutiveDeadReads = 0;
+        for (let i = 0; i < MAX_POLLS; i++) {
+            await new Promise((r) => setTimeout(r, POLL_MS));
+            const screen = await readTerminalText(rpc, sessionId);
+            if (screen !== null)
+                consecutiveDeadReads = 0;
+            else if (++consecutiveDeadReads < 2)
+                continue;
+            if (screen === null) {
+                // Session (or the whole gateway) is gone. After a successful start this
+                // is the restart landing, not a failure.
+                const status = classifyTransportLoss(true);
+                this.emitConnectorUpdate({
+                    ok: true,
+                    status,
+                    sessionId,
+                    output: lastEmitted,
+                    message: 'The agent is restarting to load the new version. The dashboard reconnects on its own.',
+                });
+                return;
+            }
+            if (screen !== lastEmitted) {
+                lastEmitted = screen;
+                this.emitConnectorUpdate({ ok: true, status: 'started', sessionId, output: screen, message: 'Updating…' });
+            }
+            if (isCredibleCompletion(screen)) {
+                const { exitCode } = parseDoneSentinel(screen);
+                const ok = exitCode === 0;
+                this.emitConnectorUpdate({
+                    ok,
+                    status: 'completed',
+                    sessionId,
+                    exitCode,
+                    output: screen,
+                    message: ok
+                        ? 'Connector updated. The agent restarts to load it.'
+                        : `The updater exited with code ${exitCode}. The connector was left as it was.`,
+                });
+                await closeTerminal(rpc, sessionId);
+                return;
+            }
+        }
+        this.emitConnectorUpdate({
+            ok: false,
+            status: 'failed',
+            sessionId,
+            output: lastEmitted,
+            message: 'The update did not finish in time. Check the box directly before retrying.',
+        });
+        await closeTerminal(rpc, sessionId);
+    }
+    emitConnectorUpdate(payload) {
+        this.fire('connectorUpdate', payload);
+    }
     /** Operator-only. Approval/balance status of the provisioned HL wallet. */
     async getHlAgentWalletStatus() {
         return executeHlAgentWalletStatus({
@@ -1135,7 +1250,14 @@ export class GatewayProvider {
         return new Poller(this.http, this.toolMap, this.config.symbol, {
             onTicker: (data) => this.onPollerTicker(data),
             onCandle: (data) => this.fire('candle', data),
-            onPositions: (positions) => this.onPollerPositions(positions),
+            // onPollerPositions is the only async poller handler — without the
+            // catch, a throw anywhere in fill-detection/NAV/risk becomes an
+            // unhandled rejection and kills the bridge process.
+            onPositions: (positions) => {
+                void this.onPollerPositions(positions).catch((err) => {
+                    logger.error(TAG, `positions handler failed: ${formatError(err)}`);
+                });
+            },
             onBalance: (balance) => this.onPollerBalance(balance),
             onOpenOrders: (orders) => this.onPollerOpenOrders(orders),
             onMarketStructure: (data) => this.onPollerMarketStructure(data),
@@ -1395,7 +1517,12 @@ export class GatewayProvider {
                         if (lastPrice <= 0)
                             return;
                         this.applyMarkPrice(pos, lastPrice);
-                    }).catch(() => { });
+                    }).catch((err) => {
+                        // These fetches run OUTSIDE guardedExec — a swallowed 418/429
+                        // here defeats the ban gate (every request during a 418 extends
+                        // the per-IP ban). Feed rate-limit-shaped errors to the breaker.
+                        this.poller?.noteExternalRateLimit('mtm_ticker', formatError(err));
+                    });
                     updatePromises.push(p);
                 }
             }
@@ -1973,6 +2100,24 @@ export class GatewayProvider {
             if (!Array.isArray(jobs))
                 return; // unknown shape — leave last-known
             const hb = jobs.find((j) => isHeartbeatLikeName(j?.name));
+            // Cadence from the same RPC row: on 2026.7.x the filesystem jobs.json
+            // that resolveHeartbeatSeconds() reads is gone (cron store migrated),
+            // so without this the "beat every Nm" label and the 2× unresponsive
+            // threshold silently fall back to the hardcoded 1800s.
+            const row = hb;
+            const sched = row?.schedule;
+            if (row?.enabled !== false &&
+                sched?.kind === 'every' &&
+                typeof sched.everyMs === 'number' &&
+                sched.everyMs > 0) {
+                const secs = Math.round(sched.everyMs / 1000);
+                if (secs !== this.heartbeatSeconds && !this.loggedHeartbeat) {
+                    this.loggedHeartbeat = true;
+                    logger.info(TAG, `Heartbeat cadence resolved: ${secs}s (~${Math.round(secs / 60)}m) from cron.list`);
+                }
+                this.heartbeatSeconds = secs;
+                this.heartbeatReadAtMs = Date.now();
+            }
             const state = hb?.state;
             if (!state || typeof state !== 'object')
                 return;
@@ -2112,11 +2257,17 @@ export class GatewayProvider {
      * hardcoded 1800 and `agents.defaults.heartbeat` are both stale/wrong once
      * the operator edits the cron (`openclaw cron ... --every 15m`). Drives both
      * the "beat every Nm" label and the unresponsive (2×) threshold. Cached 60s;
-     * returns undefined (caller defaults to 1800) when unreadable.
+     * returns undefined (caller defaults to 1800) when unreadable. On 2026.7.x
+     * (no jobs.json) the value is fed by refreshHeartbeatHealth() from the
+     * cron.list RPC instead; the file read here is the legacy fallback.
      */
     resolveHeartbeatSeconds() {
         const now = Date.now();
-        if (this.heartbeatSeconds !== undefined && now - this.heartbeatReadAtMs < 60_000) {
+        // TTL must also cover the absent-file case (jobs.json doesn't exist on
+        // 2026.7.x) — gating on `heartbeatSeconds !== undefined` meant the cache
+        // never engaged there and buildAgentState did 2 blocking readFileSync
+        // ENOENT probes every 5s tick, forever.
+        if (now - this.heartbeatReadAtMs < 60_000) {
             return this.heartbeatSeconds;
         }
         const candidates = [

package/bridge/providers/mock.js

@@ -25,6 +25,7 @@ export class MockProvider {
         chatMessageStart: new Set(),
         chatMessageChunk: new Set(),
         chatMessageEnd: new Set(),
+        connectorUpdate: new Set(),
         chatStreamingKeepAlive: new Set(),
         marketStructure: new Set(),
         cryptoMetrics: new Set(),

package/bridge/types.d.ts

@@ -3,7 +3,7 @@ export type { Channel, RequestFrame, ResponseFrame, EventFrame, Frame, Emergency
 export { VALID_CHANNELS, VALID_EMERGENCY_ACTIONS } from '@reefclaw/shared';
 type EventFrame = _EventFrame;
 /** Methods the skill accepts from the relay (browser → skill) */
-export declare const ALLOWED_METHODS: readonly ["emergency.kill", "emergency.flatten", "emergency.pause", "emergency.resume", "reconcile", "chat.send", "skill.update", "close_position", "set_trading_mode", "set_exchange_credentials", "test_exchange_credentials", "clear_exchange_credentials", "hl_provision_agent_wallet", "hl_agent_wallet_status", "hl_submit_agent_approval", "get_bracket_config", "set_bracket_requirement"];
+export declare const ALLOWED_METHODS: readonly ["emergency.kill", "emergency.flatten", "emergency.pause", "emergency.resume", "reconcile", "chat.send", "skill.update", "close_position", "set_trading_mode", "set_exchange_credentials", "test_exchange_credentials", "clear_exchange_credentials", "hl_provision_agent_wallet", "hl_agent_wallet_status", "hl_submit_agent_approval", "get_bracket_config", "set_bracket_requirement", "connector.update"];
 /** Subset of ALLOWED_METHODS that require operator.write scope. The bridge
  *  enforces this before dispatching — a session without the scope gets a
  *  403 error. PR2 ships the scope as session-wide (inherited from the Clerk

package/bridge/types.js

@@ -25,6 +25,10 @@ export const ALLOWED_METHODS = [
     // Bracket-orders config (Phase 3.5b) — operator.write-gated.
     'get_bracket_config',
     'set_bracket_requirement',
+    // Operator-triggered connector update. Runs a FIXED command on the box over
+    // the gateway PTY — carries no command/version/args field by design (see the
+    // security note in providers/connector-update.ts). operator.write-gated.
+    'connector.update',
 ];
 /** Subset of ALLOWED_METHODS that require operator.write scope. The bridge
  *  enforces this before dispatching — a session without the scope gets a
@@ -42,6 +46,7 @@ export const OPERATOR_WRITE_METHODS = new Set([
     'hl_submit_agent_approval',
     'get_bracket_config',
     'set_bracket_requirement',
+    'connector.update',
     'emergency.kill',
     'emergency.flatten',
     'emergency.pause',

package/ccxt/binance-private.js

@@ -813,7 +813,8 @@ export class BinancePrivateApi {
             const raw = await this.exchange.fetchTicker(symbol);
             noteSuccess();
             return {
-                symbol: raw.symbol,
+                // Echo the REQUESTED symbol — see BinancePublicApi.fetchTicker.
+                symbol,
                 last: raw.last ?? 0,
                 bid: raw.bid ?? 0,
                 ask: raw.ask ?? 0,

package/ccxt/binance-public.js

@@ -86,7 +86,12 @@ export class BinancePublicApi {
             const raw = await this.exchange.fetchTicker(symbol);
             noteSuccess();
             return {
-                symbol: raw.symbol,
+                // Echo the REQUESTED symbol, not ccxt's unified form. ccxt rewrites
+                // 'ETH/USDT' → 'ETH/USDT:USDT' on USDM futures; returning that made
+                // callers key per-symbol caches under a name the caller never asked
+                // for (see the simulator's tickerKey note). Same invariant that
+                // intel-public.ts fetchTicker already documents.
+                symbol,
                 last: raw.last ?? 0,
                 bid: raw.bid ?? 0,
                 ask: raw.ask ?? 0,

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

@@ -4,11 +4,14 @@
  *  never whole-payload rejection. Gates are added one at a time
  *  (TOOL_DISTRIBUTION_ARCHITECTURE.md §11 step 3): `exitGate` (slice 2) →
  *  `positionReviewMode` (slice 3, the Position Decision Journal
- *  heartbeat-mandate + superset gate, file key `positionReview.mode`). Both
- *  ride the same four-stage `off → shadow → observe → enforce` ladder. */
+ *  heartbeat-mandate + superset gate, file key `positionReview.mode`) →
+ *  `approvalMode` (slice 4, per-trade operator approval, file key
+ *  `approval.mode`). The first two ride the same four-stage
+ *  `off → shadow → observe → enforce` ladder; approvalMode has its own. */
 export interface AgentGates {
     exitGate?: 'off' | 'shadow' | 'observe' | 'enforce';
     positionReviewMode?: 'off' | 'shadow' | 'observe' | 'enforce';
+    approvalMode?: 'off' | 'per_trade';
 }
 /** Server-resolved entitlement verdict (webapp lib/entitlements.ts, computed
  *  from the users row and delivered on the config channel). The plugin NEVER

package/config/agent-config-client.js

@@ -23,6 +23,15 @@ 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']);
+/** approvalMode's own enum — deliberately NOT the four-stage ladder.
+ *
+ *  ★ `shadow` is absent on purpose. Shadow proposal telemetry is driven by the
+ *  APPROVAL_SHADOW_MODE systemd env flag, which is boot-snapshotted and local
+ *  to the box; it is not a central value. Accepting 'shadow' here would let a
+ *  central push silently enable telemetry writes the operator never configured,
+ *  and would collide with the env flag's precedence. Central can express
+ *  exactly the two states that change trading behaviour. */
+const APPROVAL_MODE_VALUES = new Set(['off', 'per_trade']);
 const ENTITLEMENT_STATES = new Set([
     'active',
     'trialing',
@@ -112,6 +121,10 @@ function validateGates(raw) {
     if (typeof positionReviewMode === 'string' && MODE_LADDER_VALUES.has(positionReviewMode)) {
         gates.positionReviewMode = positionReviewMode;
     }
+    const approvalMode = obj.approvalMode;
+    if (typeof approvalMode === 'string' && APPROVAL_MODE_VALUES.has(approvalMode)) {
+        gates.approvalMode = approvalMode;
+    }
     return gates;
 }
 /** Version-monotonic acceptance (basic rollback/replay protection): a fetched

package/config/agent-config-poller.js

@@ -65,7 +65,11 @@ export function startAgentConfigPoller(opts) {
         });
         if (fetched) {
             loggedFetchFailure = false;
-            if (applyIfAcceptable(fetched, 'network')) {
+            // Only touch the cache file when the config actually changed —
+            // isAcceptableVersion accepts equal versions, so this used to do a
+            // blocking write+rename every 60s poll forever.
+            const prevJson = JSON.stringify(current);
+            if (applyIfAcceptable(fetched, 'network') && JSON.stringify(fetched) !== prevJson) {
                 writeCachedConfig(fetched, opts.cachePath);
             }
             return;

package/config/gate-store.d.ts

@@ -9,6 +9,15 @@ declare class GateStore {
     /** The central positionReview.mode, or null when central has no value (or the
      *  kill-switch is on) — null tells the reader to fall back to the file. */
     getPositionReviewMode(): AgentGates['positionReviewMode'] | null;
+    /** The central approval.mode, or null when central has no value (or the
+     *  kill-switch is on) — null tells the reader to fall back to the file.
+     *
+     *  ★ Central can only ever say 'off' or 'per_trade'. It cannot enable shadow
+     *  telemetry (that's the local APPROVAL_SHADOW_MODE env flag) and it cannot
+     *  weaken the hardcoded safety floor — per_trade only ADDS a gate, and 'off'
+     *  is the pre-existing autonomous behaviour, so neither value can leave a
+     *  position unprotected. */
+    getApprovalMode(): AgentGates['approvalMode'] | null;
     /** Test-only. */
     __reset(): void;
 }

package/config/gate-store.js

@@ -30,11 +30,13 @@ class GateStore {
     apply(gates) {
         const next = gates ?? {};
         const changed = next.exitGate !== this.gates.exitGate ||
-            next.positionReviewMode !== this.gates.positionReviewMode;
+            next.positionReviewMode !== this.gates.positionReviewMode ||
+            next.approvalMode !== this.gates.approvalMode;
         this.gates = { ...next };
         if (changed) {
             logger.info(TAG, `applied central gates: exitGate=${next.exitGate ?? UNSET} ` +
-                `positionReviewMode=${next.positionReviewMode ?? UNSET}`);
+                `positionReviewMode=${next.positionReviewMode ?? UNSET} ` +
+                `approvalMode=${next.approvalMode ?? UNSET}`);
         }
     }
     /** The central exitGate mode, or null when central has no value (or the
@@ -51,6 +53,19 @@ class GateStore {
             return null;
         return this.gates.positionReviewMode ?? null;
     }
+    /** The central approval.mode, or null when central has no value (or the
+     *  kill-switch is on) — null tells the reader to fall back to the file.
+     *
+     *  ★ Central can only ever say 'off' or 'per_trade'. It cannot enable shadow
+     *  telemetry (that's the local APPROVAL_SHADOW_MODE env flag) and it cannot
+     *  weaken the hardcoded safety floor — per_trade only ADDS a gate, and 'off'
+     *  is the pre-existing autonomous behaviour, so neither value can leave a
+     *  position unprotected. */
+    getApprovalMode() {
+        if (!centralGatesEnabled())
+            return null;
+        return this.gates.approvalMode ?? null;
+    }
     /** Test-only. */
     __reset() {
         this.gates = {};

package/config/plugin-config-io.js

@@ -10,7 +10,7 @@
 // operator-only tool gated on dashboard provenance (verifyOperatorProvenance,
 // audit F12) — the agent cannot reach these writes conversationally. The file
 // is the plugin's OWN config store; nothing here touches OpenClaw's config.
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync, } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { logger } from '../logger.js';
@@ -82,17 +82,39 @@ export function loadMicroLiveConfig(path) {
     catch { /* best-effort — adapter default applies */ }
     return undefined;
 }
+// mtime(ns)+size memo: several hot paths re-read this file per tool call
+// (approval mode, bracket mode/requirements, exit gate, review mode, the
+// microstructure flag × N symbols on the review path). A write always bumps
+// mtime, so the documented per-call hot-reload semantics are preserved
+// exactly — an unchanged file just costs one stat instead of read+parse.
+// structuredClone on both sides keeps today's fresh-object-per-call contract.
+const readMemo = new Map();
 /** Read the config file. Returns `{}` if the file doesn't exist.
  *  Throws if the file exists but is unreadable or not valid JSON — callers
  *  should treat that as an abort signal, not silently overwrite. */
 export function readPluginConfig(path = defaultConfigPath()) {
-    if (!existsSync(path))
+    if (!existsSync(path)) {
+        readMemo.delete(path);
         return {};
+    }
+    let stat;
+    try {
+        const s = statSync(path, { bigint: true });
+        stat = { mtimeNs: s.mtimeNs, size: s.size };
+        const hit = readMemo.get(path);
+        if (hit && hit.mtimeNs === stat.mtimeNs && hit.size === stat.size) {
+            return structuredClone(hit.parsed);
+        }
+    }
+    catch { /* stat raced a delete — fall through to the plain read */ }
     const raw = readFileSync(path, 'utf-8');
     const parsed = JSON.parse(raw);
     if (parsed == null || typeof parsed !== 'object' || Array.isArray(parsed)) {
         throw new Error(`plugin-config.json root is not an object`);
     }
+    if (stat) {
+        readMemo.set(path, { ...stat, parsed: structuredClone(parsed) });
+    }
     return parsed;
 }
 /** Apply a patch on top of the existing file and write atomically.

package/http/keepalive-fetch.d.ts

@@ -0,0 +1,5 @@
+export type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+/** Drop-in fetch with connection keep-alive; falls back to global fetch when
+ *  undici is unavailable, and defers to globalThis.fetch whenever it has been
+ *  replaced (mocks/instrumentation). */
+export declare function keepAliveFetch(url: string, init?: RequestInit): Promise<Response>;