@reefclaw/connect 0.1.39 → 0.1.41

package/README.md

@@ -0,0 +1,23 @@
+# @reefclaw/connect
+
+One-command installer that connects an OpenClaw agent to [ReefClaw](https://reefclaw.com) for paper trading. No exchange keys are needed for paper mode.
+
+```
+npx -y @reefclaw/connect
+```
+
+It places two things next to your OpenClaw install: the ReefClaw trading plugin (tools the agent calls) and the bridge (a small daemon that links your gateway to the ReefClaw dashboard over an outbound WebSocket). Re-running the command updates both in place, then restarts the gateway.
+
+Requirements: Node 20 or newer for the installer itself, and whatever your OpenClaw version needs (OpenClaw 2026.9.3 and later requires Node 24).
+
+## Notes for self-hosters
+
+**One gateway per trading agent.** OpenClaw broadcasts every agent's run events to every operator connection, and an operator token can't be scoped to a single agent. The bridge keeps only its own agent's runs. It follows the gateway's default agent (the one the installer set up) with no configuration; if your trading agent is a different one, set `OPENCLAW_AGENT_ID` or `"agentId"` in `~/.reefclaw/plugin-config.json`. The cleanest setup for a gateway that hosts other agents is still a separate gateway instance for the trading agent.
+
+**One-click updates from the dashboard.** The "Update connector" button asks the bridge to run `npx -y @reefclaw/connect@latest` in a gateway terminal on your box. The command is a fixed constant; nothing from the dashboard or relay is interpolated into it. If you'd rather run updates yourself (for example because you carry local patches), switch it off per host with `REEFCLAW_ALLOW_CONNECTOR_UPDATE=0` in the bridge's environment or `"connectorUpdate": "off"` in `~/.reefclaw/plugin-config.json`. Setting `gateway.terminal.enabled=false` in `openclaw.json` disables it at the gateway level too. The dashboard then shows the manual command instead.
+
+**Paper fills.** The paper engine prices market fills off a cached order book. Since 0.1.41 a fill whose book has drifted more than 10 bps from the decision price is anchored to the decision price (stop breaches and target hits used to fill at entry-time levels).
+
+## Reporting issues
+
+Mail support@reefclaw.com. Security reports are welcome at the same address; please keep them at the design level until we've replied.

package/assets/bridge/config.d.ts

@@ -20,6 +20,13 @@ export declare function writeOpenClawConfig(token: string, userId?: string, rela
  *  guess. An empty/absent list is treated as "no evidence" (not a downgrade
  *  trigger): some builds omit the field, and acting on silence would recreate
  *  the speculative relaxation this replaced. */
+/** True when the gateway REJECTED the connect handshake because the client
+ *  carries no device identity — OpenClaw >= 2026.9 closes a control-UI client
+ *  (the bridge presents as `openclaw-tui`) with 1008 "control ui requires
+ *  device identity (use HTTPS or localhost secure context)" on an unrelaxed
+ *  gateway. Because the handshake never completes, handshakeLacksWriteScope
+ *  never gets to run — this is the equivalent proven-need signal for it. */
+export declare function isDeviceIdentityRejection(code: number | undefined, reason: string | undefined): boolean;
 export declare function handshakeLacksWriteScope(scopes: readonly string[] | undefined): boolean;
 /**
  * LAST RESORT: relax the local gateway's device-identity auth because a

package/assets/bridge/config.js

@@ -147,6 +147,19 @@ function applyGatewayAuthRelaxation(config) {
  *  guess. An empty/absent list is treated as "no evidence" (not a downgrade
  *  trigger): some builds omit the field, and acting on silence would recreate
  *  the speculative relaxation this replaced. */
+/** True when the gateway REJECTED the connect handshake because the client
+ *  carries no device identity — OpenClaw >= 2026.9 closes a control-UI client
+ *  (the bridge presents as `openclaw-tui`) with 1008 "control ui requires
+ *  device identity (use HTTPS or localhost secure context)" on an unrelaxed
+ *  gateway. Because the handshake never completes, handshakeLacksWriteScope
+ *  never gets to run — this is the equivalent proven-need signal for it. */
+export function isDeviceIdentityRejection(code, reason) {
+    if (typeof reason !== 'string' || reason.length === 0)
+        return false;
+    if (code !== undefined && code !== 1008 && code !== 4000)
+        return false;
+    return /device identity/i.test(reason);
+}
 export function handshakeLacksWriteScope(scopes) {
     if (!Array.isArray(scopes) || scopes.length === 0)
         return false;

package/assets/bridge/gateway/agent-scope.d.ts

@@ -0,0 +1,30 @@
+/** OpenClaw's default agent id, the one the installer sets the trading agent
+ *  up as, and the id the bridge has always addressed chat to. */
+export declare const DEFAULT_AGENT_ID = "main";
+/** Trim + lowercase (OpenClaw normalizes ids the same way). Undefined for
+ *  anything that is not a non-empty string. */
+export declare function normalizeAgentId(value: unknown): string | undefined;
+/** `agent:<agentId>:<rest>` → `<agentId>`. Undefined when the key carries no
+ *  agent scope (legacy keys, `global`, `unknown`, missing). */
+export declare function resolveAgentIdFromSessionKey(sessionKey: unknown): string | undefined;
+/**
+ * OpenClaw's own rule for the gateway's default agent (agent-scope-config.ts
+ * `resolveDefaultAgentId`): the `agents.list` entry flagged `default: true`,
+ * else the first entry, else `main`. The installer places the ReefClaw skill
+ * in that agent's workspace and the heartbeat cron runs on it, so with no
+ * override the default agent IS the trading agent. Nobody has to configure
+ * anything; an override exists for hand-built multi-agent setups.
+ */
+export declare function resolveDefaultAgentIdFromConfig(cfg: unknown): string;
+/** The agent an event belongs to, when the payload says. An explicit
+ *  `agentId` field wins (future-proofing; today's gateway sends only the
+ *  session key). */
+export declare function resolveAgentEventOwner(payload: {
+    agentId?: unknown;
+    sessionKey?: unknown;
+}): string | undefined;
+/** True when the event is attributable to an agent OTHER than ours. */
+export declare function isForeignAgentEvent(payload: {
+    agentId?: unknown;
+    sessionKey?: unknown;
+}, ownAgentId: string): boolean;

package/assets/bridge/gateway/agent-scope.js

@@ -0,0 +1,67 @@
+// Which OpenClaw agent this bridge belongs to, and how to tell whose run an
+// incoming `agent` event is.
+//
+// An OpenClaw gateway can host several agents (`agents.list`), and it
+// broadcasts EVERY agent's run events to EVERY operator connection —
+// `sendAgentPayload` → `broadcast('agent', …)` in OpenClaw's server-chat.ts
+// carries no per-agent scoping, and an operator token cannot be scoped to one
+// agent. Until 2026-09-16 the bridge forwarded whatever arrived, so on a
+// shared gateway a second agent's morning briefing streamed into the ReefClaw
+// dashboard chat and across the relay (reported by a self-hosting subscriber
+// against 0.1.31 and 0.1.40). The only owner marker on the event is its
+// session key: `agent:<agentId>:<rest>` (OpenClaw routing/session-key.ts).
+//
+// Fail-open on purpose: an event with NO attributable session key (older
+// gateways omit it; legacy/unscoped keys such as `global`) is treated as our
+// own. Dropping it would blind the chat on exactly the single-agent boxes
+// that cannot leak anything.
+/** OpenClaw's default agent id, the one the installer sets the trading agent
+ *  up as, and the id the bridge has always addressed chat to. */
+export const DEFAULT_AGENT_ID = 'main';
+/** Trim + lowercase (OpenClaw normalizes ids the same way). Undefined for
+ *  anything that is not a non-empty string. */
+export function normalizeAgentId(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim().toLowerCase();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+/** `agent:<agentId>:<rest>` → `<agentId>`. Undefined when the key carries no
+ *  agent scope (legacy keys, `global`, `unknown`, missing). */
+export function resolveAgentIdFromSessionKey(sessionKey) {
+    if (typeof sessionKey !== 'string')
+        return undefined;
+    const key = sessionKey.trim();
+    if (!/^agent:/i.test(key))
+        return undefined;
+    return normalizeAgentId(key.split(':')[1]);
+}
+/**
+ * OpenClaw's own rule for the gateway's default agent (agent-scope-config.ts
+ * `resolveDefaultAgentId`): the `agents.list` entry flagged `default: true`,
+ * else the first entry, else `main`. The installer places the ReefClaw skill
+ * in that agent's workspace and the heartbeat cron runs on it, so with no
+ * override the default agent IS the trading agent. Nobody has to configure
+ * anything; an override exists for hand-built multi-agent setups.
+ */
+export function resolveDefaultAgentIdFromConfig(cfg) {
+    const list = cfg?.agents?.list;
+    if (!Array.isArray(list))
+        return DEFAULT_AGENT_ID;
+    const entries = list.filter((e) => !!e && typeof e === 'object' && !Array.isArray(e));
+    if (entries.length === 0)
+        return DEFAULT_AGENT_ID;
+    const chosen = entries.find((e) => e.default === true) ?? entries[0];
+    return normalizeAgentId(chosen.id) ?? DEFAULT_AGENT_ID;
+}
+/** The agent an event belongs to, when the payload says. An explicit
+ *  `agentId` field wins (future-proofing; today's gateway sends only the
+ *  session key). */
+export function resolveAgentEventOwner(payload) {
+    return normalizeAgentId(payload.agentId) ?? resolveAgentIdFromSessionKey(payload.sessionKey);
+}
+/** True when the event is attributable to an agent OTHER than ours. */
+export function isForeignAgentEvent(payload, ownAgentId) {
+    const owner = resolveAgentEventOwner(payload);
+    return owner !== undefined && owner !== (normalizeAgentId(ownAgentId) ?? DEFAULT_AGENT_ID);
+}

package/assets/bridge/gateway/gateway-config.d.ts

@@ -16,6 +16,13 @@ export interface GatewayConfig {
      *  Optional so a hand-built config (tests, embedders) stays valid; every
      *  consumer treats absent as 'binance', the historical behaviour. */
     venue?: VenueId;
+    /** The OpenClaw agent this bridge serves: chat is addressed to it and ONLY
+     *  its run events reach the dashboard (gateway/agent-scope.ts). Optional so
+     *  a hand-built config stays valid; consumers default to 'main'. */
+    agentId?: string;
+    /** Per-host switch for the dashboard's one-click connector update, which
+     *  opens a PTY on this box (providers/connector-update.ts). Absent = allowed. */
+    allowConnectorUpdate?: boolean;
 }
 /** CLI args specific to gateway provider */
 export interface GatewayCliArgs {
@@ -23,14 +30,20 @@ export interface GatewayCliArgs {
     gatewayToken?: string;
     symbol?: string;
     intelligenceUrl?: string;
+    agentId?: string;
 }
+/** `1/true/on/yes/enabled` → true, `0/false/off/no/disabled` → false, anything
+ *  else (unset, blank, garbage) → undefined so the next source is consulted. */
+export declare function parseOnOffSwitch(raw: unknown): boolean | undefined;
 /**
  * Resolve gateway connection config with priority:
- * 1. CLI args (--gateway-url, --gateway-token, --symbol)
+ * 1. CLI args (--gateway-url, --gateway-token, --symbol, --agent-id)
  * 2. Env vars (OPENCLAW_GATEWAY_URL, OPENCLAW_GATEWAY_TOKEN, REEFCLAW_SYMBOL,
- *    REEFCLAW_INTELLIGENCE_URL, REEFCLAW_VENUE)
+ *    REEFCLAW_INTELLIGENCE_URL, REEFCLAW_VENUE, OPENCLAW_AGENT_ID,
+ *    REEFCLAW_ALLOW_CONNECTOR_UPDATE)
  * 3. Config files (~/.openclaw/openclaw.json, ~/.reefclaw/plugin-config.json)
- * 4. Defaults (localhost:18789, the venue's default symbol, intel.reefclaw.com)
+ * 4. Defaults (localhost:18789, the venue's default symbol, intel.reefclaw.com,
+ *    the gateway's default agent)
  *
  * Returns null for gatewayToken if it can't be resolved (caller must handle).
  * `intelligenceUrl` is never null — see DEFAULT_INTELLIGENCE_URL for why that
@@ -42,6 +55,8 @@ export declare function resolveGatewayConfig(args: GatewayCliArgs): {
     symbol: string;
     intelligenceUrl: string;
     venue: VenueId;
+    agentId: string;
+    allowConnectorUpdate: boolean;
 };
 /**
  * Validate that the resolved config has all required fields.

package/assets/bridge/gateway/gateway-config.js

@@ -7,6 +7,7 @@ import { homedir } from 'os';
 import JSON5 from 'json5';
 import { parseVenue, VENUE_DEFAULT_SYMBOL } from '@reefclaw/shared';
 import { logger } from '../logger.js';
+import { normalizeAgentId, resolveDefaultAgentIdFromConfig } from './agent-scope.js';
 const TAG = 'gateway-config';
 const DEFAULT_GATEWAY_PORT = 18789;
 const DEFAULT_GATEWAY_HOST = 'localhost';
@@ -70,14 +71,30 @@ function readPluginConfig() {
         return null;
     }
 }
+/** `1/true/on/yes/enabled` → true, `0/false/off/no/disabled` → false, anything
+ *  else (unset, blank, garbage) → undefined so the next source is consulted. */
+export function parseOnOffSwitch(raw) {
+    if (typeof raw === 'boolean')
+        return raw;
+    if (typeof raw !== 'string')
+        return undefined;
+    const v = raw.trim().toLowerCase();
+    if (['1', 'true', 'on', 'yes', 'enabled'].includes(v))
+        return true;
+    if (['0', 'false', 'off', 'no', 'disabled'].includes(v))
+        return false;
+    return undefined;
+}
 // ---- Resolve gateway config ----
 /**
  * Resolve gateway connection config with priority:
- * 1. CLI args (--gateway-url, --gateway-token, --symbol)
+ * 1. CLI args (--gateway-url, --gateway-token, --symbol, --agent-id)
  * 2. Env vars (OPENCLAW_GATEWAY_URL, OPENCLAW_GATEWAY_TOKEN, REEFCLAW_SYMBOL,
- *    REEFCLAW_INTELLIGENCE_URL, REEFCLAW_VENUE)
+ *    REEFCLAW_INTELLIGENCE_URL, REEFCLAW_VENUE, OPENCLAW_AGENT_ID,
+ *    REEFCLAW_ALLOW_CONNECTOR_UPDATE)
  * 3. Config files (~/.openclaw/openclaw.json, ~/.reefclaw/plugin-config.json)
- * 4. Defaults (localhost:18789, the venue's default symbol, intel.reefclaw.com)
+ * 4. Defaults (localhost:18789, the venue's default symbol, intel.reefclaw.com,
+ *    the gateway's default agent)
  *
  * Returns null for gatewayToken if it can't be resolved (caller must handle).
  * `intelligenceUrl` is never null — see DEFAULT_INTELLIGENCE_URL for why that
@@ -127,9 +144,30 @@ export function resolveGatewayConfig(args) {
         || process.env.REEFCLAW_INTELLIGENCE_URL
         || pluginConfig?.intelligenceUrl
         || DEFAULT_INTELLIGENCE_URL;
+    // --- Agent id ---
+    // CLI > env > plugin-config.json agentId > the gateway's DEFAULT agent from
+    // openclaw.json (OpenClaw's own rule, see resolveDefaultAgentIdFromConfig)
+    // > 'main'. Zero configuration for every installer-built box: the installer
+    // puts the skill in the default agent's workspace and the heartbeat cron
+    // runs on it. ONE value drives both chat addressing and the agent-event
+    // filter (agent-scope.ts), so a multi-agent gateway can never end up
+    // chatting to one agent while displaying another's runs.
+    const overrideAgentId = normalizeAgentId(args.agentId)
+        ?? normalizeAgentId(process.env.OPENCLAW_AGENT_ID)
+        ?? normalizeAgentId(pluginConfig?.agentId);
+    const agentId = overrideAgentId ?? resolveDefaultAgentIdFromConfig(ocConfig);
+    const agentIdSource = overrideAgentId ? 'configured override' : 'gateway default agent';
+    // --- One-click connector update switch ---
+    // env > plugin-config.json connectorUpdate > allowed. A per-host opt-out
+    // for the dashboard's "Update connector" (which opens a PTY on this box);
+    // see providers/connector-update.ts.
+    const allowConnectorUpdate = parseOnOffSwitch(process.env.REEFCLAW_ALLOW_CONNECTOR_UPDATE)
+        ?? parseOnOffSwitch(pluginConfig?.connectorUpdate)
+        ?? true;
     logger.info(TAG, `Intelligence service: ${intelligenceUrl} (venue=${venue})`);
+    logger.info(TAG, `Agent: ${agentId} (${agentIdSource}); one-click connector update: ${allowConnectorUpdate ? 'allowed' : 'DISABLED on this box'}`);
     logger.debug(TAG, `Resolved: url=${gatewayUrl}, token=${gatewayToken ? '***' : '(none)'}, symbol=${symbol}`);
-    return { gatewayUrl, gatewayToken, symbol, intelligenceUrl, venue };
+    return { gatewayUrl, gatewayToken, symbol, intelligenceUrl, venue, agentId, allowConnectorUpdate };
 }
 /**
  * Validate that the resolved config has all required fields.

package/assets/bridge/gateway/gateway-ws-client.d.ts

@@ -1,5 +1,9 @@
 import { type ReconnectConfig as BaseReconnectConfig } from '../utils/reconnect.js';
 import type { GatewayConfig } from './gateway-config.js';
+export type GatewayClientId = 'gateway-client' | 'openclaw-tui';
+export declare const DEFAULT_CLIENT_IDENTITIES: readonly GatewayClientId[];
+/** The gateway's wording when a control-UI client has no device identity. */
+export declare function isDeviceIdentityRejectionMessage(message: string | undefined | null): boolean;
 interface ReconnectConfig extends BaseReconnectConfig {
     /** Fast-backoff attempts before falling back to the slow retry loop */
     maxFastAttempts: number;
@@ -47,6 +51,7 @@ export type GatewayWsEventPayload = {
         seq?: number;
         sessionKey?: string;
         sessionId?: string;
+        agentId?: string;
     };
     presence: {
         payload: unknown;
@@ -80,8 +85,21 @@ export declare class GatewayWsClient {
     private readonly gatewayUrl;
     private readonly gatewayToken;
     private readonly requestAdminScope;
+    /** Identities to try, in order (see the client-identity note above). */
+    private readonly identities;
+    private identityIndex;
+    /** Scope the handshake must grant, else the next identity is tried. */
+    private readonly requireScope;
+    /** Set when the current socket is being closed ON PURPOSE to retry the
+     *  handshake under the next identity: the close handler then reconnects
+     *  immediately (no backoff, no 'disconnected' event). */
+    private identitySwitchPending;
     constructor(config: Pick<GatewayConfig, 'gatewayUrl' | 'gatewayToken'> & {
         requestAdminScope?: boolean;
+        /** Override the identity ladder (e.g. `[winningId]` for a side session). */
+        identities?: readonly GatewayClientId[];
+        /** Scope the handshake must grant (default operator.write); null = any. */
+        requireScope?: string | null;
     }, reconnect?: Partial<ReconnectConfig>);
     /** Start the WebSocket connection and handshake */
     connect(): void;
@@ -100,6 +118,12 @@ export declare class GatewayWsClient {
     getState(): GatewayWsState;
     /** Get the hello-ok snapshot from the last successful connection */
     getHelloOk(): HelloOkPayload | null;
+    /** The client identity currently in use (the one the gateway admitted, once connected). */
+    getClientId(): GatewayClientId;
+    private hasNextIdentity;
+    /** Close the current socket and retry the handshake under the next identity. */
+    private switchIdentity;
+    private completeIdentitySwitch;
     /** Get stored device token (for future connects) */
     getDeviceToken(): string | null;
     private handleMessage;

package/assets/bridge/gateway/gateway-ws-client.js

@@ -28,8 +28,12 @@ function isLoopbackHost(hostAndRest) {
 // gets `1002 protocol mismatch` there and the bridge can never connect).
 const MIN_PROTOCOL_VERSION = 3;
 const MAX_PROTOCOL_VERSION = 4;
-const CLIENT_ID = 'openclaw-tui';
+export const DEFAULT_CLIENT_IDENTITIES = ['gateway-client', 'openclaw-tui'];
 const CLIENT_VERSION = '0.1.0';
+/** The gateway's wording when a control-UI client has no device identity. */
+export function isDeviceIdentityRejectionMessage(message) {
+    return typeof message === 'string' && /device identity/i.test(message);
+}
 // Mirrors the relay connector's proven shape (see connector.ts DEFAULT_RECONNECT):
 // a bounded fast-backoff burst, then a slow retry that NEVER gives up.
 //
@@ -76,8 +80,20 @@ export class GatewayWsClient {
     gatewayUrl;
     gatewayToken;
     requestAdminScope;
+    /** Identities to try, in order (see the client-identity note above). */
+    identities;
+    identityIndex = 0;
+    /** Scope the handshake must grant, else the next identity is tried. */
+    requireScope;
+    /** Set when the current socket is being closed ON PURPOSE to retry the
+     *  handshake under the next identity: the close handler then reconnects
+     *  immediately (no backoff, no 'disconnected' event). */
+    identitySwitchPending = false;
     constructor(config, reconnect) {
         this.requestAdminScope = config.requestAdminScope === true;
+        this.identities =
+            config.identities && config.identities.length > 0 ? [...config.identities] : [...DEFAULT_CLIENT_IDENTITIES];
+        this.requireScope = config.requireScope === undefined ? 'operator.write' : config.requireScope;
         // Convert to WebSocket URL: http→ws, https→wss. A bare host:port defaults
         // by destination: loopback → ws:// (the normal localhost gateway), anything
         // else → wss:// — a remote default must never silently downgrade to
@@ -126,9 +142,22 @@ export class GatewayWsClient {
             logger.info(TAG, `WebSocket closed: ${code} ${reasonStr}`);
             this.ws = null;
             this.clearStaleTimer();
+            if (this.identitySwitchPending && !this.destroyed) {
+                // Closed on purpose to retry the handshake under the next identity:
+                // no 'disconnected' event, no backoff.
+                this.completeIdentitySwitch();
+                return;
+            }
             this.rejectAllPending('Connection closed');
             if (this.destroyed)
                 return;
+            // A device-identity rejection that arrived only as a close frame (no
+            // error response): still worth the next identity.
+            if (code === 1008 && isDeviceIdentityRejectionMessage(reasonStr) && this.hasNextIdentity()) {
+                this.identitySwitchPending = true;
+                this.completeIdentitySwitch();
+                return;
+            }
             const wasConnected = this.state === 'connected' || this.state === 'handshaking';
             if (wasConnected) {
                 this.emit('disconnected', { code, reason: reasonStr });
@@ -202,6 +231,40 @@ export class GatewayWsClient {
     getHelloOk() {
         return this.lastHelloOk;
     }
+    /** The client identity currently in use (the one the gateway admitted, once connected). */
+    getClientId() {
+        return this.identities[this.identityIndex];
+    }
+    hasNextIdentity() {
+        return this.identityIndex + 1 < this.identities.length;
+    }
+    /** Close the current socket and retry the handshake under the next identity. */
+    switchIdentity(why) {
+        const from = this.getClientId();
+        const to = this.identities[this.identityIndex + 1];
+        logger.warn(TAG, `Gateway would not take client id ${from} (${why}) — retrying the handshake as ${to}`);
+        // No rejectAllPending here: the handshake's pending entry is already gone
+        // (handleResponse deletes it before invoking resolve/reject, and this can
+        // run from inside that reject), so the close handler does the rest.
+        this.identitySwitchPending = true;
+        const ws = this.ws;
+        if (ws && ws.readyState === WebSocket.OPEN) {
+            ws.close(4000, 'identity switch');
+        }
+        else {
+            this.completeIdentitySwitch();
+        }
+    }
+    completeIdentitySwitch() {
+        this.identitySwitchPending = false;
+        this.identityIndex++;
+        this.attempt = 0;
+        this.ws = null;
+        // connect() refuses to run while 'handshaking' — the state the rejected
+        // attempt left behind.
+        this.setState('disconnected');
+        this.connect();
+    }
     /** Get stored device token (for future connects) */
     getDeviceToken() {
         return this.deviceToken;
@@ -281,6 +344,9 @@ export class GatewayWsClient {
                         seq: frame.seq,
                         ...(typeof p.sessionKey === 'string' ? { sessionKey: p.sessionKey } : {}),
                         ...(typeof p.sessionId === 'string' ? { sessionId: p.sessionId } : {}),
+                        // Not sent by today's gateway (the owner rides in sessionKey);
+                        // forwarded if a future build adds it — see agent-scope.ts.
+                        ...(typeof p.agentId === 'string' ? { agentId: p.agentId } : {}),
                     });
                 }
                 break;
@@ -321,7 +387,7 @@ export class GatewayWsClient {
                 minProtocol: MIN_PROTOCOL_VERSION,
                 maxProtocol: MAX_PROTOCOL_VERSION,
                 client: {
-                    id: CLIENT_ID,
+                    id: this.getClientId(),
                     version: CLIENT_VERSION,
                     platform: 'node',
                     mode: 'backend',
@@ -357,7 +423,12 @@ export class GatewayWsClient {
             resolve: () => { },
             reject: (err) => {
                 logger.error(TAG, `Handshake failed: ${err.message}`);
-                this.ws?.close(4000, 'Handshake rejected');
+                if (isDeviceIdentityRejectionMessage(err.message) && this.hasNextIdentity()) {
+                    this.switchIdentity(err.message);
+                    return;
+                }
+                // Carry the gateway's reason (close reasons are capped at 123 bytes).
+                this.ws?.close(4000, `Handshake rejected: ${err.message}`.slice(0, 120));
             },
             timer,
         });
@@ -369,7 +440,19 @@ export class GatewayWsClient {
      * Extracts policy, snapshot, and device token.
      */
     handleHelloOk(payload) {
-        logger.info(TAG, `Connected to gateway (protocol=${payload.protocol})`);
+        // Older builds admit `gateway-client` but strip its scopes: without the
+        // required scope this session is useless — retry as the next identity
+        // rather than accept a connection that cannot trade.
+        const granted = payload.auth?.scopes;
+        if (this.requireScope &&
+            Array.isArray(granted) &&
+            granted.length > 0 &&
+            !granted.includes(this.requireScope) &&
+            this.hasNextIdentity()) {
+            this.switchIdentity(`granted [${granted.join(', ')}] without ${this.requireScope}`);
+            return;
+        }
+        logger.info(TAG, `Connected to gateway (protocol=${payload.protocol}, client=${this.getClientId()})`);
         this.lastHelloOk = payload;
         this.attempt = 0; // Reset reconnect counter
         this.slowRetryActive = false; // Back on the fast budget for the next drop

package/assets/bridge/index.js

@@ -91,6 +91,10 @@ function parseArgs() {
                 gateway.symbol = next;
                 i++;
                 break;
+            case '--agent-id':
+                gateway.agentId = next;
+                i++;
+                break;
             case '--log-level':
             case '-l':
                 if (['debug', 'info', 'warn', 'error'].includes(next)) {
@@ -118,36 +122,37 @@ function parseArgs() {
     return { cli, gateway };
 }
 function printUsage() {
-    console.log(`
-ReefClaw Skill — Bridge between OpenClaw and ReefClaw relay
-
-Usage:
-  tsx src/index.ts [options]
-
-Options:
-  --provider, -p <mock|gateway>  Provider type (default: mock)
-  --token, -t <token>            Connection token (or REEFCLAW_TOKEN env)
-  --user-id, -u <id>             User ID (or REEFCLAW_USER_ID env)
-  --relay-url, -r <url>          Relay URL (default: wss://reefclaw.radunlupsa.partykit.dev)
-  --gateway-url <url>            OpenClaw gateway URL (or OPENCLAW_GATEWAY_URL env)
-  --gateway-token <token>        OpenClaw gateway token (or OPENCLAW_GATEWAY_TOKEN env)
-  --symbol <symbol>              Trading symbol (default: BTC/USDT, or REEFCLAW_SYMBOL env)
-  --log-level, -l <level>        Log level: debug, info, warn, error (default: info)
-  --setup, -s [token]            Run setup flow (validate token, test connection, save to config)
-  --help, -h                     Show this help
-
-Relay config resolution (highest priority first):
-  1. CLI arguments (--token, --user-id, --relay-url)
-  2. Environment variables (REEFCLAW_TOKEN, REEFCLAW_USER_ID, REEFCLAW_RELAY_URL)
-  3. OpenClaw config file (~/.openclaw/openclaw.json → skills.entries.reefclaw)
-  4. Fallback env vars (MOCK_TOKEN, USER_ID)
-  5. Defaults (relay URL → wss://reefclaw.radunlupsa.partykit.dev)
-
-Gateway config resolution (for --provider gateway):
-  1. CLI arguments (--gateway-url, --gateway-token, --symbol)
-  2. Environment variables (OPENCLAW_GATEWAY_URL, OPENCLAW_GATEWAY_TOKEN, REEFCLAW_SYMBOL)
-  3. OpenClaw config file (~/.openclaw/openclaw.json → gateway.auth.token, gateway.port)
-  4. Defaults (http://localhost:18789, BTC/USDT)
+    console.log(`
+ReefClaw Skill — Bridge between OpenClaw and ReefClaw relay
+
+Usage:
+  tsx src/index.ts [options]
+
+Options:
+  --provider, -p <mock|gateway>  Provider type (default: mock)
+  --token, -t <token>            Connection token (or REEFCLAW_TOKEN env)
+  --user-id, -u <id>             User ID (or REEFCLAW_USER_ID env)
+  --relay-url, -r <url>          Relay URL (default: wss://reefclaw.radunlupsa.partykit.dev)
+  --gateway-url <url>            OpenClaw gateway URL (or OPENCLAW_GATEWAY_URL env)
+  --gateway-token <token>        OpenClaw gateway token (or OPENCLAW_GATEWAY_TOKEN env)
+  --symbol <symbol>              Trading symbol (default: BTC/USDT, or REEFCLAW_SYMBOL env)
+  --agent-id <id>                OpenClaw agent this bridge serves (default: main, or OPENCLAW_AGENT_ID env)
+  --log-level, -l <level>        Log level: debug, info, warn, error (default: info)
+  --setup, -s [token]            Run setup flow (validate token, test connection, save to config)
+  --help, -h                     Show this help
+
+Relay config resolution (highest priority first):
+  1. CLI arguments (--token, --user-id, --relay-url)
+  2. Environment variables (REEFCLAW_TOKEN, REEFCLAW_USER_ID, REEFCLAW_RELAY_URL)
+  3. OpenClaw config file (~/.openclaw/openclaw.json → skills.entries.reefclaw)
+  4. Fallback env vars (MOCK_TOKEN, USER_ID)
+  5. Defaults (relay URL → wss://reefclaw.radunlupsa.partykit.dev)
+
+Gateway config resolution (for --provider gateway):
+  1. CLI arguments (--gateway-url, --gateway-token, --symbol, --agent-id)
+  2. Environment variables (OPENCLAW_GATEWAY_URL, OPENCLAW_GATEWAY_TOKEN, REEFCLAW_SYMBOL, OPENCLAW_AGENT_ID)
+  3. OpenClaw config file (~/.openclaw/openclaw.json → gateway.auth.token, gateway.port)
+  4. Defaults (http://localhost:18789, BTC/USDT)
 `);
 }
 // ---- Main ----

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

@@ -45,6 +45,9 @@ export interface ConnectorUpdateOutcome {
  *   - agent runs in a sandbox → in-sandbox terminals are unsupported
  */
 export declare function describeOpenFailure(err: unknown): ConnectorUpdateOutcome;
+/** The operator switched one-click updates off on this box. Refused before
+ *  any gateway call is made; the copy carries the manual path. */
+export declare function describeUpdateDisabled(): 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
@@ -87,3 +90,43 @@ export declare function startConnectorUpdate(rpc: TerminalRpc, opts: StartOption
 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>;
+/** The subset of GatewayWsClient the admin session needs — injected so the
+ *  handshake logic is unit-testable with a fake client. */
+export interface AdminSessionClient {
+    connect(): void;
+    destroy(): void;
+    on(event: 'connected', listener: (hello: {
+        auth?: {
+            scopes?: string[];
+        };
+    } | null | undefined) => void): void;
+    on(event: 'failed', listener: (payload: {
+        reason?: string;
+    } | undefined) => void): void;
+    sendRpc(method: string, params?: Record<string, unknown>): Promise<unknown>;
+}
+export declare function hasAdminScope(scopes: readonly string[] | undefined | null): boolean;
+export declare function describeMissingAdminScope(granted: readonly string[] | undefined | null): ConnectorUpdateOutcome;
+export type AdminSessionResult = {
+    ok: true;
+    scopes: string[];
+} | {
+    ok: false;
+    outcome: ConnectorUpdateOutcome;
+};
+/** Connect a fresh admin-scoped client and wait for hello-ok. Resolves with the
+ *  granted scopes, or a blocked/failed outcome (client already destroyed). */
+export declare function openAdminGatewaySession(client: AdminSessionClient, timeoutMs?: number): Promise<AdminSessionResult>;
+export interface RunOptions {
+    pollMs?: number;
+    maxPolls?: number;
+    /** Injected for tests. */
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Poll the PTY and emit progress until the command finishes or the gateway
+ * restart takes the session down. Returns the final outcome. A single failed
+ * read is not proof the gateway went away (transient RPC error under install
+ * load) — two in a row are required before declaring the restart.
+ */
+export declare function runConnectorUpdate(rpc: TerminalRpc, sessionId: string, emit: (outcome: ConnectorUpdateOutcome) => void, opts?: RunOptions): Promise<ConnectorUpdateOutcome>;