@reefclaw/openclaw-plugin 0.1.22 → 0.1.24

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/providers/onboarding-commands.d.ts

@@ -1,6 +1,6 @@
 import type { GatewayHttpClient } from '../gateway/gateway-http-client.js';
 import type { ToolMap } from '../gateway/tool-discovery.js';
-import type { ExchangeCredentialsRequest, HlProvisionOutcome, HlAgentWalletStatusOutcome } from '../provider.js';
+import type { ExchangeCredentialsRequest, HlProvisionOutcome, HlAgentWalletStatusOutcome, HlSubmitApprovalOutcome } from '../provider.js';
 import type { TradingMode } from '@reefclaw/shared';
 export interface SetTradingModeOutcome {
     ok: boolean;
@@ -116,6 +116,17 @@ export declare function executeProvisionHlAgentWallet(ctx: OnboardingContext, ar
     regenerate?: boolean;
     confirm_venue_switch?: boolean;
 }): Promise<HlProvisionOutcome>;
+/** Forward an hl_submit_agent_approval invocation to the plugin. The payload
+ *  is a signature the operator's wallet produced — no secret material. */
+export declare function executeSubmitHlAgentApproval(ctx: OnboardingContext, args: {
+    action: Record<string, unknown>;
+    nonce: number;
+    signature: {
+        r: string;
+        s: string;
+        v: number;
+    };
+}): Promise<HlSubmitApprovalOutcome>;
 /** Forward an hl_agent_wallet_status invocation to the plugin. Read-only. */
 export declare function executeHlAgentWalletStatus(ctx: OnboardingContext): Promise<HlAgentWalletStatusOutcome>;
 /** Forward a set_exchange_credentials invocation to the plugin via HTTP.

package/bridge/providers/onboarding-commands.js

@@ -254,6 +254,31 @@ export async function executeProvisionHlAgentWallet(ctx, args) {
         return { ok: false, message: reason, venue: 'hyperliquid', mode: 'PAPER' };
     }
 }
+/** Forward an hl_submit_agent_approval invocation to the plugin. The payload
+ *  is a signature the operator's wallet produced — no secret material. */
+export async function executeSubmitHlAgentApproval(ctx, args) {
+    const tool = ctx.toolMap.hl_submit_agent_approval;
+    if (!tool || !ctx.http) {
+        return {
+            ok: false,
+            message: 'hl_submit_agent_approval tool not available on gateway — update the ReefClaw plugin (npx @reefclaw/connect@latest)',
+        };
+    }
+    try {
+        const result = await ctx.http.invoke(tool, {
+            action: args.action,
+            nonce: args.nonce,
+            signature: args.signature,
+            operator_token: ctx.operatorToken,
+        });
+        return result.data;
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        logger.error(TAG, `hl_submit_agent_approval failed: ${reason}`);
+        return { ok: false, message: reason };
+    }
+}
 /** Forward an hl_agent_wallet_status invocation to the plugin. Read-only. */
 export async function executeHlAgentWalletStatus(ctx) {
     const tool = ctx.toolMap.hl_agent_wallet_status;

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", "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

@@ -21,9 +21,14 @@ export const ALLOWED_METHODS = [
     // Hyperliquid guided onboarding (box-generated agent wallet) — operator.write-gated.
     'hl_provision_agent_wallet',
     'hl_agent_wallet_status',
+    'hl_submit_agent_approval',
     // 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
@@ -38,8 +43,10 @@ export const OPERATOR_WRITE_METHODS = new Set([
     'clear_exchange_credentials',
     'hl_provision_agent_wallet',
     'hl_agent_wallet_status',
+    '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/config/tool-gate.js

@@ -35,6 +35,7 @@ export const UNGOVERNABLE_TOOLS = new Set([
     // operator-only channel; disabling them would strand the HL setup flow.
     'hl_provision_agent_wallet',
     'hl_agent_wallet_status',
+    'hl_submit_agent_approval',
 ]);
 /** RC_TOOL_GATE: 'off' = kill-switch (gate never blocks), 'shadow' = log
  *  would-be blocks but execute anyway, anything else/default = 'enforce'.

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>;

package/http/keepalive-fetch.js

@@ -0,0 +1,50 @@
+// Keep-alive HTTP for the plugin's intel/webapp clients.
+//
+// Node's built-in fetch closes idle sockets after undici's 4s default, and the
+// gap between two agent tool calls is LLM think-time (seconds to tens of
+// seconds) — so every intel/webapp call was paying a fresh TCP+TLS handshake
+// (~2 RTTs) before any server work started. A dedicated undici Agent with a
+// 60s idle timeout holds the connection across those gaps.
+//
+// undici loads via createRequire (same rule as CCXT — see
+// docs/CLAUDE/plugin-integration.md) and the whole module FAILS OPEN to the
+// global fetch: dist-only overlay deploys land on boxes whose node_modules
+// predate this dependency, and a missing package must degrade to today's
+// behaviour, never crash the connector.
+import { createRequire } from 'node:module';
+// Captured at module load. When someone REPLACES globalThis.fetch later
+// (vitest fetch mocks, tracing wrappers), keepAliveFetch honors the
+// replacement instead of undici — otherwise every fetch-stubbing test (and
+// any legitimate instrumentation) would be silently bypassed onto the real
+// network.
+const nativeFetch = globalThis.fetch;
+let cached;
+function build() {
+    try {
+        const req = createRequire(import.meta.url);
+        const undici = req('undici');
+        const dispatcher = new undici.Agent({
+            keepAliveTimeout: 60_000,
+            keepAliveMaxTimeout: 300_000,
+            connections: 16,
+        });
+        // undici's own fetch + Agent are used together: passing an npm-undici
+        // dispatcher to Node's built-in fetch can fail an instanceof check against
+        // the internal undici copy.
+        return (url, init) => undici.fetch(url, { ...init, dispatcher });
+    }
+    catch {
+        return (url, init) => fetch(url, init);
+    }
+}
+/** 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 function keepAliveFetch(url, init) {
+    if (globalThis.fetch !== nativeFetch) {
+        return globalThis.fetch(url, init);
+    }
+    if (!cached)
+        cached = build();
+    return cached(url, init);
+}

package/index.js

@@ -68,6 +68,7 @@ import { testExchangeCredentialsTool } from './tools/test-exchange-credentials.j
 import { clearExchangeCredentialsTool } from './tools/clear-exchange-credentials.js';
 import { hlProvisionAgentWalletTool } from './tools/hl-provision-agent-wallet.js';
 import { hlAgentWalletStatusTool } from './tools/hl-agent-wallet-status.js';
+import { hlSubmitAgentApprovalTool } from './tools/hl-submit-agent-approval.js';
 import { ensureCredentialTransportKey } from './security/sealed-credentials.js';
 // Tool implementations
 import { fetchTickerTool } from './tools/fetch-ticker.js';
@@ -850,6 +851,16 @@ const TOOL_PARAMS = {
             probe: { type: 'boolean', description: 'Tool-discovery probe — returns immediately without config or network access' },
         },
     },
+    hl_submit_agent_approval: {
+        type: 'object',
+        properties: {
+            operator_token: { type: 'string', description: 'Operator provenance — injected automatically by the ReefClaw dashboard path. Agent-initiated calls are refused without it.' },
+            action: { type: 'object', description: "The wallet-signed approveAgent action, verbatim. Only type='approveAgent' is accepted." },
+            nonce: { type: 'number', description: 'Outer nonce — must equal action.nonce (user-signed actions carry one nonce)' },
+            signature: { type: 'object', description: 'Wallet signature { r, s, v } over the approveAgent typed data' },
+            probe: { type: 'boolean', description: 'Tool-discovery probe — returns immediately without config or network access' },
+        },
+    },
     clear_exchange_credentials: {
         type: 'object',
         properties: {
@@ -978,7 +989,10 @@ const paperTradingPlugin = {
         // gateway process must reload it before serving HTTP API calls.
         const reloadState = () => {
             try {
-                const fresh = stateManager.loadSync();
+                // Skips the full read+parse (and replaceState) when the on-disk file
+                // hasn't changed since the last load — this runs on every paper-mode
+                // tool call and the file grows with trade history.
+                const fresh = stateManager.loadSyncIfChanged();
                 if (fresh) {
                     simulator.replaceState(fresh);
                 }
@@ -1282,11 +1296,32 @@ const paperTradingPlugin = {
         // rows while collecting real ones). See docs/APPROVAL_MODE_DESIGN.md §12.
         const approvalShadowEnabled = (process.env.APPROVAL_SHADOW_MODE ?? '').trim() === '1';
         const resolveApprovalMode = () => {
-            try {
-                if (readPluginConfig().approval?.mode === 'per_trade')
-                    return 'per_trade';
+            // Precedence (config-service slice 4, mirrors loadExitGateMode /
+            // loadPositionReviewMode):
+            //
+            //   central (agent_config.gates.approvalMode) → plugin-config.json →
+            //   APPROVAL_SHADOW_MODE env → 'off'
+            //
+            // Central is enum-validated plugin-side (agent-config-client
+            // validateGates) and can only ever say 'off' | 'per_trade' — it cannot
+            // enable shadow telemetry and cannot weaken the safety floor. Kill-switch
+            // RC_CENTRAL_GATES=off makes the store report null and the file rules
+            // again. Read per call, so a dashboard flip applies within one poll
+            // (~60 s) with no restart.
+            const central = gateStore.getApprovalMode();
+            if (central === 'per_trade')
+                return 'per_trade';
+            if (central !== 'off') {
+                // No central value — fall back to the local file.
+                try {
+                    if (readPluginConfig().approval?.mode === 'per_trade')
+                        return 'per_trade';
+                }
+                catch { /* config unreadable — env-only fallback below */ }
             }
-            catch { /* config unreadable — env-only fallback below */ }
+            // Central 'off' still permits local shadow telemetry: shadow does not
+            // change trading behaviour (the order fires either way), it only writes
+            // an extra row, and the env flag is the operator's own local choice.
             return approvalShadowEnabled ? 'shadow' : 'off';
         };
         // Proposal manager + listener credentials: built whenever ingest
@@ -1316,8 +1351,18 @@ const paperTradingPlugin = {
                     logger.info(TAG, `Approval wiring active (mode=${bootApprovalMode}) → ${ingestBaseUrl} (userId=${reefclawUserId.slice(0, 8)}…)`);
                 }
             }
+            else if (bootApprovalMode === 'per_trade') {
+                // FAIL-CLOSED state: create_order will REFUSE every new entry until the
+                // credentials are restored or approval.mode is set back to off. Loud at
+                // boot AND at each refusal (create-order.ts) — a boot-only signal is how
+                // this used to go unnoticed while orders fired without the gate.
+                logger.error(TAG, `approval mode=per_trade but ingest token / REEFCLAW_USER_ID missing — proposals CANNOT ` +
+                    `reach the operator, so create_order will REFUSE every new entry (fail-closed). ` +
+                    `Restore the plugin connectionToken/WEBAPP_INGEST_TOKEN + REEFCLAW_USER_ID, or set ` +
+                    `approval.mode=off. Exits, stops, brackets and operator controls are unaffected.`);
+            }
             else if (bootApprovalMode !== 'off') {
-                logger.warn(TAG, `approval mode=${bootApprovalMode} but ingest token / REEFCLAW_USER_ID missing — proposal path disabled (orders fire directly)`);
+                logger.warn(TAG, `approval mode=${bootApprovalMode} but ingest token / REEFCLAW_USER_ID missing — shadow telemetry disabled (orders fire directly, as in off mode)`);
             }
         }
         // ---- Create exchange adapter based on trading mode ----
@@ -1876,6 +1921,14 @@ const paperTradingPlugin = {
                     pollIntervalMs: approvalCfg?.pollIntervalMs ?? 3_000,
                 });
             },
+            // The approval path just went away (mode flipped off, or live→PAPER).
+            // Anything still pending is now un-fireable but still shows an Approve
+            // button — cancel it rather than leave the operator a dead control.
+            onApprovalPathDisabled: async () => {
+                if (!proposalManagerCtx)
+                    return;
+                await proposalManagerCtx.manager.cancelAll(proposalManagerCtx.userId, 'mode_disabled');
+            },
         });
         runtime.setOnAdapterSwapped((a) => { void approvalLifecycle.onAdapterSwapped(a); });
         // Boot application — the same path every later swap takes.
@@ -2726,6 +2779,20 @@ const paperTradingPlugin = {
                     return jsonResult(await hlProvisionAgentWalletTool(params, { runtime, bootVenue: venue }));
                 },
             },
+            {
+                name: 'hl_submit_agent_approval',
+                label: 'Submit Hyperliquid Agent Approval',
+                description: "Operator-only. Submit the operator's wallet-signed approveAgent action to Hyperliquid FROM THIS MACHINE (the dashboard browser is often blocked from reaching the exchange API by ad-blockers/shields). Strictly limited to type='approveAgent' targeting this box's own provisioned agent wallet — it is not a general signed-action relay. Refused without dashboard operator provenance.",
+                parameters: TOOL_PARAMS.hl_submit_agent_approval,
+                execute: async (_id, params) => {
+                    if (params?.probe === true)
+                        return jsonResult(await hlSubmitAgentApprovalTool(params));
+                    const prov = verifyOperatorProvenance(params.operator_token);
+                    if (!prov.ok)
+                        return jsonResult({ error: prov.error });
+                    return jsonResult(await hlSubmitAgentApprovalTool(params));
+                },
+            },
             {
                 name: 'hl_agent_wallet_status',
                 label: 'Hyperliquid Agent Wallet Status',

package/ingest/position-decisions-client.d.ts

@@ -322,6 +322,12 @@ export declare class PositionDecisionsClient {
     private fireAndForget;
     private run;
     private runReturning;
+    /** Decision-path GET budget. Every read caller degrades to empty/null on
+     *  failure, so burning the write-grade budget (4 × 10s + backoff ≈ 42s
+     *  worst case) of the agent's turn to reach an optional result is pure
+     *  heartbeat latency. Background reads (reconcile sweep) override per call. */
+    private static readonly READ_MAX_ATTEMPTS;
+    private static readonly READ_DEADLINE_MS;
     private runGetReturning;
     private sleepBackoff;
 }

package/ingest/position-decisions-client.js

@@ -12,6 +12,7 @@
 //   - postEntry/Review/Close are fire-and-forget (don't block the WS hot path).
 //
 // All four routes accept the same auth: Bearer + X-User-Id headers.
+import { keepAliveFetch } from '../http/keepalive-fetch.js';
 import { logger, formatError } from '../logger.js';
 const TAG = 'position-decisions-client';
 export class PositionDecisionsClient {
@@ -25,7 +26,7 @@ export class PositionDecisionsClient {
         this.opts = {
             baseUrl: options.baseUrl.replace(/\/+$/, ''),
             ingestToken: options.ingestToken,
-            fetchImpl: options.fetchImpl ?? fetch,
+            fetchImpl: options.fetchImpl ?? keepAliveFetch,
             requestTimeoutMs: options.requestTimeoutMs ?? 10_000,
             maxAttempts: options.maxAttempts ?? 4,
             baseBackoffMs: options.baseBackoffMs ?? 250,
@@ -65,7 +66,12 @@ export class PositionDecisionsClient {
             qs.set('mode', mode);
         if (exchange)
             qs.set('exchange', exchange);
-        return this.runGetReturning(userId, `/api/internal/positions?${qs.toString()}`);
+        return this.runGetReturning(userId, `/api/internal/positions?${qs.toString()}`, {
+            // Reconcile-sweep read, NOT on the agent decision path — keep the
+            // write-grade retry budget: a null here skips a whole reconcile pass.
+            maxAttempts: this.opts.maxAttempts,
+            deadlineMs: Number.POSITIVE_INFINITY,
+        });
     }
     /** Read endpoint for the Phase 1 self-reflection feature. Awaited.
      *  Returns null on terminal/retry-exhausted failure (caller logs + degrades). */
@@ -246,12 +252,24 @@ export class PositionDecisionsClient {
         logger.error(TAG, `POST ${url} dropped after ${this.opts.maxAttempts} attempts. userId=${userId}.`);
         return null;
     }
-    async runGetReturning(userId, path) {
+    /** Decision-path GET budget. Every read caller degrades to empty/null on
+     *  failure, so burning the write-grade budget (4 × 10s + backoff ≈ 42s
+     *  worst case) of the agent's turn to reach an optional result is pure
+     *  heartbeat latency. Background reads (reconcile sweep) override per call. */
+    static READ_MAX_ATTEMPTS = 2;
+    static READ_DEADLINE_MS = 8_000;
+    async runGetReturning(userId, path, budget) {
         const url = `${this.opts.baseUrl}${path}`;
-        for (let attempt = 1; attempt <= this.opts.maxAttempts; attempt++) {
+        const maxAttempts = budget?.maxAttempts ??
+            Math.min(this.opts.maxAttempts, PositionDecisionsClient.READ_MAX_ATTEMPTS);
+        const deadlineAt = Date.now() + (budget?.deadlineMs ?? PositionDecisionsClient.READ_DEADLINE_MS);
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            const remainingMs = deadlineAt - Date.now();
+            if (remainingMs <= 0)
+                break;
             try {
                 const ac = new AbortController();
-                const tid = setTimeout(() => ac.abort(), this.opts.requestTimeoutMs);
+                const tid = setTimeout(() => ac.abort(), Math.min(this.opts.requestTimeoutMs, remainingMs));
                 let res;
                 try {
                     res = await this.opts.fetchImpl(url, {
@@ -285,16 +303,16 @@ export class PositionDecisionsClient {
                     logger.warn(TAG, `GET ${url} → ${res.status} (terminal, dropped). userId=${userId} body=${errBody.slice(0, 200)}`);
                     return null;
                 }
-                logger.warn(TAG, `GET ${url} → ${res.status} (attempt ${attempt}/${this.opts.maxAttempts}).`);
+                logger.warn(TAG, `GET ${url} → ${res.status} (attempt ${attempt}/${maxAttempts}).`);
             }
             catch (err) {
-                logger.warn(TAG, `GET ${url} threw (attempt ${attempt}/${this.opts.maxAttempts}): ${formatError(err)}`);
+                logger.warn(TAG, `GET ${url} threw (attempt ${attempt}/${maxAttempts}): ${formatError(err)}`);
             }
-            if (attempt < this.opts.maxAttempts) {
+            if (attempt < maxAttempts && Date.now() < deadlineAt) {
                 await this.sleepBackoff(attempt);
             }
         }
-        logger.error(TAG, `GET ${url} failed after ${this.opts.maxAttempts} attempts. userId=${userId}.`);
+        logger.error(TAG, `GET ${url} failed after ${maxAttempts} attempt(s)/deadline. userId=${userId}.`);
         return null;
     }
     async sleepBackoff(attempt) {

package/live/approval-lifecycle.d.ts

@@ -14,6 +14,16 @@ export interface ApprovalLifecycleDeps {
     hasWiring: () => boolean;
     /** Build a listener bound to THIS adapter. Called only when starting. */
     buildListener: (adapter: IExchangeAdapter) => StartableListener;
+    /** Called when a RUNNING listener was torn down and no replacement started —
+     *  i.e. the approval path was deliberately disabled (mode flipped away from
+     *  per_trade, or the live adapter went away). Any proposal still pending is
+     *  now un-fireable but still approvable on the dashboard, so the caller
+     *  cancels them (design doc §10 row 12).
+     *
+     *  Deliberately NOT called from stop() — a shutdown drain is a restart, not a
+     *  disable, and cancelling the operator's live proposals on every plugin
+     *  restart would be both wrong and obnoxious. */
+    onApprovalPathDisabled?: () => void | Promise<void>;
 }
 export declare class ApprovalListenerLifecycle {
     private readonly deps;

package/live/approval-lifecycle.js

@@ -52,14 +52,28 @@ export class ApprovalListenerLifecycle {
         return this.chain;
     }
     async apply(adapter) {
+        // A listener was running before this swap? Then if we end up NOT starting a
+        // replacement, whatever is still pending has been orphaned.
+        const hadListener = this.listener !== undefined;
         // Always tear down the previous listener first — it is bound to the OLD
         // adapter and must never fire through it again.
         await this.stopCurrent();
+        const orphaned = async (why) => {
+            if (!hadListener || !this.deps.onApprovalPathDisabled)
+                return;
+            logger.info(TAG, `approval path disabled (${why}) — cancelling any pending proposals`);
+            try {
+                await this.deps.onApprovalPathDisabled();
+            }
+            catch (err) {
+                logger.warn(TAG, `pending-proposal cancel failed: ${formatError(err)}`);
+            }
+        };
         if (!adapter.isLive)
-            return;
+            return orphaned('adapter is no longer live');
         const mode = this.deps.resolveApprovalMode();
         if (mode !== 'per_trade')
-            return;
+            return orphaned(`approval.mode=${mode}`);
         if (!this.deps.hasWiring()) {
             logger.warn(TAG, "approval.mode='per_trade' but ingest credentials/proposal manager missing — listener NOT started; approvals will not fire");
             return;