@reefclaw/openclaw-plugin 0.1.0

package/config/user-data-stream-config.d.ts

@@ -0,0 +1,85 @@
+import { type PluginConfigFile } from './plugin-config-io.js';
+export type UserDataStreamMode = 'off' | 'shadow' | 'observe' | 'enforce';
+/** Production-safe defaults. Override via plugin-config for runbook use only. */
+export interface UserDataStreamTunables {
+    /** How often to call PUT /fapi/v1/listenKey to keep the stream alive.
+     *  Binance kills the key after 60 min of no keepalive; 25 min gives a 2x
+     *  safety margin under jitter and transient failures. */
+    listenKeyRefreshMs: number;
+    /** Initial backoff delay after a WS disconnect. Doubles on each attempt
+     *  up to reconnectCapMs. ±20% jitter applied to avoid thundering herd. */
+    reconnectBaseMs: number;
+    /** Cap on the exponential backoff. Keeps us trying indefinitely but not
+     *  more than once/minute after repeated failures. */
+    reconnectCapMs: number;
+    /** If no WS frame of any kind (message, ping, or pong) arrives within this
+     *  window, force a reconnect. Binance documents server pings every 3 min on
+     *  the user-data stream; a 6-min default catches a truly dead socket while
+     *  remaining quiet on calm accounts that get only the periodic pings. */
+    staleEventWatchdogMs: number;
+    /** How often to REST-refresh algo (STOP_MARKET / TAKE_PROFIT_MARKET / bracket)
+     *  orders into the store. Binance's user-data WS does NOT emit
+     *  ORDER_TRADE_UPDATE for algo orders until they trigger, so the store has no
+     *  other way to observe algo-order add/cancel events. Without this loop, the
+     *  60s truth-check reports MAJOR order drift every cycle any time brackets
+     *  are touched. Set to 0 to disable (falls back to snapshot-only). */
+    algoRefreshMs: number;
+    /** @deprecated since 2026-04-25 (ping-aware watchdog refactor). Field kept
+     *  for backward compatibility with existing plugin-config.json files; the
+     *  runtime no longer consults it. Empirically 99% of its fires were
+     *  false positives because the 90 s default sat below Binance's 180 s
+     *  server-ping interval and the watchdog only counted message frames as
+     *  liveness. The single `staleEventWatchdogMs` (6 min default, ping-aware)
+     *  is now sufficient; the active REST probe handles per-position freshness. */
+    activeStaleEventWatchdogMs: number;
+    /** How often the active REST probe checks for fills the WS missed.
+     *  Iterates open positions, calls fetchMyTrades(since=lastEventAt), and
+     *  forces a reconnect if any trade newer than lastEventAt is found.
+     *  Set to 0 to disable. Cost: ~5 weight per open position per probe. */
+    activeProbeIntervalMs: number;
+}
+export declare const DEFAULT_TUNABLES: UserDataStreamTunables;
+/** Read user-data-stream mode from a config object. Invalid values fall back to 'off'. */
+export declare function getUserDataStreamMode(config?: PluginConfigFile, remoteOverride?: UserDataStreamMode): UserDataStreamMode;
+/** Convenience: load from disk and return the effective mode. */
+export declare function loadUserDataStreamMode(): UserDataStreamMode;
+/** Is the WS stream enabled at all (anything other than 'off')? */
+export declare function userDataStreamEnabled(mode: UserDataStreamMode): boolean;
+export type UserDataStreamDbWrite = 'off' | 'on';
+/** Read the dbWrite flag.  Orthogonal to `mode`: `mode` controls the read
+ *  path (WS vs REST authoritative for getPositions etc.); `dbWrite` controls
+ *  whether WS-observed fills are POSTed to the webapp's audit-trail store.
+ *  Both must be enabled together for WS rows to land in `trades`. */
+export declare function getUserDataStreamDbWrite(config?: PluginConfigFile): UserDataStreamDbWrite;
+export declare function loadUserDataStreamDbWrite(): UserDataStreamDbWrite;
+/** Webapp ingest base URL (POST target).  Defaults to production reefclaw.com. */
+export declare function getUserDataStreamIngestBaseUrl(config?: PluginConfigFile): string;
+/** Resolve the webapp-ingest credential (the per-user `rc_*` token).
+ *
+ *  Prefers `connectionToken` in plugin-config.json — the same `rc_*` token
+ *  already stored there for the intel-service client, so there's one fewer
+ *  place to update on rotation than the legacy `WEBAPP_INGEST_TOKEN` systemd
+ *  env var. Falls back to that env var so existing deployments that haven't
+ *  moved the token into plugin-config.json keep working unchanged.
+ *
+ *  Both ingest paths (position-decisions journal + WS audit-trail) use this. */
+export declare function resolveIngestToken(config?: PluginConfigFile): string;
+/** Is the WS authoritative for reads (observe or enforce)? In shadow it's
+ *  only observed — REST remains the source of truth for getPositions etc. */
+export declare function userDataStreamAuthoritative(mode: UserDataStreamMode): boolean;
+/** Should REST polling cadence be reduced? True in observe/enforce where
+ *  WS is carrying the hot-path signal and REST is only a truth-check. */
+export declare function restPollingReduced(mode: UserDataStreamMode): boolean;
+/** Read tunables, falling back to DEFAULT_TUNABLES for any missing field.
+ *  Clamps are defense-in-depth against a truncated or nonsensical config. */
+export declare function getUserDataStreamTunables(config?: PluginConfigFile): UserDataStreamTunables;
+export declare function loadUserDataStreamTunables(): UserDataStreamTunables;
+/** Validate a proposed transition. Returns `{ allowed: false, reason }` when
+ *  the move is blocked so the deploy script can refuse. Forward transitions
+ *  must progress through stages; reverse transitions (to any earlier stage,
+ *  including 'off') are always permitted as a safety-net rollback. */
+export interface TransitionCheck {
+    allowed: boolean;
+    reason?: string;
+}
+export declare function checkTransition(from: UserDataStreamMode, to: UserDataStreamMode): TransitionCheck;

package/config/user-data-stream-config.js

@@ -0,0 +1,224 @@
+// Feature flag reader for the Binance user-data WebSocket stream.
+//
+// Ordering of sources (first hit wins):
+//   1. Remote override from intelligence (set via admin dashboard OTA) — stored
+//      in memory on the plugin after push; not persisted to plugin-config.json.
+//      Wired in Phase 2; for Phase 1 this is always undefined.
+//   2. Local plugin-config.json `userDataStream.mode` field.
+//   3. Default: 'off' (legacy REST polling remains authoritative).
+//
+// Rollout stages:
+//   off     — WS not started. REST polling authoritative.
+//   shadow  — DEPRECATED 2026-05-06. WS runs alongside REST; diffs logged every
+//             60s; REST authoritative. Was the soak stage during the original
+//             rollout; retained as a runtime mode for backward compatibility
+//             with existing plugin-config files but no longer reachable as a
+//             forward transition target. New deployments go off → observe.
+//   observe — WS authoritative for reads; REST drops to 30-60s truth-check.
+//   enforce — Full cutover. Skill-side pollers disabled; REST at 60s only.
+//
+// Transitions must progress forward only (no skipping). Deploy script enforces.
+// Reverse transitions to any earlier stage (including 'shadow' and 'off') are
+// always permitted as a safety-net rollback.
+import { readPluginConfig } from './plugin-config-io.js';
+const VALID = new Set(['off', 'shadow', 'observe', 'enforce']);
+/** Allowed forward transitions. Reverse transitions are always permitted so
+ *  the operator can fall back to REST if WS misbehaves.
+ *
+ *  'shadow' is deprecated as a forward target (2026-05-06): nothing transitions
+ *  TO shadow anymore. Configs that already have 'shadow' continue to work; the
+ *  shadow → observe escape path is preserved so an operator stuck on a
+ *  shadow-configured plugin can still ladder up. */
+const FORWARD_TRANSITIONS = {
+    off: new Set(['observe']),
+    shadow: new Set(['observe']),
+    observe: new Set(['enforce']),
+    enforce: new Set(),
+};
+export const DEFAULT_TUNABLES = {
+    listenKeyRefreshMs: 25 * 60_000, // 25 min
+    reconnectBaseMs: 1_000, // 1 s
+    reconnectCapMs: 60_000, // 60 s
+    // Ping-aware watchdog (refactored 2026-04-25). The watchdog now compares
+    // against `lastFrameAt` — any incoming WS frame including server pings —
+    // not `lastEventAt` (message frames only). Binance documents server pings
+    // every 3 min on the user-data stream:
+    //   "The websocket server will send a ping frame every 3 minutes."
+    //   "If the websocket server does not receive a pong frame back from the
+    //    connection within a 10 minute period, the connection will be disconnected."
+    //   https://developers.binance.com/docs/derivatives/usds-margined-futures/websocket-market-streams
+    // 6 min comfortably exceeds the 180 s ping interval and stays well under
+    // Binance's own 10-min no-pong cutoff. The previous 90 s active threshold
+    // false-fired ~200×/day on idle accounts; the active REST probe (60 s
+    // fetchMyTrades per open-position symbol) is the correct mechanism for
+    // catching missed fills, and remains in place.
+    staleEventWatchdogMs: 6 * 60_000, // 6 min
+    // 60 s. NOT a "cheap" call: the algo refresh is an UNSCOPED fetchOpenOrders
+    // = 80 weight (40 regular + 40 algo, doc-verified developers.binance.com
+    // 2026-05-15). At 15 s that was 4/min × 80 = ~320 weight/min — measured on
+    // prod (binance-ban-gate weight-window summary) as the dominant idle
+    // consumer after the audit-scope fix, pinning the pacer ceiling and
+    // starving the agent's heartbeat reads. ALGO_UPDATE (5a16f05) is now the
+    // AUTHORITATIVE bracket-lifecycle push (terminal events arrive immediately,
+    // not on this poll) and the 60 s bracket-reconciler unscoped sweep
+    // cross-checks, so this periodic full-algo-view refresh only needs to keep
+    // the dashboard's open-orders panel eventually-consistent — 60 s is
+    // operationally invisible. Still clamped 5 s–5 min + plugin-config
+    // overridable for per-VPS tuning.
+    algoRefreshMs: 60_000,
+    // @deprecated — kept for backward compatibility with existing plugin-config
+    // files. Runtime no longer consults this value (see UserDataStreamController
+    // .buildStreamOptions). 90 s default retained so an old config file doesn't
+    // drift silently on field validation.
+    activeStaleEventWatchdogMs: 90_000,
+    // Active probe (added 2026-04-25). 60 s tick polls fetchMyTrades for every
+    // open-position symbol; if any trade timestamp exceeds lastEventAt, the WS
+    // missed a fill and we force-reconnect. Belt + suspenders alongside the
+    // adaptive watchdog. ~5 weight per open position per probe; with 5 positions
+    // = 25 weight/min, well under the 2400/min budget.
+    activeProbeIntervalMs: 60_000,
+};
+/** Read user-data-stream mode from a config object. Invalid values fall back to 'off'. */
+export function getUserDataStreamMode(config, remoteOverride) {
+    if (remoteOverride && VALID.has(remoteOverride))
+        return remoteOverride;
+    const raw = config?.userDataStream?.mode;
+    if (typeof raw === 'string' && VALID.has(raw)) {
+        return raw;
+    }
+    return 'off';
+}
+/** Convenience: load from disk and return the effective mode. */
+export function loadUserDataStreamMode() {
+    try {
+        return getUserDataStreamMode(readPluginConfig());
+    }
+    catch {
+        // Matches loadBracketMode policy: don't gate trading on a corrupt flag read.
+        return 'off';
+    }
+}
+/** Is the WS stream enabled at all (anything other than 'off')? */
+export function userDataStreamEnabled(mode) {
+    return mode !== 'off';
+}
+/** Read the dbWrite flag.  Orthogonal to `mode`: `mode` controls the read
+ *  path (WS vs REST authoritative for getPositions etc.); `dbWrite` controls
+ *  whether WS-observed fills are POSTed to the webapp's audit-trail store.
+ *  Both must be enabled together for WS rows to land in `trades`. */
+export function getUserDataStreamDbWrite(config) {
+    const raw = config?.userDataStream?.dbWrite;
+    return raw === 'on' ? 'on' : 'off';
+}
+export function loadUserDataStreamDbWrite() {
+    try {
+        return getUserDataStreamDbWrite(readPluginConfig());
+    }
+    catch {
+        return 'off';
+    }
+}
+/** Webapp ingest base URL (POST target).  Defaults to production reefclaw.com. */
+export function getUserDataStreamIngestBaseUrl(config) {
+    const raw = config?.userDataStream?.ingestBaseUrl;
+    if (typeof raw === 'string' && /^https?:\/\//.test(raw))
+        return raw;
+    return 'https://www.reefclaw.com';
+}
+/** Resolve the webapp-ingest credential (the per-user `rc_*` token).
+ *
+ *  Prefers `connectionToken` in plugin-config.json — the same `rc_*` token
+ *  already stored there for the intel-service client, so there's one fewer
+ *  place to update on rotation than the legacy `WEBAPP_INGEST_TOKEN` systemd
+ *  env var. Falls back to that env var so existing deployments that haven't
+ *  moved the token into plugin-config.json keep working unchanged.
+ *
+ *  Both ingest paths (position-decisions journal + WS audit-trail) use this. */
+export function resolveIngestToken(config) {
+    const fromConfig = config?.connectionToken;
+    if (typeof fromConfig === 'string' && fromConfig.trim())
+        return fromConfig.trim();
+    return process.env.WEBAPP_INGEST_TOKEN ?? '';
+}
+/** Is the WS authoritative for reads (observe or enforce)? In shadow it's
+ *  only observed — REST remains the source of truth for getPositions etc. */
+export function userDataStreamAuthoritative(mode) {
+    return mode === 'observe' || mode === 'enforce';
+}
+/** Should REST polling cadence be reduced? True in observe/enforce where
+ *  WS is carrying the hot-path signal and REST is only a truth-check. */
+export function restPollingReduced(mode) {
+    return mode === 'observe' || mode === 'enforce';
+}
+/** Read tunables, falling back to DEFAULT_TUNABLES for any missing field.
+ *  Clamps are defense-in-depth against a truncated or nonsensical config. */
+export function getUserDataStreamTunables(config) {
+    const u = config?.userDataStream;
+    const clamp = (v, fallback, min, max) => {
+        if (typeof v !== 'number' || !Number.isFinite(v) || v < min || v > max)
+            return fallback;
+        return v;
+    };
+    return {
+        // listenKey expires at 60 min; refresh must be below that with margin.
+        listenKeyRefreshMs: clamp(u?.listenKeyRefreshMs, DEFAULT_TUNABLES.listenKeyRefreshMs, 60_000, 55 * 60_000),
+        reconnectBaseMs: clamp(u?.reconnectBaseMs, DEFAULT_TUNABLES.reconnectBaseMs, 100, 10_000),
+        reconnectCapMs: clamp(u?.reconnectCapMs, DEFAULT_TUNABLES.reconnectCapMs, 5_000, 300_000),
+        // Lower bound 4 min — any tighter and Binance's documented 3-min ping
+        // interval can fail to update lastFrameAt (jitter, network blips) and
+        // trigger false reconnects. Upper bound 60 min — beyond that we no longer
+        // catch a dead socket before Binance's own 10-min idle timeout would.
+        staleEventWatchdogMs: clamp(u?.staleEventWatchdogMs, DEFAULT_TUNABLES.staleEventWatchdogMs, 4 * 60_000, 60 * 60_000),
+        // 0 = disabled. Otherwise clamp to a reasonable range: 5s minimum (so we
+        // don't hammer REST), 5 min maximum (beyond that the drift window gets
+        // long enough to forcedResync the whole store anyway).
+        algoRefreshMs: clampOrZero(u?.algoRefreshMs, DEFAULT_TUNABLES.algoRefreshMs, 5_000, 5 * 60_000),
+        // @deprecated — read for backward compat with existing plugin-config files
+        // but the runtime no longer wires this into the watchdog. Clamp range left
+        // intact so a bad value in an old config doesn't cause a validation failure
+        // when re-saving the file.
+        activeStaleEventWatchdogMs: clamp(u?.activeStaleEventWatchdogMs, DEFAULT_TUNABLES.activeStaleEventWatchdogMs, 30_000, 5 * 60_000),
+        // 0 = disabled. 10s minimum to keep weight pressure sensible; 10 min
+        // maximum because a probe that runs less often than the stale watchdog
+        // adds no value.
+        activeProbeIntervalMs: clampOrZero(u?.activeProbeIntervalMs, DEFAULT_TUNABLES.activeProbeIntervalMs, 10_000, 10 * 60_000),
+    };
+}
+function clampOrZero(v, fallback, min, max) {
+    if (v === 0)
+        return 0;
+    if (typeof v !== 'number' || !Number.isFinite(v) || v < min || v > max)
+        return fallback;
+    return v;
+}
+export function loadUserDataStreamTunables() {
+    try {
+        return getUserDataStreamTunables(readPluginConfig());
+    }
+    catch {
+        return { ...DEFAULT_TUNABLES };
+    }
+}
+export function checkTransition(from, to) {
+    if (!VALID.has(from))
+        return { allowed: false, reason: `invalid source mode: ${from}` };
+    if (!VALID.has(to))
+        return { allowed: false, reason: `invalid target mode: ${to}` };
+    if (from === to)
+        return { allowed: true };
+    const stageOrder = ['off', 'shadow', 'observe', 'enforce'];
+    const fromIdx = stageOrder.indexOf(from);
+    const toIdx = stageOrder.indexOf(to);
+    // Reverse transitions always allowed (rollback).
+    if (toIdx < fromIdx)
+        return { allowed: true };
+    // Forward transition — must go through next stage only.
+    const allowed = FORWARD_TRANSITIONS[from];
+    if (!allowed.has(to)) {
+        return {
+            allowed: false,
+            reason: `forward transition ${from} → ${to} skips stages (next allowed: ${[...allowed].join(', ') || '(none)'})`,
+        };
+    }
+    return { allowed: true };
+}

package/connector-supervisor.d.ts

@@ -0,0 +1,36 @@
+import { spawn } from 'node:child_process';
+/** Bridge bundled INSIDE the plugin package (the npm-channel distribution
+ *  `@reefclaw/openclaw-plugin` ships the connector at <pluginRoot>/bridge).
+ *  Compiled connector-supervisor.js sits at the plugin dist root, so the
+ *  bundled bridge is a sibling directory. */
+export declare function bundledBridgeDir(): string;
+/** Where the connector lives, in preference order: bundled-in-package first
+ *  (npm-channel install — self-contained), then the npx installer's
+ *  placement. Returns null when neither exists. */
+export declare function resolveBridgeDir(): string | null;
+/** True when the plugin should supervise the connector even WITHOUT an
+ *  explicit connectorSupervisor='on' in plugin-config: the connector is
+ *  bundled inside this plugin package, which only the npm-channel
+ *  distribution does. Prod's linked plugin dir and the npx installer's
+ *  ~/.reefclaw/plugin have no bridge/ subdir, so they stay opt-in — prod
+ *  keeps running the bridge under systemd and must never double-connect. */
+export declare function hasBundledBridge(): boolean;
+export interface ConnectorSupervisorOptions {
+    /** Directory holding the placed bridge (default ~/.reefclaw/bridge). */
+    bridgeDir?: string;
+    /** Injectable spawn for tests. */
+    spawnFn?: typeof spawn;
+}
+export interface ConnectorSupervisorHandle {
+    stop(): void;
+    /** Test/debug introspection. */
+    isRunning(): boolean;
+}
+/**
+ * Start supervising the connector. Idempotent per process — repeat calls
+ * (OpenClaw can invoke register() more than once) return the existing handle.
+ * Returns null when the bridge isn't placed on disk (installer not run).
+ */
+export declare function startConnectorSupervisor(opts?: ConnectorSupervisorOptions): ConnectorSupervisorHandle | null;
+/** Test-only: reset the module singleton. */
+export declare function resetConnectorSupervisorForTest(): void;

package/connector-supervisor.js

@@ -0,0 +1,149 @@
+// Plugin-supervised ReefClaw connector (frictionless-onboarding phase 1).
+//
+// The plugin runs persistently inside the OpenClaw gateway process, so it can
+// supervise the relay connector (the bridge) as a child process — making
+// OpenClaw itself the process manager. This removes every host-level concern
+// from onboarding: no systemd, no terminal, works inside containers, and the
+// connector's lifetime is correctly tied to the gateway's (gateway down ⇒
+// nothing to bridge anyway — the plugin holding the exchange keys lives in
+// the same process).
+//
+// SAFETY: default OFF. Prod runs the bridge as `reefclaw-skill.service`
+// (systemd) — a supervisor turned on there would double-connect the relay
+// room. Only the fresh-install path (the npx installer) writes
+// `connectorSupervisor: 'on'` into ~/.reefclaw/plugin-config.json.
+// Kill-switch: RC_CONNECTOR_SUPERVISOR=off beats config.
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { logger } from './logger.js';
+const TAG = 'connector-supervisor';
+/** Bridge bundled INSIDE the plugin package (the npm-channel distribution
+ *  `@reefclaw/openclaw-plugin` ships the connector at <pluginRoot>/bridge).
+ *  Compiled connector-supervisor.js sits at the plugin dist root, so the
+ *  bundled bridge is a sibling directory. */
+export function bundledBridgeDir() {
+    return join(dirname(fileURLToPath(import.meta.url)), 'bridge');
+}
+/** Where the connector lives, in preference order: bundled-in-package first
+ *  (npm-channel install — self-contained), then the npx installer's
+ *  placement. Returns null when neither exists. */
+export function resolveBridgeDir() {
+    for (const dir of [bundledBridgeDir(), join(homedir(), '.reefclaw', 'bridge')]) {
+        if (existsSync(join(dir, 'index.js')))
+            return dir;
+    }
+    return null;
+}
+/** True when the plugin should supervise the connector even WITHOUT an
+ *  explicit connectorSupervisor='on' in plugin-config: the connector is
+ *  bundled inside this plugin package, which only the npm-channel
+ *  distribution does. Prod's linked plugin dir and the npx installer's
+ *  ~/.reefclaw/plugin have no bridge/ subdir, so they stay opt-in — prod
+ *  keeps running the bridge under systemd and must never double-connect. */
+export function hasBundledBridge() {
+    return existsSync(join(bundledBridgeDir(), 'index.js'));
+}
+const MIN_BACKOFF_MS = 5_000;
+const MAX_BACKOFF_MS = 60_000;
+/** A child that survives this long resets the backoff (it was healthy). */
+const STABLE_RESET_MS = 5 * 60_000;
+let singleton = null;
+/**
+ * Start supervising the connector. Idempotent per process — repeat calls
+ * (OpenClaw can invoke register() more than once) return the existing handle.
+ * Returns null when the bridge isn't placed on disk (installer not run).
+ */
+export function startConnectorSupervisor(opts = {}) {
+    if (singleton)
+        return singleton;
+    const bridgeDir = opts.bridgeDir ?? resolveBridgeDir();
+    if (!bridgeDir) {
+        logger.warn(TAG, 'connector not found (no bundled bridge/ and no ~/.reefclaw/bridge) — supervisor idle');
+        return null;
+    }
+    const indexJs = join(bridgeDir, 'index.js');
+    if (!existsSync(indexJs)) {
+        logger.warn(TAG, `connector not found at ${indexJs} — supervisor idle`);
+        return null;
+    }
+    const spawnFn = opts.spawnFn ?? spawn;
+    let child = null;
+    let stopped = false;
+    let backoffMs = MIN_BACKOFF_MS;
+    let restartTimer = null;
+    const launch = () => {
+        if (stopped)
+            return;
+        const startedAt = Date.now();
+        // NOT detached: the connector must die with the gateway (a gateway
+        // restart resurrects both, and an orphan bridge can never linger).
+        child = spawnFn(process.execPath, [indexJs, '--provider', 'gateway', '--log-level', 'info'], {
+            cwd: bridgeDir,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        logger.info(TAG, `connector started (pid ${child.pid})`);
+        const forward = (stream, level) => {
+            stream?.on('data', (chunk) => {
+                for (const line of chunk.toString().split('\n')) {
+                    if (line.trim())
+                        logger[level](TAG, `[connector] ${line}`);
+                }
+            });
+        };
+        forward(child.stdout, 'info');
+        forward(child.stderr, 'warn');
+        child.on('exit', (code, signal) => {
+            child = null;
+            if (stopped)
+                return;
+            const aliveMs = Date.now() - startedAt;
+            if (aliveMs >= STABLE_RESET_MS)
+                backoffMs = MIN_BACKOFF_MS;
+            // Exit is EXPECTED pre-token (the connector exits until the connect
+            // message is saved) — restart with backoff, exactly like systemd's
+            // Restart=always did.
+            logger.info(TAG, `connector exited (code=${code ?? 'null'} signal=${signal ?? 'null'} after ${Math.round(aliveMs / 1000)}s) — restarting in ${backoffMs / 1000}s`);
+            restartTimer = setTimeout(launch, backoffMs);
+            restartTimer.unref?.();
+            backoffMs = Math.min(backoffMs * 2, MAX_BACKOFF_MS);
+        });
+        child.on('error', (err) => {
+            logger.error(TAG, `connector spawn failed: ${err.message}`);
+            child = null;
+            if (stopped)
+                return;
+            restartTimer = setTimeout(launch, backoffMs);
+            restartTimer.unref?.();
+            backoffMs = Math.min(backoffMs * 2, MAX_BACKOFF_MS);
+        });
+    };
+    launch();
+    const handle = {
+        stop() {
+            stopped = true;
+            if (restartTimer)
+                clearTimeout(restartTimer);
+            if (child) {
+                try {
+                    child.kill('SIGTERM');
+                }
+                catch {
+                    /* already gone */
+                }
+            }
+            singleton = null;
+        },
+        isRunning() {
+            return child !== null;
+        },
+    };
+    singleton = handle;
+    return handle;
+}
+/** Test-only: reset the module singleton. */
+export function resetConnectorSupervisorForTest() {
+    singleton = null;
+}

package/exchange-adapter.d.ts

@@ -0,0 +1,49 @@
+import type { CcxtOrder, CcxtBalance, CcxtPosition, TradingMode } from './types.js';
+import type { PositionMetadata, CloseReason } from './simulator/types.js';
+/** Adapter readiness state machine: INIT_PENDING → READY | DEGRADED | BLOCKED */
+export type AdapterReadiness = 'INIT_PENDING' | 'READY' | 'DEGRADED' | 'BLOCKED';
+/** Options for order submission. */
+export interface OrderOptions {
+    clientOrderId?: string;
+    reduceOnly?: boolean;
+    positionSide?: 'LONG' | 'SHORT' | 'BOTH';
+    emergency?: boolean;
+}
+/**
+ * Common exchange adapter interface.
+ * Implemented by PaperAdapter (wrapping ExchangeSimulator) and LiveAdapter (wrapping BinancePrivateApi).
+ *
+ * Trade tools call adapter methods instead of directly referencing the simulator.
+ * Emergency controls (cancel, close) have NO readiness gate — they ALWAYS work.
+ * Only create_order is blocked when readiness !== 'READY'.
+ */
+export interface IExchangeAdapter {
+    createOrder(symbol: string, side: 'buy' | 'sell', type: 'market' | 'limit', amount: number, price?: number, metadata?: PositionMetadata, options?: OrderOptions): Promise<CcxtOrder>;
+    cancelOrder(orderId: string, symbol?: string): Promise<CcxtOrder>;
+    cancelAllOrders(symbol?: string): Promise<CcxtOrder[]>;
+    /** Close a position at market.
+     *  @param closeReason Tags the resulting Trade record with who initiated the close.
+     *    Paper mode persists it on the closing Trade.metadata.closeReason so the agent
+     *    can see on its next heartbeat that e.g. a stop_watcher auto-closed the trade.
+     *    Live mode currently ignores this (metadata not tracked in live path). */
+    closePosition(symbol: string, closeReason?: CloseReason): Promise<CcxtOrder>;
+    getBalance(): Promise<CcxtBalance>;
+    getPositions(symbol?: string): Promise<CcxtPosition[]>;
+    /**
+     * Like getPositions(), but returns `null` (not `[]`) when the underlying
+     * exchange fetch FAILED (429 / weight-paced / transient) — i.e. position
+     * state is UNKNOWN, not "flat". Decision/destructive paths (flatten, audit,
+     * portfolio snapshot, attach_brackets, reconciler) MUST use this and treat
+     * `null` as "do not act on a phantom-empty account". getPositions() keeps
+     * the `?? []` display contract for the 20+ KPI/display callers
+     * (KPI-must-equal-Binance invariant). Paper adapters never fail a fetch, so
+     * this is equivalent to getPositions() there.
+     */
+    getPositionsOrNull(symbol?: string): Promise<CcxtPosition[] | null>;
+    getOpenOrders(symbol?: string): Promise<CcxtOrder[]>;
+    fetchOrder(orderId: string, symbol?: string): Promise<CcxtOrder | null>;
+    getLastPrice(symbol: string): Promise<number | null>;
+    readonly readiness: AdapterReadiness;
+    readonly mode: TradingMode;
+    readonly isLive: boolean;
+}

package/exchange-adapter.js

@@ -0,0 +1,4 @@
+// Exchange adapter interface — common abstraction over ExchangeSimulator (paper) and BinancePrivateApi (live).
+// Both PaperAdapter and LiveAdapter implement this interface.
+// All methods return Promise for uniform call sites — paper adapter wraps sync results in Promise.resolve().
+export {};

package/index.d.ts

@@ -0,0 +1,30 @@
+interface PluginApi {
+    registerTool: (tool: any, opts?: {
+        names?: string[];
+        optional?: boolean;
+    }) => void;
+    config?: any;
+    [key: string]: any;
+}
+declare const paperTradingPlugin: {
+    id: string;
+    name: string;
+    description: string;
+    configSchema: {
+        type: "object";
+        properties: {
+            startingBalance: {
+                type: "number";
+                default: number;
+                description: string;
+            };
+            symbol: {
+                type: "string";
+                default: string;
+                description: string;
+            };
+        };
+    };
+    register(api: PluginApi): void;
+};
+export default paperTradingPlugin;