@reefclaw/openclaw-plugin 0.1.23 → 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
@@ -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.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/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>;

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.