@reefclaw/openclaw-plugin 0.1.23 → 0.1.25

package/bridge/bridge.js

@@ -11,7 +11,7 @@
 import { writeFileSync, renameSync, existsSync, mkdirSync, unlinkSync, readdirSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
-import { logger } from './logger.js';
+import { logger, formatError } from './logger.js';
 import { Connector } from './connector.js';
 import { readLocalSkillVersion, readAgentVisibleSkillVersions, validateSkillContent, compareSemver } from './utils/skill-version.js';
 import { invalidateSkillsSnapshot } from './utils/skills-snapshot-invalidation.js';
@@ -53,6 +53,8 @@ const CRITICAL_EVENTS = new Set([
     'state_update', // Agent mode changes (ACTIVE/PAUSED/STOPPED)
     'trading_mode', // Paper/live mode changes
     'skill_update_applied', // OTA SKILL.md confirmation
+    'connector_update', // Operator-triggered update progress — the frame right
+    // before the gateway restart must not be coalesced away.
     // All chat events are on the 'chat' channel and always sent immediately
 ]);
 /** How often to re-attempt the webapp SKILL.md pull while still on a bootstrap
@@ -249,6 +251,14 @@ export class Bridge {
         this.addListener('decisionTraceUpdate', (data) => {
             this.emit('agent_state', 'decision_trace', data);
         });
+        // Operator-triggered connector update: PTY output + status. CRITICAL
+        // priority so the operator watching an update in progress sees it live
+        // instead of behind the 500ms low-priority coalescer — and, more to the
+        // point, so the final frame before the gateway restart is not the one that
+        // gets dropped.
+        this.addListener('connectorUpdate', (data) => {
+            this.emit('agent_state', 'connector_update', data);
+        });
     }
     addListener(event, fn) {
         this.provider.on(event, fn);
@@ -313,10 +323,20 @@ export class Bridge {
     flushThrottleBuffer() {
         if (this.throttleBuffer.size === 0)
             return;
-        for (const [, { channel, event, payload }] of this.throttleBuffer) {
-            this.sendFrame(channel, event, payload);
+        // Per-entry guard + delete-as-sent: this runs bare inside setInterval, so
+        // an uncaught throw (e.g. JSON.stringify on a payload with a circular ref
+        // or BigInt leaking out of a tool result) would be a process-killing
+        // uncaught exception — and skipping clear() would re-flush the survivors
+        // next tick under NEW seq numbers (duplicate frames on the wire).
+        for (const [key, { channel, event, payload }] of this.throttleBuffer) {
+            this.throttleBuffer.delete(key);
+            try {
+                this.sendFrame(channel, event, payload);
+            }
+            catch (err) {
+                logger.warn(TAG, `flush dropped unserializable ${channel}:${event}: ${formatError(err)}`);
+            }
         }
-        this.throttleBuffer.clear();
     }
     startThrottleTimer() {
         this.stopThrottleTimer();
@@ -361,7 +381,7 @@ export class Bridge {
                 logger.info(TAG, 'Reconciliation requested');
                 const snapshot = await this.provider.getSnapshot();
                 const lastSequences = parseLastSequences(params);
-                const gapFill = this.replayBuffer
+                let gapFill = this.replayBuffer
                     .sinceMany(lastSequences)
                     .map((e) => ({
                     type: 'event',
@@ -370,7 +390,32 @@ export class Bridge {
                     payload: e.payload,
                     seq: e.seq,
                 }));
+                // The whole reconcile response is ONE WS message; an unbounded replay
+                // blows the relay's frame limit and the browser then gets NO snapshot
+                // at all (observed live 2026-08-04: 369 replayed events → relay
+                // "Message too large"). Keep the NEWEST events under a byte budget —
+                // the snapshot already carries current state, so dropping the oldest
+                // stream events is strictly better than losing the entire response.
                 if (gapFill.length > 0) {
+                    const GAP_FILL_BYTE_BUDGET = 256 * 1024;
+                    let bytes = 0;
+                    let start = gapFill.length;
+                    for (let i = gapFill.length - 1; i >= 0; i--) {
+                        try {
+                            bytes += JSON.stringify(gapFill[i]).length;
+                        }
+                        catch {
+                            start = i + 1; // unserializable event — cut it and everything older
+                            break;
+                        }
+                        if (bytes > GAP_FILL_BYTE_BUDGET)
+                            break;
+                        start = i;
+                    }
+                    if (start > 0) {
+                        logger.warn(TAG, `gapFill capped: dropping ${start} oldest of ${gapFill.length} events to fit the relay frame limit`);
+                        gapFill = gapFill.slice(start);
+                    }
                     logger.info(TAG, `gapFill: ${gapFill.length} events replayed (lastSeqs=${JSON.stringify(lastSequences)})`);
                 }
                 // Provider hardcodes gapFill: []; bridge owns the wire-side seq
@@ -557,6 +602,28 @@ export class Bridge {
                 this.connector.sendResponse(id, true, result);
                 return;
             }
+            if (method === 'connector.update') {
+                const provider = this.provider;
+                if (!provider.updateConnector) {
+                    this.connector.sendResponse(id, true, {
+                        ok: false,
+                        status: 'failed',
+                        message: 'Provider does not support connector.update (likely mock provider)',
+                    });
+                    return;
+                }
+                // ★ Deliberately reads ONE field. There is no command/version/args
+                // parameter to forward — the command is a constant inside the driver
+                // (providers/connector-update.ts). If a future change starts forwarding
+                // caller-supplied strings into that command, this stops being an update
+                // button and becomes a remote shell on the trader's machine.
+                const acknowledgeOpenPositions = params?.acknowledgeOpenPositions === true;
+                audit('connector_update.start', { id, acknowledgeOpenPositions });
+                const outcome = await provider.updateConnector({ acknowledgeOpenPositions });
+                audit('connector_update.dispatched', { id, ok: outcome.ok, status: outcome.status });
+                this.connector.sendResponse(id, true, outcome);
+                return;
+            }
             if (method === 'get_bracket_config') {
                 if (!this.provider.getBracketConfig) {
                     this.connector.sendResponse(id, false, undefined, {

package/bridge/connector.d.ts

@@ -22,7 +22,9 @@ export declare class Connector {
     private lastMessageAt;
     private destroyed;
     constructor(config: ConnectorConfig, callbacks: ConnectorCallbacks);
-    /** Build the relay WebSocket URL (token is sent via Authorization header, not URL) */
+    /** Build the relay WebSocket URL (token is sent via Authorization header, not
+     *  URL; the instance id is non-secret and rides the query string so the
+     *  relay's skill-slot admission can recognise a same-box restart). */
     private buildUrl;
     /** Start connecting to the relay */
     connect(): void;

package/bridge/connector.js

@@ -37,10 +37,15 @@ export class Connector {
         this.reconnectConfig = { ...DEFAULT_RECONNECT, ...config.reconnect };
         this.heartbeatConfig = { ...DEFAULT_HEARTBEAT };
     }
-    /** Build the relay WebSocket URL (token is sent via Authorization header, not URL) */
+    /** Build the relay WebSocket URL (token is sent via Authorization header, not
+     *  URL; the instance id is non-secret and rides the query string so the
+     *  relay's skill-slot admission can recognise a same-box restart). */
     buildUrl() {
         const base = this.config.relayUrl.replace(/\/$/, '');
-        return `${base}/parties/reefclaw/${this.config.userId}`;
+        const path = `${base}/parties/reefclaw/${this.config.userId}`;
+        return this.config.instanceId
+            ? `${path}?instance=${encodeURIComponent(this.config.instanceId)}`
+            : path;
     }
     /** Start connecting to the relay */
     connect() {
@@ -78,10 +83,40 @@ export class Connector {
             this.rejectAllPending('Connection closed');
             if (this.destroyed)
                 return;
-            // Fatal codes: do not reconnect
+            // Fatal codes (4001 invalid/mismatched token): no fast reconnect — but
+            // not terminal-forever either. A 4001 can be transient (relay/DB blip,
+            // token-cache miss on a just-created token, revoke-then-restore), and
+            // the old return-and-never-retry left the dashboard dark until a manual
+            // bridge restart (residual half of the #312 gave-up-forever class). One
+            // probe per 15 min is harmless and self-heals the transient cases.
             if (FATAL_CLOSE_CODES.includes(code)) {
-                logger.error(TAG, `Fatal close code ${code} — not reconnecting`);
+                logger.error(TAG, `Fatal close code ${code} (invalid/mismatched token). If the token was rotated, ` +
+                    `update the bridge .env (REEFCLAW_TOKEN) and restart. Probing again in 15 min ` +
+                    `in case the rejection was transient.`);
                 this.setState('failed');
+                this.attempt = 0;
+                this.reconnectTimer = setTimeout(() => {
+                    this.reconnectTimer = null;
+                    this.connect();
+                }, 15 * 60_000);
+                return;
+            }
+            // 4011 = another agent holds this account's skill slot and is alive
+            // (relay skill-slot admission, 2026-08-25 — the fix for the 4010
+            // ping-pong two bridges used to fight). Retrying fast is pointless and
+            // noisy: the seated agent keeps the slot until it stops. Slow-probe
+            // every 5 min so a deliberate box switch (stop the old one) is picked
+            // up without a manual restart here.
+            if (code === 4011) {
+                logger.error(TAG, `Relay refused this connection (4011): another agent is already connected for this ` +
+                    `account. ReefClaw runs ONE agent per account — stop the other agent (or revoke its ` +
+                    `token in the dashboard) to move this box in. Probing again in 5 min.`);
+                this.setState('failed');
+                this.attempt = 0;
+                this.reconnectTimer = setTimeout(() => {
+                    this.reconnectTimer = null;
+                    this.connect();
+                }, 5 * 60_000);
                 return;
             }
             // 4002 = stale skill connection on relay. Wait for it to time out, then retry.
@@ -263,6 +298,18 @@ export class Connector {
             // Send a native WebSocket ping (protocol-level, handled by PartyKit automatically).
             if (this.ws && this.ws.readyState === WebSocket.OPEN) {
                 this.ws.ping();
+                // App-level keepalive: native pings are absorbed by the PartyKit
+                // runtime and never reach the relay DO, so an idle-but-healthy agent
+                // would look dead to the skill-slot admission's liveness window and
+                // could be evicted by a second box's probe. One tiny frame per
+                // heartbeat tick keeps the seat provably occupied; the relay swallows
+                // it (never forwarded to browsers, never audited).
+                this.ws.send(JSON.stringify({
+                    type: 'event',
+                    event: 'skill_keepalive',
+                    channel: 'agent_state',
+                    payload: { ts: Date.now() },
+                }));
             }
         }, this.heartbeatConfig.intervalMs);
         logger.debug(TAG, `Heartbeat started: interval=${this.heartbeatConfig.intervalMs}ms timeout=${this.heartbeatConfig.timeoutMs}ms`);

package/bridge/gateway/heartbeat-cron.js

@@ -28,11 +28,35 @@ export const HEARTBEAT_EVERY_MS = 15 * 60 * 1000;
 // (verified empirically on 2026.7.1-2: a cron.add without it stores none) —
 // 780s is the field-proven value from the 2026-07-22 small-box mitigations.
 export const HEARTBEAT_TIMEOUT_SECONDS = 780;
-// Byte-identical to the message the setup-time CLI path created, so new jobs
-// match every existing install's job.
-export const HEARTBEAT_MESSAGE = 'Heartbeat. Run SESSION START mandatory checks, then the full Decision Loop (Steps 0-9) from SKILL.md. ' +
-    'Check tradingMode from fetch_balance — it is your source of truth for paper vs live. ' +
-    'Use tools in parallel where possible.';
+// The routine beat is HEARTBEAT.md (injected into every isolated cron session
+// as workspace bootstrap context) — NOT the SKILL.md Decision Loop. The old
+// message ("run the full Decision Loop (Steps 0-9) from SKILL.md") had two
+// measured costs on prod (2026-08-04): the agent paged the whole ~110KB
+// SKILL.md through sed/rg every beat (~100KB of tool output before any
+// trading work), and Steps 0-9 predate the pinned-plan/exit-gate discipline —
+// Step 8's exit rules are the scratch-the-winners instructions. SKILL.md is
+// consulted only when preparing a NEW entry.
+// NOTE: once-per-install marker semantics mean this message only reaches NEW
+// installs; existing boxes need a one-time `openclaw cron edit <id> --message`
+// (done on prod at deploy).
+// ★ The mandatory items are ENUMERATED here on purpose. The first (softer)
+// version of this message — "Run the HEARTBEAT.md checklist" — produced
+// 85-second beats on gpt-5.4-mini that skipped record_position_reviews,
+// get_wave9_status, and the liquidity batch entirely (observed on prod
+// 2026-08-04 12:25/12:40 UTC): the checklist being in context is not enough,
+// the beat prompt itself must name what cannot be skipped.
+export const HEARTBEAT_MESSAGE = 'Heartbeat. Execute EVERY checkbox in the HEARTBEAT.md checklist (already injected in your context; ' +
+    'do NOT re-read SKILL.md from disk unless preparing a NEW entry). ' +
+    'NON-SKIPPABLE every beat: (1) query_trades({hours:1}) stop-watcher reconcile; ' +
+    '(2) get_wave9_status() once, unconditionally; ' +
+    '(3) if ANY position is open and the Position Decision Journal is enabled (record_position_reviews reports off-mode when it is not): ' +
+    'get_my_recent_reviews() + get_relevant_learnings({applies_at: heartbeat}) in one batch, ' +
+    'then record_position_reviews with ONE review per open position, ' +
+    'plus get_resting_liquidity + get_liquidation_levels + get_liquidation_pulse for ALL positions in one parallel batch; ' +
+    '(4) the Market Assessment reads. ' +
+    'Manage open positions by their pinned plan (invalidation_price / realization_rule) — do not re-argue the entry thesis each beat. ' +
+    'Check tradingMode from fetch_balance — the source of truth for paper vs live. ' +
+    'Batch independent tool calls in parallel. Trading tools only: no subagents, no web browsing.';
 /**
  * Whether an existing cron job counts as "the heartbeat already exists".
  * Union of the two matchers already in the codebase: the old setup path
@@ -89,8 +113,8 @@ export async function ensureHeartbeatCron(opts) {
             // cron.add on 2026.7.1-2). No toolsAllow: absent = all-tools-allowed,
             // which is future-proof — an explicit allowlist freezes at creation and
             // silently excludes every plugin tool shipped later. Beat tool
-            // discipline (no subagents/web/media during heartbeats) lives in
-            // SKILL.md, which updates on every bridge start.
+            // discipline (no subagents/web during heartbeats) is stated in
+            // HEARTBEAT_MESSAGE itself.
             payload: {
                 kind: 'agentTurn',
                 message: HEARTBEAT_MESSAGE,

package/bridge/gateway/poller.d.ts

@@ -114,6 +114,11 @@ export declare class Poller {
      * - Errors are logged and swallowed (never crash the provider)
      */
     private guardedExec;
+    /** Arm the circuit-breaker for a Binance-bound call made OUTSIDE
+     *  guardedExec (e.g. the gateway's paper mark-to-market ticker fan-out).
+     *  Those calls used to swallow 418/429s entirely — exactly the
+     *  ban-extending failure mode the gate exists to prevent. */
+    noteExternalRateLimit(label: string, msg: string): void;
     /** Inspect a failed poll's error for Binance rate-limit signals and arm
      *  the process-wide circuit-breaker accordingly.
      *

package/bridge/gateway/poller.js

@@ -266,6 +266,15 @@ export class Poller {
             this.inflight.delete(label);
         }
     }
+    /** Arm the circuit-breaker for a Binance-bound call made OUTSIDE
+     *  guardedExec (e.g. the gateway's paper mark-to-market ticker fan-out).
+     *  Those calls used to swallow 418/429s entirely — exactly the
+     *  ban-extending failure mode the gate exists to prevent. */
+    noteExternalRateLimit(label, msg) {
+        if (isRateLimitShapedError(msg)) {
+            this.applyRateLimitBackoff(label, msg);
+        }
+    }
     /** Inspect a failed poll's error for Binance rate-limit signals and arm
      *  the process-wide circuit-breaker accordingly.
      *

package/bridge/index.js

@@ -16,7 +16,9 @@ import { MockProvider } from './providers/mock.js';
 import { GatewayProvider } from './providers/gateway.js';
 import { resolveConfig } from './config.js';
 import { resolveGatewayConfig, validateGatewayConfig } from './gateway/gateway-config.js';
+import { ShockWakePoller } from './shock-wake.js';
 import { runSetup } from './setup.js';
+import { resolveRelayInstanceId } from './utils/instance-id.js';
 const TAG = 'main';
 // ---- Load .env file (skill/.env only) ----
 function loadEnvFile() {
@@ -191,6 +193,7 @@ async function main() {
     }
     // Create provider
     let provider;
+    let intelligenceUrlForWakes;
     if (args.provider === 'mock') {
         logger.info(TAG, 'Using MockProvider');
         provider = new MockProvider();
@@ -217,14 +220,30 @@ async function main() {
         gwConfig.connectionToken = token;
         logger.info(TAG, `Using GatewayProvider (url=${gwConfig.gatewayUrl}, symbol=${gwConfig.symbol})`);
         provider = new GatewayProvider(gwConfig);
+        intelligenceUrlForWakes = gwConfig.intelligenceUrl;
     }
     // Create bridge
     const connectorConfig = {
         relayUrl,
         userId,
         token,
+        // Stable per-install id → the relay's skill-slot admission recognises a
+        // same-box restart (instant takeover) vs a second box (rejected 4011).
+        instanceId: resolveRelayInstanceId(),
     };
     const bridge = new Bridge(provider, connectorConfig);
+    // Shock-wake poller (WS3, docs/MARKET_ADAPTIVITY_PLAN.md) — watches intel's
+    // /api/shocks (the WS2 change-of-character flags) and delivers an
+    // out-of-band re-evaluation turn to the agent on a genuine market shift.
+    // Inert until the central gate agent_config.gates.shockWake leaves 'off'.
+    const shockWake = intelligenceUrlForWakes
+        ? new ShockWakePoller({ provider, token, intelligenceUrl: intelligenceUrlForWakes })
+        : null;
+    if (shockWake) {
+        // Delivery confirmation: any agent turn STARTING proves the main-session
+        // lane is alive — the gateway ack alone cannot (swallowed-turn class).
+        provider.on('chatMessageStart', () => shockWake.noteAssistantActivity());
+    }
     // Handle graceful shutdown
     let shuttingDown = false;
     async function shutdown(signal) {
@@ -239,6 +258,7 @@ async function main() {
             }
             catch { /* best-effort */ }
         }
+        shockWake?.stop();
         bridge.stop();
         // Allow 1s for final cleanup before force exit
         setTimeout(() => process.exit(0), 1000);
@@ -248,5 +268,6 @@ async function main() {
     // Start
     logger.info(TAG, `Starting ReefClaw skill (provider=${args.provider}, relay=${relayUrl})`);
     bridge.start();
+    shockWake?.start();
 }
 main();

package/bridge/provider.d.ts

@@ -1,5 +1,6 @@
 import type { EmergencyAction, ReconciliationSnapshot, TickerData, CandleData, OrderUpdatePayload, AgentStateData, RiskUpdatePayload, ChatMessage, MarketStructureData, CryptoMetricsData, VolumeAnalysisData, TradeJournalEntry, RegimeData, SignalData, MissionData, AnalyticsData, ShadowComparisonData, TradingModeData, DecisionTraceData } from './types.js';
 import type { TradingMode } from '@reefclaw/shared';
+import type { ConnectorUpdateOutcome } from './providers/connector-update.js';
 /** Per-venue credential shapes for the operator set/test RPCs. Binance is an
  *  HMAC key pair; Hyperliquid is a MASTER account address (public — queries)
  *  plus an approved AGENT wallet private key (signs only, cannot withdraw).
@@ -48,6 +49,9 @@ export interface HlSubmitApprovalOutcome {
     chain?: string;
     agentAddress?: string;
 }
+/** Progress of an operator-triggered connector update. Re-exported from the
+ *  driver so callers get the status union without importing the PTY module. */
+export type { ConnectorUpdateOutcome, ConnectorUpdateStatus, } from './providers/connector-update.js';
 /** Result of hl_agent_wallet_status — approval polling for the guided flow. */
 export interface HlAgentWalletStatusOutcome {
     ok: boolean;
@@ -100,6 +104,8 @@ export interface ProviderEvents {
         id: string;
         toolName: string;
     }) => void;
+    /** Progress of an operator-triggered connector update (PTY output + status). */
+    connectorUpdate: (data: ConnectorUpdateOutcome) => void;
     marketStructure: (data: MarketStructureData) => void;
     cryptoMetrics: (data: CryptoMetricsData) => void;
     volumeAnalysis: (data: VolumeAnalysisData) => void;
@@ -217,6 +223,15 @@ export interface OpenClawProvider {
             v: number;
         };
     }): Promise<HlSubmitApprovalOutcome>;
+    /** Operator-only: update the ReefClaw connector on this box to the latest
+     *  published version, driven over the gateway's terminal.* PTY methods.
+     *
+     *  There is no command parameter, by design — see the security note at the
+     *  top of providers/connector-update.ts. The only input is the operator's
+     *  acknowledgement that the resulting restart may interrupt an open book. */
+    updateConnector?(args: {
+        acknowledgeOpenPositions?: boolean;
+    }): Promise<ConnectorUpdateOutcome>;
     /** Operator-only: remove stored credentials from the plugin config and
      *  de-escalate to PAPER mode if currently running in a live mode. */
     clearExchangeCredentials?(): Promise<{

package/bridge/providers/connector-update.d.ts

@@ -0,0 +1,89 @@
+/**
+ * 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 declare const CONNECTOR_UPDATE_COMMAND = "npx -y @reefclaw/connect@latest";
+/** Marker printed after the command so we can detect completion + exit code. */
+export declare 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 declare function buildUpdateCommandLine(): string;
+/** Minimal RPC surface this module needs (injected — keeps it unit-testable). */
+export type TerminalRpc = (method: string, params: Record<string, unknown>) => Promise<unknown>;
+export type ConnectorUpdateStatus = 
+/** Command written to the PTY; output is streaming. */
+'started'
+/** DONE sentinel observed — we have a real exit code. */
+ | 'completed'
+/** Transport died after the command started = the gateway restart landed. */
+ | 'restarting'
+/** Refused before anything ran (terminal disabled / sandboxed / open positions). */
+ | 'blocked'
+/** Something genuinely went wrong. */
+ | 'failed';
+export interface ConnectorUpdateOutcome {
+    ok: boolean;
+    status: ConnectorUpdateStatus;
+    message: string;
+    sessionId?: string;
+    exitCode?: number | null;
+    /** Accumulated screen text, for the dashboard's output pane. */
+    output?: string;
+    /** True when the caller must re-submit with acknowledgeOpenPositions. */
+    requiresPositionAck?: boolean;
+}
+/**
+ * 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 declare function describeOpenFailure(err: unknown): ConnectorUpdateOutcome;
+/**
+ * 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 declare function classifyTransportLoss(started: boolean): ConnectorUpdateStatus;
+/** Extract the exit code that follows the DONE sentinel, if it has appeared. */
+export declare function parseDoneSentinel(screen: string): {
+    done: boolean;
+    exitCode: number | 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 declare function isCredibleCompletion(screen: string): boolean;
+export interface StartOptions {
+    /** Open positions the operator has been warned about and accepted. */
+    acknowledgeOpenPositions?: boolean;
+    /** Count of currently-open positions, as the skill sees them. */
+    openPositionCount: number;
+}
+/**
+ * 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 declare function checkPositionGuard(opts: StartOptions): ConnectorUpdateOutcome | 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 declare function startConnectorUpdate(rpc: TerminalRpc, opts: StartOptions): Promise<ConnectorUpdateOutcome>;
+/** Read the current screen contents. Returns null when the session is gone. */
+export declare function readTerminalText(rpc: TerminalRpc, sessionId: string): Promise<string | null>;
+/** Best-effort PTY cleanup. Never throws — cleanup failure must not mask an outcome. */
+export declare function closeTerminal(rpc: TerminalRpc, sessionId: string): Promise<void>;