@reefclaw/openclaw-plugin 0.1.23 → 0.1.25

package/bridge/providers/connector-update.js

@@ -0,0 +1,212 @@
+// Operator-triggered connector update, driven over the OpenClaw gateway's
+// terminal.* PTY methods.
+//
+// WHY A PTY AND NOT AN RPC: there is no plugin-install RPC on the gateway. The
+// full method table of OpenClaw 2026.7.1-2 (197 handlers) has no
+// `plugin.install` / `plugins.install`; that string exists only as an
+// audit-operation label and a CLI flag. `skills.install` DOES accept
+// `acknowledgeClawHubRisk` (it is what OpenClaw's own Control UI calls) but it
+// is the SKILLS surface, and the ClawHub installer branches on package family —
+// ReefClaw ships as `code-plugin`, which that path refuses by design. On this
+// OpenClaw version a code-plugin can only be installed/updated from a shell.
+// `terminal.*` is the gateway's shell.
+//
+// ★★ SECURITY — READ BEFORE CHANGING ANYTHING IN THIS FILE ★★
+// This module can run a command on the trader's machine, initiated from our
+// dashboard. That is only acceptable because the command is a FIXED CONSTANT:
+//
+//   - `CONNECTOR_UPDATE_COMMAND` is a module constant. Nothing from the
+//     browser, the relay, the agent, or any config is interpolated into it.
+//     There is deliberately NO version/args/flags parameter — not even a
+//     validated one — because the moment a caller can influence the string this
+//     stops being an update button and becomes a remote shell.
+//   - The RPC that reaches this module carries NO command field. Adding one is
+//     not a feature request to accept; it is the vulnerability.
+//   - No secret is ever placed on the command line. `@reefclaw/connect` takes
+//     no token argument (the token is already on disk from the first install),
+//     so the process list and shell history stay clean.
+//
+// Two further facts that shape the design:
+//   - The installer calls `restartGateway()`. The gateway restart therefore
+//     KILLS THIS PTY AND OUR OWN TRANSPORT mid-run. Losing the session after
+//     the command started is the SUCCESS path, not an error — see
+//     `classifyTransportLoss`.
+//   - The PTY runs as the gateway's own user (`openclaw`), which is exactly the
+//     user the installer must run as. Correct by construction.
+import { logger } from '../logger.js';
+const TAG = 'connector-update';
+/**
+ * The ONE command this feature can ever run.
+ *
+ * `-y` so npx never blocks on its install prompt; `@latest` because this is an
+ * update. No user input, no interpolation, no exceptions.
+ */
+export const CONNECTOR_UPDATE_COMMAND = 'npx -y @reefclaw/connect@latest';
+/** Marker printed after the command so we can detect completion + exit code. */
+export const DONE_SENTINEL = '__RC_CONNECTOR_UPDATE_DONE__';
+/**
+ * The exact line written to the PTY. Built once, from constants only.
+ * `$?` is expanded by the remote shell, not by us.
+ */
+export function buildUpdateCommandLine() {
+    return `${CONNECTOR_UPDATE_COMMAND}; printf '\\n${DONE_SENTINEL}%s\\n' "$?"`;
+}
+/** Terminal grid we request. Wide enough that npm/npx output does not wrap into
+ *  unreadable soup in the dashboard's output pane. */
+const COLS = 120;
+const ROWS = 40;
+function isOpenResult(v) {
+    return !!v && typeof v === 'object' && typeof v.sessionId === 'string';
+}
+/**
+ * Map a gateway error from `terminal.open` onto an operator-readable outcome.
+ *
+ * The two refusals we know the gateway can produce are worth distinct copy —
+ * both are configuration facts on the trader's box that no retry will fix:
+ *   - "terminal is not available" / "terminal is disabled"
+ *   - agent runs in a sandbox → in-sandbox terminals are unsupported
+ */
+export function describeOpenFailure(err) {
+    const raw = err instanceof Error ? err.message : String(err);
+    const lower = raw.toLowerCase();
+    if (lower.includes('terminal is disabled') || lower.includes('terminal is not available')) {
+        return {
+            ok: false,
+            status: 'blocked',
+            message: 'This box has the OpenClaw terminal disabled, so ReefClaw cannot run the update for you. '
+                + 'Update it from a shell on the box instead: npx -y @reefclaw/connect@latest',
+        };
+    }
+    if (lower.includes('sandbox')) {
+        return {
+            ok: false,
+            status: 'blocked',
+            message: 'This agent runs in a sandbox, and OpenClaw does not support terminals inside one yet. '
+                + 'Update from a shell on the box instead: npx -y @reefclaw/connect@latest',
+        };
+    }
+    return {
+        ok: false,
+        status: 'failed',
+        message: `Could not open a terminal on the box: ${raw}`,
+    };
+}
+/**
+ * Once the command is running, losing the transport is EXPECTED — the installer
+ * restarts the gateway, which is the process hosting both the PTY and our own
+ * connection. Treating that as a failure would report a successful update as
+ * broken, so the distinction is explicit and tested.
+ */
+export function classifyTransportLoss(started) {
+    return started ? 'restarting' : 'failed';
+}
+/** Extract the exit code that follows the DONE sentinel, if it has appeared. */
+export function parseDoneSentinel(screen) {
+    const idx = screen.lastIndexOf(DONE_SENTINEL);
+    if (idx === -1)
+        return { done: false, exitCode: null };
+    const after = screen.slice(idx + DONE_SENTINEL.length);
+    const m = /^(\d{1,3})/.exec(after.trim());
+    return { done: true, exitCode: m ? Number(m[1]) : null };
+}
+/**
+ * The sentinel is echoed by the shell as part of the command line BEFORE the
+ * command runs, so a naive `includes()` reports "done" immediately. Strip the
+ * echoed command line first: completion is only credible after the printf has
+ * actually executed, which is the LAST occurrence and is followed by a digit.
+ */
+export function isCredibleCompletion(screen) {
+    const { done, exitCode } = parseDoneSentinel(screen);
+    return done && exitCode !== null;
+}
+/**
+ * Guard the restart hazard. The installer restarts the gateway; with positions
+ * open that means the agent stops managing them for the duration (exchange-side
+ * brackets still protect the book — they are enforced by the venue, not by us —
+ * but there is a known startup window where protective closes are refused).
+ * So: never silently update a live book. Demand an explicit acknowledgement.
+ */
+export function checkPositionGuard(opts) {
+    if (opts.openPositionCount > 0 && opts.acknowledgeOpenPositions !== true) {
+        const n = opts.openPositionCount;
+        return {
+            ok: false,
+            status: 'blocked',
+            requiresPositionAck: true,
+            message: `${n} position${n === 1 ? ' is' : 's are'} open. Updating restarts the agent, so it will stop `
+                + 'managing the book for about a minute (exchange-side stops stay in force throughout). '
+                + 'Confirm again to update anyway, or flatten first.',
+        };
+    }
+    return null;
+}
+/**
+ * Open a PTY and write the update command to it. Returns as soon as the command
+ * is running — the caller polls `readTerminalText` for output.
+ */
+export async function startConnectorUpdate(rpc, opts) {
+    const blocked = checkPositionGuard(opts);
+    if (blocked) {
+        logger.info(TAG, `update refused: ${opts.openPositionCount} open position(s), no acknowledgement`);
+        return blocked;
+    }
+    let opened;
+    try {
+        opened = await rpc('terminal.open', { cols: COLS, rows: ROWS });
+    }
+    catch (err) {
+        const outcome = describeOpenFailure(err);
+        logger.warn(TAG, `terminal.open failed: ${outcome.message}`);
+        return outcome;
+    }
+    if (!isOpenResult(opened)) {
+        return {
+            ok: false,
+            status: 'failed',
+            message: 'The gateway opened a terminal but did not return a session id.',
+        };
+    }
+    const { sessionId } = opened;
+    logger.info(TAG, `terminal opened (shell=${opened.shell} cwd=${opened.cwd} confined=${opened.confined})`);
+    try {
+        // `\r` submits the line — terminal.input is raw keystrokes, not a command API.
+        await rpc('terminal.input', { sessionId, data: `${buildUpdateCommandLine()}\r` });
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        logger.warn(TAG, `terminal.input failed: ${reason}`);
+        // Best-effort cleanup so we do not leak a live PTY on the box.
+        await rpc('terminal.close', { sessionId }).catch(() => undefined);
+        return { ok: false, status: 'failed', message: `Could not start the update: ${reason}`, sessionId };
+    }
+    logger.info(TAG, `connector update started (session=${sessionId})`);
+    return {
+        ok: true,
+        status: 'started',
+        sessionId,
+        message: 'Update started. The agent restarts when it finishes, so the dashboard will reconnect on its own.',
+    };
+}
+/** Read the current screen contents. Returns null when the session is gone. */
+export async function readTerminalText(rpc, sessionId) {
+    try {
+        const res = await rpc('terminal.text', { sessionId });
+        if (typeof res === 'string')
+            return res;
+        if (res && typeof res === 'object') {
+            const t = res;
+            if (typeof t.text === 'string')
+                return t.text;
+            if (typeof t.data === 'string')
+                return t.data;
+        }
+        return '';
+    }
+    catch {
+        return null;
+    }
+}
+/** Best-effort PTY cleanup. Never throws — cleanup failure must not mask an outcome. */
+export async function closeTerminal(rpc, sessionId) {
+    await rpc('terminal.close', { sessionId }).catch(() => undefined);
+}

package/bridge/providers/emergency-commands.d.ts

@@ -44,6 +44,42 @@ export declare function executeKill(ctx: EmergencyContext, freshOrders: OrderDat
  * Caller must set agentMode = 'STOPPED' after this returns.
  */
 export declare function executeFlatten(ctx: EmergencyContext, cachedPositions: CcxtPosition[]): Promise<EmergencyResult>;
+export interface ProposalCancelSummary {
+    /** Rows moved to `cancelled`. 0 is the normal result when approval mode is off. */
+    cancelled: number;
+    /** Approved proposals a listener had already claimed — these may already be
+     *  at the exchange, so they are deliberately NOT cancelled. */
+    inFlight: number;
+    /** Operator-facing sentence for EmergencyResult.details, or null when there
+     *  is nothing worth saying (feature off / not configured). */
+    detail: string | null;
+}
+/**
+ * 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 declare function cancelPendingProposals(operatorToken: string | undefined, reason: 'kill_switch' | 'flatten' | 'pause' | 'mode_disabled', fetchImpl?: typeof fetch): Promise<ProposalCancelSummary>;
+/** Fold a proposal-cancel summary into an EmergencyResult's details line. */
+export declare function withProposalDetail(result: EmergencyResult, summary: ProposalCancelSummary): EmergencyResult;
 /**
  * Pause: prevent new entries, keep existing positions.
  * Returns the new agent mode if the transition is valid.

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(),