@reefclaw/connect 0.1.39 → 0.1.40

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/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;
@@ -80,8 +84,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 +117,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;
@@ -321,7 +384,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 +420,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 +437,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/providers/connector-update.d.ts

@@ -87,3 +87,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>;

package/assets/bridge/providers/connector-update.js

@@ -85,6 +85,20 @@ export function describeOpenFailure(err) {
                 + 'Update from a shell on the box instead: npx -y @reefclaw/connect@latest',
         };
     }
+    // Scope refusal: terminal.* requires operator.admin on OpenClaw >= 2026.7
+    // (verified in the 2026.9.4 method-scopes table). The steady-state bridge
+    // session runs on operator.read/write, so a bridge that predates the
+    // admin-session update (2026-09-14) is refused right here. Nothing changed
+    // on the box; the fix is one manual update, after which this is one click.
+    if (/operator\.admin|scope|forbidden|unauthori[sz]ed|not allowed|\b403\b/.test(lower)) {
+        return {
+            ok: false,
+            status: 'blocked',
+            message: 'The gateway refused to open a terminal for the connector (it needs the operator.admin scope). '
+                + 'One-click updates need a connector released 2026-09-14 or later — update once by pasting the manual '
+                + 'command to your agent or from a shell: npx -y @reefclaw/connect@latest. After that, updates are one click.',
+        };
+    }
     return {
         ok: false,
         status: 'failed',
@@ -210,3 +224,112 @@ export async function readTerminalText(rpc, sessionId) {
 export async function closeTerminal(rpc, sessionId) {
     await rpc('terminal.close', { sessionId }).catch(() => undefined);
 }
+export function hasAdminScope(scopes) {
+    return Array.isArray(scopes) && scopes.includes('operator.admin');
+}
+export function describeMissingAdminScope(granted) {
+    const list = granted && granted.length > 0 ? granted.join(', ') : 'none';
+    return {
+        ok: false,
+        status: 'blocked',
+        message: `This gateway did not grant the connector the operator.admin scope it needs to open a terminal (granted: ${list}). `
+            + 'One-click updates are unavailable on this box — update from a shell instead: npx -y @reefclaw/connect@latest',
+    };
+}
+/** 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 async function openAdminGatewaySession(client, timeoutMs = 20_000) {
+    const result = await new Promise((resolve) => {
+        const timer = setTimeout(() => resolve(new Error('timed out waiting for the gateway handshake')), timeoutMs);
+        client.on('connected', (hello) => {
+            clearTimeout(timer);
+            resolve(hello?.auth?.scopes ?? []);
+        });
+        client.on('failed', (payload) => {
+            clearTimeout(timer);
+            resolve(new Error(payload?.reason ?? 'gateway connection failed'));
+        });
+        client.connect();
+    });
+    if (result instanceof Error) {
+        client.destroy();
+        logger.warn(TAG, `admin session failed: ${result.message}`);
+        return {
+            ok: false,
+            outcome: { ok: false, status: 'failed', message: `Could not open an admin session on the gateway: ${result.message}` },
+        };
+    }
+    if (!hasAdminScope(result)) {
+        client.destroy();
+        logger.warn(TAG, `admin session granted [${result.join(', ')}] — operator.admin missing, update refused`);
+        return { ok: false, outcome: describeMissingAdminScope(result) };
+    }
+    logger.info(TAG, `admin session open (scopes: ${result.join(', ')})`);
+    return { ok: true, scopes: result };
+}
+/**
+ * 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 async function runConnectorUpdate(rpc, sessionId, emit, opts = {}) {
+    const pollMs = opts.pollMs ?? 1500;
+    // Generous: an npm install on a small VPS is slow (240 × 1.5 s = 6 min).
+    const maxPolls = opts.maxPolls ?? 240;
+    const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    let lastEmitted = '';
+    let consecutiveDeadReads = 0;
+    for (let i = 0; i < maxPolls; i++) {
+        await sleep(pollMs);
+        const screen = await readTerminalText(rpc, sessionId);
+        if (screen !== null)
+            consecutiveDeadReads = 0;
+        else if (++consecutiveDeadReads < 2)
+            continue;
+        if (screen === null) {
+            // Session (or the whole gateway) is gone. After a successful start this
+            // is the restart landing, not a failure.
+            const outcome = {
+                ok: true,
+                status: classifyTransportLoss(true),
+                sessionId,
+                output: lastEmitted,
+                message: 'The agent is restarting to load the new version. The dashboard reconnects on its own.',
+            };
+            emit(outcome);
+            return outcome;
+        }
+        if (screen !== lastEmitted) {
+            lastEmitted = screen;
+            emit({ ok: true, status: 'started', sessionId, output: screen, message: 'Updating…' });
+        }
+        if (isCredibleCompletion(screen)) {
+            const { exitCode } = parseDoneSentinel(screen);
+            const ok = exitCode === 0;
+            const outcome = {
+                ok,
+                status: 'completed',
+                sessionId,
+                exitCode,
+                output: screen,
+                message: ok
+                    ? 'Connector updated. The agent restarts to load it.'
+                    : `The updater exited with code ${exitCode}. The connector was left as it was.`,
+            };
+            emit(outcome);
+            await closeTerminal(rpc, sessionId);
+            return outcome;
+        }
+    }
+    const outcome = {
+        ok: false,
+        status: 'failed',
+        sessionId,
+        output: lastEmitted,
+        message: 'The update did not finish in time. Check the box directly before retrying.',
+    };
+    emit(outcome);
+    await closeTerminal(rpc, sessionId);
+    return outcome;
+}

package/assets/bridge/providers/gateway.d.ts

@@ -265,11 +265,6 @@ export declare class GatewayProvider implements OpenClawProvider {
     updateConnector(args: {
         acknowledgeOpenPositions?: boolean;
     }): Promise<ConnectorUpdateOutcome>;
-    /**
-     * Poll the PTY and emit progress until the command finishes or the gateway
-     * restart takes the session (and us) down.
-     */
-    private streamConnectorUpdate;
     private emitConnectorUpdate;
     /** Operator-only. Approval/balance status of the provisioned HL wallet. */
     getHlAgentWalletStatus(): Promise<HlAgentWalletStatusOutcome>;
@@ -306,6 +301,11 @@ export declare class GatewayProvider implements OpenClawProvider {
      *  2026-07-29), we read the scopes the gateway ACTUALLY granted and relax
      *  only when it demonstrably withheld the one we need. On the supported
      *  range the scope survives and nothing is written. */
+    private deviceIdentityRelaxationApplied;
+    /** Handshake rejected outright for missing device identity (see
+     *  isDeviceIdentityRejection). Same escalation as the withheld-write-scope
+     *  case, keyed on the rejection instead of on hello-ok scopes. */
+    private onHandshakeRejectedForDeviceIdentity;
     private checkGrantedScopes;
     private onWsConnected;
     private onAgentEvent;

package/assets/bridge/providers/gateway.js

@@ -7,7 +7,7 @@ import { homedir } from 'os';
 import { logger, formatError } from '../logger.js';
 import { isTradingMode } from '../types.js';
 import { deriveModelHealth } from '../model-health.js';
-import { handshakeLacksWriteScope, relaxGatewayDeviceAuth } from '../config.js';
+import { handshakeLacksWriteScope, isDeviceIdentityRejection, relaxGatewayDeviceAuth } from '../config.js';
 import { toIntelSymbol } from '@reefclaw/shared';
 import { GatewayHttpClient } from '../gateway/gateway-http-client.js';
 import { GatewayWsClient } from '../gateway/gateway-ws-client.js';
@@ -19,7 +19,7 @@ import { parseIdentityName } from '../utils/identity-name.js';
 import { computeEquity as _computeEquity, computePositionNotional as _computePositionNotional, computeRiskMetrics as _computeRiskMetrics, DEFAULT_RISK_LIMITS, DRAWDOWN_ZONE_THRESHOLDS, TENANT_LIMIT_BOUNDS, boundedNum, validateDrawdownLadder, } from './risk-calculator.js';
 import { executeKill as _executeKill, executeFlatten as _executeFlatten, executePause as _executePause, executeResume as _executeResume, cancelPendingProposals, withProposalDetail, } from './emergency-commands.js';
 import { executeSetTradingMode, executeGetBracketConfig, executeSetBracketRequirement, executeSetExchangeCredentials, executeTestExchangeCredentials, executeClearExchangeCredentials, executeProvisionHlAgentWallet, executeHlAgentWalletStatus, executeSubmitHlAgentApproval, } from './onboarding-commands.js';
-import { startConnectorUpdate, readTerminalText, closeTerminal, classifyTransportLoss, isCredibleCompletion, parseDoneSentinel, } from './connector-update.js';
+import { startConnectorUpdate, runConnectorUpdate, openAdminGatewaySession, checkPositionGuard, } from './connector-update.js';
 const TAG = 'gateway';
 // ---- Day-start NAV persistence ----
 // Persists sessionStartNav (the UTC-day P&L anchor) per date so Day P&L
@@ -749,87 +749,44 @@ export class GatewayProvider {
      * `restarting` and the dashboard waits for the reconnect.
      */
     async updateConnector(args) {
-        const ws = this.wsClient;
-        if (!ws) {
+        if (!this.wsClient) {
             return { ok: false, status: 'failed', message: 'Not connected to the OpenClaw gateway.' };
         }
-        const rpc = (method, params) => ws.sendRpc(method, params);
         const openPositionCount = this.positions.filter((p) => Math.abs(Number(p.contracts) || 0) > 0).length;
-        const started = await startConnectorUpdate(rpc, {
-            acknowledgeOpenPositions: args.acknowledgeOpenPositions,
-            openPositionCount,
-        });
-        if (started.status !== 'started' || !started.sessionId)
+        const guardArgs = { acknowledgeOpenPositions: args.acknowledgeOpenPositions, openPositionCount };
+        // Position guard FIRST — never open an admin session for a request that is
+        // going to be refused anyway.
+        const blocked = checkPositionGuard(guardArgs);
+        if (blocked)
+            return blocked;
+        // terminal.* is operator.admin-only (OpenClaw method-scopes, since 2026.7).
+        // The long-lived session runs on operator.read/write by design, so open a
+        // SEPARATE short-lived admin session for this update. Reconnects are
+        // effectively disabled: the gateway restart is supposed to kill it.
+        const admin = new GatewayWsClient({
+            gatewayUrl: this.config.gatewayUrl,
+            gatewayToken: this.config.gatewayToken,
+            requestAdminScope: true,
+            // The identity the long-lived session was admitted under; no ladder here.
+            identities: [this.wsClient.getClientId()],
+            requireScope: 'operator.admin',
+        }, { baseDelayMs: 60_000, maxDelayMs: 60_000, maxFastAttempts: 0, jitterFactor: 0, slowRetryMs: 3_600_000 });
+        const session = await openAdminGatewaySession(admin);
+        if (!session.ok)
+            return session.outcome;
+        const rpc = (method, params) => admin.sendRpc(method, params);
+        const started = await startConnectorUpdate(rpc, guardArgs);
+        if (started.status !== 'started' || !started.sessionId) {
+            admin.destroy();
             return started;
+        }
         // Stream progress in the background; the RPC returns as soon as the command
         // is running so the browser is never left waiting on a minutes-long call.
-        void this.streamConnectorUpdate(rpc, started.sessionId);
-        return started;
-    }
-    /**
-     * Poll the PTY and emit progress until the command finishes or the gateway
-     * restart takes the session (and us) down.
-     */
-    async streamConnectorUpdate(rpc, sessionId) {
-        const POLL_MS = 1500;
-        // Generous: an npm install on a small VPS is slow. The gateway restart
-        // normally ends this loop long before the cap.
-        const MAX_POLLS = 240;
-        let lastEmitted = '';
-        // A single failed read is not proof the gateway went away — it could be a
-        // transient RPC error under install load. Require two in a row before
-        // declaring the restart, so we do not flip the dashboard into "restarting"
-        // while the update is in fact still running.
-        let consecutiveDeadReads = 0;
-        for (let i = 0; i < MAX_POLLS; i++) {
-            await new Promise((r) => setTimeout(r, POLL_MS));
-            const screen = await readTerminalText(rpc, sessionId);
-            if (screen !== null)
-                consecutiveDeadReads = 0;
-            else if (++consecutiveDeadReads < 2)
-                continue;
-            if (screen === null) {
-                // Session (or the whole gateway) is gone. After a successful start this
-                // is the restart landing, not a failure.
-                const status = classifyTransportLoss(true);
-                this.emitConnectorUpdate({
-                    ok: true,
-                    status,
-                    sessionId,
-                    output: lastEmitted,
-                    message: 'The agent is restarting to load the new version. The dashboard reconnects on its own.',
-                });
-                return;
-            }
-            if (screen !== lastEmitted) {
-                lastEmitted = screen;
-                this.emitConnectorUpdate({ ok: true, status: 'started', sessionId, output: screen, message: 'Updating…' });
-            }
-            if (isCredibleCompletion(screen)) {
-                const { exitCode } = parseDoneSentinel(screen);
-                const ok = exitCode === 0;
-                this.emitConnectorUpdate({
-                    ok,
-                    status: 'completed',
-                    sessionId,
-                    exitCode,
-                    output: screen,
-                    message: ok
-                        ? 'Connector updated. The agent restarts to load it.'
-                        : `The updater exited with code ${exitCode}. The connector was left as it was.`,
-                });
-                await closeTerminal(rpc, sessionId);
-                return;
-            }
-        }
-        this.emitConnectorUpdate({
-            ok: false,
-            status: 'failed',
-            sessionId,
-            output: lastEmitted,
-            message: 'The update did not finish in time. Check the box directly before retrying.',
+        // The admin session is torn down when the loop ends, whichever way.
+        void runConnectorUpdate(rpc, started.sessionId, (outcome) => this.emitConnectorUpdate(outcome)).finally(() => {
+            admin.destroy();
         });
-        await closeTerminal(rpc, sessionId);
+        return started;
     }
     emitConnectorUpdate(payload) {
         this.fire('connectorUpdate', payload);
@@ -1283,6 +1240,12 @@ export class GatewayProvider {
         this.wsClient.on('disconnected', ({ code, reason }) => {
             logger.warn(TAG, `WS disconnected: ${code} ${reason}`);
             this.poller?.pause();
+            // OpenClaw >= 2026.9: an unrelaxed gateway rejects a control-UI client
+            // without device identity AT THE HANDSHAKE, so checkGrantedScopes (which
+            // needs a completed handshake) never runs and the bridge would reconnect
+            // forever with no diagnosis. The rejection itself is the proven need.
+            if (isDeviceIdentityRejection(code, reason))
+                this.onHandshakeRejectedForDeviceIdentity(reason);
         });
         this.wsClient.on('reconnecting', ({ attempt, delayMs }) => {
             logger.info(TAG, `WS reconnecting: attempt ${attempt}, delay ${Math.round(delayMs)}ms`);
@@ -1303,6 +1266,31 @@ export class GatewayProvider {
      *  2026-07-29), we read the scopes the gateway ACTUALLY granted and relax
      *  only when it demonstrably withheld the one we need. On the supported
      *  range the scope survives and nothing is written. */
+    deviceIdentityRelaxationApplied = false;
+    /** Handshake rejected outright for missing device identity (see
+     *  isDeviceIdentityRejection). Same escalation as the withheld-write-scope
+     *  case, keyed on the rejection instead of on hello-ok scopes. */
+    onHandshakeRejectedForDeviceIdentity(reason) {
+        if (this.deviceIdentityRelaxationApplied)
+            return;
+        this.deviceIdentityRelaxationApplied = true;
+        const tried = this.wsClient?.getClientId() ?? 'unknown';
+        logger.error(TAG, `Gateway REJECTED the connector handshake under every client identity (last: ${tried}): ${reason}. ` +
+            `OpenClaw >= 2026.9 admits only a local-backend client (gateway-client) or a device-paired one — ` +
+            `the retired gateway.controlUi relaxation no longer applies — and this gateway did neither. The ` +
+            `dashboard cannot reach this agent (no tools, no state, no updates) until the handshake completes.`);
+        // Last resort for OLDER builds only: on 2026.9+ the flags are retired and
+        // ignored (a config migration deletes them), so this is best-effort and
+        // says so.
+        const changed = relaxGatewayDeviceAuth(`the gateway rejected the connector handshake (${reason})`);
+        if (changed) {
+            logger.warn(TAG, 'Wrote the legacy gateway.controlUi relaxation flags in case this is an older OpenClaw build — ' +
+                'RESTART the gateway to find out. On OpenClaw >= 2026.9 they are ignored: check the gateway ' +
+                'auth config / device pairing instead.');
+        }
+        this.agentMode = 'ERROR';
+        this.emitAgentState();
+    }
     checkGrantedScopes(helloOk) {
         const scopes = helloOk.auth?.scopes;
         if (!handshakeLacksWriteScope(scopes))

package/assets/plugin/index.js

@@ -38,6 +38,7 @@ import { reconcileDbOpenVsExchange, startPeriodicDbReconcile } from './ingest/re
 import { onStopWatcherClose } from './ingest/position-auto-capture.js';
 import { ReentryTracker } from './portfolio/reentry-tracker.js';
 import { startReadinessReporter } from './ingest/readiness-reporter.js';
+import { resolvePluginInstallFacts } from './plugin-version.js';
 import { IntelMicrostructureAssembler } from './live/microstructure-assembler.js';
 import { recordPositionReviewsTool } from './tools/record-position-reviews.js';
 import { getMyRecentReviewsTool } from './tools/get-my-recent-reviews.js';
@@ -2938,6 +2939,15 @@ const paperTradingPlugin = {
         catch (err) {
             logger.warn(TAG, `credential transport key setup failed (plaintext fallback stays available): ${formatError(err)}`);
         }
+        // Release version + install channel for the dashboard's update banner —
+        // read from the manifest shipped next to index.js (stamped by both release
+        // channels); the repo's unstamped manifest marks a source/dist deploy, which
+        // the dashboard never nags (plugin/src/plugin-version.ts).
+        const installFacts = resolvePluginInstallFacts({
+            pluginRoot: dirname(fileURLToPath(import.meta.url)),
+            connectorSupervisor: readPluginConfig().connectorSupervisor,
+        });
+        logger.info(TAG, `Plugin release ${installFacts.version ?? 'unknown (no stamped manifest)'} via ${installFacts.channel}`);
         // Runs here once (guarded by the pluginInitialised early-return → once per
         // process) + on an unref'd interval inside the reporter.
         startReadinessReporter({
@@ -2946,6 +2956,8 @@ const paperTradingPlugin = {
             venue,
             publicApi: hlPublicApi ?? binanceApi,
             toolCount: toolNames.length,
+            pluginVersion: installFacts.version,
+            installChannel: installFacts.channel,
             // live_stop_protection (E2E audit #3): what would stop a losing live
             // position. Deferred closure over the runtime so paper↔live flips and
             // adapter swaps surface on the next 5-min report without a restart.

package/assets/plugin/ingest/readiness-reporter.d.ts

@@ -1,4 +1,5 @@
 import { type ReadinessCheck, type ReadinessReport, type VenueId, type VenueReachabilityResult } from '@reefclaw/shared';
+import type { InstallChannel } from '../plugin-version.js';
 /** Who froze the loop. 'unknown' when the kernel counter is unreadable (not
  *  Linux / no CONFIG_SCHEDSTATS / first cycle) — attribution is evidence, and
  *  absent evidence stays absent rather than defaulting to a blame. */
@@ -48,6 +49,12 @@ export interface ReadinessReporterOptions {
     publicApi: VenueReachabilityProbe;
     /** Number of trading tools registered (a health signal). */
     toolCount: number;
+    /** Release version from the shipped manifest (e.g. '0.1.27'); omitted from
+     *  the report when unknown — never fabricated. */
+    pluginVersion?: string;
+    /** How this plugin was installed — decides which update path the dashboard
+     *  offers ('npx' one-click, 'clawhub' steps, 'source' silent). */
+    installChannel?: InstallChannel;
     /** Resolve the stop-protection snapshot at CALL time (deferred closure over
      *  the runtime — follows paper↔live flips and adapter swaps). Absent/null →
      *  the `live_stop_protection` row is omitted, never fabricated. */
@@ -67,7 +74,7 @@ export interface ReadinessReporterOptions {
  *  warn/fail drift is reported 'unknown' (not amber/red) so the readiness
  *  banner doesn't cry-wolf for ~5 min after every restart; a genuinely
  *  skewed clock still surfaces on cycle 2. */
-export declare function collectReadiness(opts: Pick<ReadinessReporterOptions, 'venue' | 'publicApi' | 'toolCount' | 'resolveStopProtection'>, bootWarmup?: boolean, deps?: {
+export declare function collectReadiness(opts: Pick<ReadinessReporterOptions, 'venue' | 'publicApi' | 'toolCount' | 'resolveStopProtection' | 'pluginVersion' | 'installChannel'>, bootWarmup?: boolean, deps?: {
     /** Debounce memory. Omitted → a fresh state, so a lone unreachable reads
      *  `unknown`; only a caller that persists state across cycles can ever
      *  reach the warn rung. */

package/assets/plugin/ingest/readiness-reporter.js

@@ -14,8 +14,11 @@ import { startEventLoopMonitor, sampleEventLoopDelayMs, sampleRunqueueWaitMs, }
 const TAG = 'readiness';
 const DEFAULT_INTERVAL_MS = 300_000; // 5 min — geo/clock state changes rarely.
 const MIN_INTERVAL_MS = 60_000;
-/** Best-effort display fact; kept in sync with the register() banner in index.ts. */
-const PLUGIN_VERSION = '3.8.0';
+// The plugin's RELEASE version + install channel arrive via options (index.ts
+// resolves them from the shipped manifest — plugin/src/plugin-version.ts).
+// They used to be a hardcoded internal constant ('3.8.0') in a different
+// namespace from the release versions, which left the dashboard's update
+// banner permanently inert.
 /** Consecutive non-pass reachability probes required before the banner goes
  *  amber. One 5-min sample is not enough evidence to send an operator hunting a
  *  network fault — the intel-health AMBER rung already debounces the same way
@@ -288,7 +291,8 @@ export async function collectReadiness(opts, bootWarmup = false, deps = {}) {
         overall: deriveOverallReadiness(checks),
         checks,
         agent: {
-            pluginVersion: PLUGIN_VERSION,
+            ...(opts.pluginVersion ? { pluginVersion: opts.pluginVersion } : {}),
+            ...(opts.installChannel ? { installChannel: opts.installChannel } : {}),
             toolCount: opts.toolCount,
             venue: opts.venue,
             ...(credentialPublicKey ? { credentialPublicKey } : {}),

package/assets/plugin/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "reefclaw-paper-trading",
   "name": "ReefClaw Trading",
-  "version": "0.1.27",
+  "version": "0.1.28",
   "description": "Supervised trading plugin for the ReefClaw dashboard. It runs on YOUR machine and starts in PAPER mode with no API keys. It cannot trade real funds until you supply exchange credentials and step PAPER→MICRO_LIVE→LIVE yourself from the dashboard — the agent cannot make that change (the tool is refused without operator provenance). Exchange keys stay local, are used only to sign requests to the exchange, and are never transmitted to ReefClaw (asserted by a test in this package). Trading telemetry — positions, fills, decision journal — is sent to ReefClaw to render the dashboard. Every live position carries exchange-native protective stops. Remote updates to the agent's trading instructions are applied only after an Ed25519 signature is verified against a public key pinned in this build.",
   "author": "ReefClaw",
   "activation": {

package/assets/plugin/plugin-version.d.ts

@@ -0,0 +1,21 @@
+export type InstallChannel = 'npx' | 'clawhub' | 'source';
+export interface PluginInstallFacts {
+    /** Release version from the shipped manifest (e.g. '0.1.27'); undefined
+     *  when no usable manifest sits next to index.js — never fabricated. */
+    version?: string;
+    channel: InstallChannel;
+}
+/** The repo manifest's placeholder version. A box reporting it was not
+ *  installed from a release package (no release will ever be 0.1.0 — the
+ *  release line passed it long ago). */
+export declare const UNSTAMPED_VERSION = "0.1.0";
+export interface ResolveInstallFactsInput {
+    /** Directory holding the plugin's index.js (+ openclaw.plugin.json). */
+    pluginRoot: string;
+    /** plugin-config.json `connectorSupervisor` — the npx installer writes 'on'
+     *  on every install; nothing else does. */
+    connectorSupervisor?: 'on' | 'off';
+    /** ~/.reefclaw (injectable for tests). */
+    reefclawHome?: string;
+}
+export declare function resolvePluginInstallFacts(input: ResolveInstallFactsInput): PluginInstallFacts;

package/assets/plugin/plugin-version.js

@@ -0,0 +1,58 @@
+// Which ReefClaw plugin RELEASE is running, and how it was installed — the two
+// facts the dashboard needs to (a) tell the trader an update exists and (b)
+// offer the right update path (one click for npx installs, ClawHub steps for
+// ClawHub installs, silence for the operator's own source/dist deploys).
+//
+// Version source: the `openclaw.plugin.json` that ships NEXT TO index.js in
+// every installed layout. Both release channels stamp it with the package
+// release version — installer/scripts/bundle-assets.mjs for `npx
+// @reefclaw/connect`, plugin-package/scripts/assemble.mjs for ClawHub. The
+// repo's own manifest carries the unstamped 0.1.0, which is what tells a
+// source-tree / script-deployed box apart from a packaged install.
+//
+// History: the readiness report used to send a hardcoded internal constant
+// ('3.8.0') that lived in a different namespace from the release versions
+// ('0.1.x'), so the dashboard's update banner compared apples to oranges and
+// never fired (memory feedback_plugin_update_banner_inert_version_namespace).
+// The webapp still recognises that legacy value and nudges those boxes once.
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
+import { homedir } from 'node:os';
+/** The repo manifest's placeholder version. A box reporting it was not
+ *  installed from a release package (no release will ever be 0.1.0 — the
+ *  release line passed it long ago). */
+export const UNSTAMPED_VERSION = '0.1.0';
+const RELEASE_VERSION_RE = /^\d+\.\d+\.\d+$/;
+export function resolvePluginInstallFacts(input) {
+    let version;
+    try {
+        const raw = readFileSync(join(input.pluginRoot, 'openclaw.plugin.json'), 'utf-8');
+        const v = JSON.parse(raw).version;
+        if (typeof v === 'string' && RELEASE_VERSION_RE.test(v.trim()))
+            version = v.trim();
+    }
+    catch {
+        // No (readable) manifest next to index.js — legacy deploy layout. Report
+        // nothing rather than a guess; the dashboard fails open (no banner).
+    }
+    return { version, channel: detectChannel(input, version) };
+}
+function detectChannel(input, version) {
+    // Unstamped or absent manifest → the repo's own: source tree or a dist deploy
+    // (the operator's rigs, updated by deploy scripts — never by the installer).
+    if (version === undefined || version === UNSTAMPED_VERSION)
+        return 'source';
+    // ClawHub packages carry the bootstrap skill at the package root
+    // (plugin-package/scripts/assemble.mjs); the npx layout deliberately does
+    // not. Checked FIRST: a box that once ran the npx installer and later
+    // installed from ClawHub loads the ClawHub copy.
+    if (existsSync(join(input.pluginRoot, 'skills')))
+        return 'clawhub';
+    const home = resolve(input.reefclawHome ?? join(homedir(), '.reefclaw'));
+    const root = resolve(input.pluginRoot);
+    if (input.connectorSupervisor === 'on' || root.startsWith(home + sep))
+        return 'npx';
+    // Stamped release package without an installer marker (placed by hand).
+    // The installer still updates it in place, so it gets the one-click path.
+    return 'npx';
+}

package/assets/shared/readiness.d.ts

@@ -48,7 +48,12 @@ export interface ReadinessReport {
     checks: ReadinessCheck[];
     /** Best-effort agent facts for display. */
     agent?: {
+        /** Release version from the shipped manifest ('0.1.27'). Legacy plugins
+         *  sent an internal '3.x' constant — the webapp treats that as "behind". */
         pluginVersion?: string;
+        /** 'npx' | 'clawhub' | 'source' — how the plugin was installed. Kept
+         *  `string` so an older webapp renders reports from a newer plugin. */
+        installChannel?: string;
         toolCount?: number;
         /** Trading venue this agent executes on ('binance' | 'hyperliquid').
          *  Kept `string` so an older webapp renders reports from a newer plugin.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reefclaw/connect",
-  "version": "0.1.39",
+  "version": "0.1.40",
   "description": "One-command installer that connects your OpenClaw agent to ReefClaw (paper trading, no exchange keys).",
   "type": "module",
   "bin": {