@reefclaw/openclaw-plugin 0.1.22 → 0.1.24

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
@@ -505,6 +550,44 @@ export class Bridge {
                 }
                 return;
             }
+            if (method === 'hl_submit_agent_approval') {
+                const provider = this.provider;
+                if (!provider.submitHlAgentApproval) {
+                    this.connector.sendResponse(id, true, {
+                        ok: false,
+                        message: 'Provider does not support hl_submit_agent_approval (likely mock provider)',
+                    });
+                    return;
+                }
+                const action = params?.action;
+                const nonce = params?.nonce;
+                const signature = params?.signature;
+                if (!action || typeof action !== 'object' ||
+                    typeof nonce !== 'number' ||
+                    !signature || typeof signature.r !== 'string' || typeof signature.s !== 'string' ||
+                    typeof signature.v !== 'number') {
+                    this.connector.sendResponse(id, false, undefined, {
+                        code: 400,
+                        message: 'hl_submit_agent_approval requires { action, nonce, signature:{r,s,v} }',
+                    });
+                    return;
+                }
+                // The plugin re-validates strictly (approveAgent only, own agent
+                // address only) — this layer just shape-checks and forwards.
+                audit('hl_submit_agent_approval.start', {
+                    id,
+                    chain: action.hyperliquidChain,
+                    agentAddress: action.agentAddress,
+                });
+                const outcome = await provider.submitHlAgentApproval({
+                    action: action,
+                    nonce,
+                    signature: { r: signature.r, s: signature.s, v: signature.v },
+                });
+                audit('hl_submit_agent_approval.complete', { id, ok: outcome.ok, hlStatus: outcome.hlStatus });
+                this.connector.sendResponse(id, true, outcome);
+                return;
+            }
             if (method === 'hl_agent_wallet_status') {
                 const provider = this.provider;
                 if (!provider.getHlAgentWalletStatus) {
@@ -519,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.js

@@ -78,10 +78,22 @@ 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;
             }
             // 4002 = stale skill connection on relay. Wait for it to time out, then retry.

package/bridge/gateway/heartbeat-cron.js

@@ -28,11 +28,34 @@ 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: 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 +112,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/gateway/tool-discovery.d.ts

@@ -3,7 +3,7 @@ import { GatewayHttpClient, GatewayHttpError } from './gateway-http-client.js';
  * Logical tool names used by ReefClaw internally.
  * Each maps to one or more candidate actual tool names on the gateway.
  */
-export type LogicalTool = 'fetch_ticker' | 'fetch_balance' | 'fetch_ohlcv' | 'fetch_positions' | 'fetch_open_orders' | 'cancel_all_orders' | 'cancel_order' | 'close_position' | 'create_order' | 'get_market_structure' | 'get_crypto_metrics' | 'get_market_intel' | '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 type LogicalTool = 'fetch_ticker' | 'fetch_balance' | 'fetch_ohlcv' | 'fetch_positions' | 'fetch_open_orders' | 'cancel_all_orders' | 'cancel_order' | 'close_position' | 'create_order' | 'get_market_structure' | 'get_crypto_metrics' | 'get_market_intel' | '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';
 /**
  * Build the test args used when probing each logical tool.
  *

package/bridge/gateway/tool-discovery.js

@@ -22,6 +22,7 @@ const OPTIONAL_TOOLS = [
     'clear_exchange_credentials',
     'hl_provision_agent_wallet',
     'hl_agent_wallet_status',
+    'hl_submit_agent_approval',
     'get_bracket_config',
     'set_bracket_requirement',
 ];
@@ -48,6 +49,7 @@ const CANDIDATES = {
     clear_exchange_credentials: ['clear_exchange_credentials'],
     hl_provision_agent_wallet: ['hl_provision_agent_wallet'],
     hl_agent_wallet_status: ['hl_agent_wallet_status'],
+    hl_submit_agent_approval: ['hl_submit_agent_approval'],
     get_bracket_config: ['get_bracket_config'],
     set_bracket_requirement: ['set_bracket_requirement'],
 };
@@ -119,6 +121,8 @@ export function buildProbeArgs(symbol = DEFAULT_PROBE_SYMBOL) {
         // timeout and mark the tool missing forever).
         hl_provision_agent_wallet: { walletAddress: '' },
         hl_agent_wallet_status: { probe: true },
+        // Same dedicated probe path: a real submit would POST to Hyperliquid.
+        hl_submit_agent_approval: { probe: true },
         // Bracket-config probes: no-arg read; set with an invalid flag triggers early-return.
         get_bracket_config: {},
         set_bracket_requirement: { flag: '__probe__', value: false },

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).
@@ -39,6 +40,18 @@ export interface HlProvisionOutcome {
     currentVenue?: string;
     currentMode?: string;
 }
+/** Result of hl_submit_agent_approval — the box relays the wallet-signed
+ *  approveAgent action to Hyperliquid (browsers are often blocked). */
+export interface HlSubmitApprovalOutcome {
+    ok: boolean;
+    message: string;
+    hlStatus?: string;
+    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;
@@ -91,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;
@@ -196,6 +211,27 @@ export interface OpenClawProvider {
     /** Operator-only: approval/balance status of the box's provisioned HL agent
      *  wallet (polled by the dashboard's guided flow after the wallet signature). */
     getHlAgentWalletStatus?(): Promise<HlAgentWalletStatusOutcome>;
+    /** Operator-only: submit the wallet-signed approveAgent action to
+     *  Hyperliquid FROM THE BOX. Carries no secret — only a signature the
+     *  operator's wallet already produced. */
+    submitHlAgentApproval?(args: {
+        action: Record<string, unknown>;
+        nonce: number;
+        signature: {
+            r: string;
+            s: string;
+            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>;