@reefclaw/openclaw-plugin 0.1.26 → 0.1.28

package/.gitignore

@@ -6,3 +6,4 @@
 !scripts/**
 !README.md
 !.gitignore
+!release-notes.json

package/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/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/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/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/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/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/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/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/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';
@@ -1001,6 +1002,13 @@ const paperTradingPlugin = {
                 logger.warn(TAG, `State reload failed: ${formatError(err)}`);
             }
         };
+        // Out-of-tool readers (periodic DB-vs-exchange sweep, stop-watcher) read
+        // the PaperAdapter directly and never went through reloadState — in the
+        // process that did not execute the entry they saw a stale book and posted
+        // false `reconciler_observed_flat` closes seconds after every entry
+        // (2026-09-14). Hook on the simulator so every adapter built from it
+        // (boot + every reconnect path) refreshes before a read.
+        simulator.setStateRefresher(reloadState);
         // Read config: ReefClaw plugin config from ~/.reefclaw/plugin-config.json
         // (OpenClaw's schema validation rejects custom keys in plugin entries)
         let connectionToken = '';
@@ -2931,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({
@@ -2939,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/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/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/ingest/reconcile-db-vs-exchange.d.ts

@@ -13,6 +13,14 @@ export interface DbVsExchangeContext {
      *  venue's snapshot can never contain. Absent → unscoped (legacy). */
     resolveExchange?: () => 'binance' | 'hyperliquid';
 }
+/** Rows opened more recently than this are never orphan-closed. An entry
+ *  that filled seconds ago and is "absent from the exchange" is propagation
+ *  lag, not an orphan: the paper book's debounced state.json save (1s) has
+ *  not landed in the other process yet, or a live fill's REST snapshot raced
+ *  the journal POST. A real orphan is still harvested by the next sweep
+ *  (5 min) — the grace costs nothing and removes the false-close class that
+ *  hit every entry on a paying tenant's box on 2026-09-14. */
+export declare const DEFAULT_MIN_OPEN_AGE_MS = 120000;
 /**
  * Close webapp `positions` rows that are status='open' but absent from the
  * (trusted) exchange snapshot. Returns the number of synthetic closes posted.
@@ -23,6 +31,9 @@ export interface DbVsExchangeContext {
 export interface DbReconcileOptions {
     /** Provenance tag written into closeAssessment.source (default boot sweep). */
     source?: string;
+    /** Young-row grace (ms); rows with `nowMs - openedAt < minOpenAgeMs` are
+     *  skipped with a log line. Default DEFAULT_MIN_OPEN_AGE_MS; 0 disables. */
+    minOpenAgeMs?: number;
     /** Attribution hook (issue #203): given an orphaned symbol, return a short
      *  human-readable description of what the execution engine last knew about
      *  it (e.g. the simulator's last trade). Logged with the synthetic close so
@@ -32,6 +43,8 @@ export interface DbReconcileOptions {
 export declare function reconcileDbOpenVsExchange(ctx: DbVsExchangeContext, exchangeSymbols: Iterable<string>, nowMs?: number, opts?: DbReconcileOptions): Promise<number>;
 export declare const DEFAULT_DB_RECONCILE_INTERVAL_MS = 300000;
 export interface PeriodicDbReconcileDeps extends DbVsExchangeContext {
+    /** Young-row grace forwarded to every sweep (default DEFAULT_MIN_OPEN_AGE_MS). */
+    minOpenAgeMs?: number;
     /** Resolve the ACTIVE adapter each tick (follows runtime reconnects). */
     resolveAdapter: () => {
         getPositionsOrNull(symbol?: string): Promise<Array<{

package/ingest/reconcile-db-vs-exchange.js

@@ -43,6 +43,14 @@ const TAG = 'reconcile-db-vs-exchange';
 function canonical(symbol) {
     return symbol.split(':')[0];
 }
+/** Rows opened more recently than this are never orphan-closed. An entry
+ *  that filled seconds ago and is "absent from the exchange" is propagation
+ *  lag, not an orphan: the paper book's debounced state.json save (1s) has
+ *  not landed in the other process yet, or a live fill's REST snapshot raced
+ *  the journal POST. A real orphan is still harvested by the next sweep
+ *  (5 min) — the grace costs nothing and removes the false-close class that
+ *  hit every entry on a paying tenant's box on 2026-09-14. */
+export const DEFAULT_MIN_OPEN_AGE_MS = 120_000;
 export async function reconcileDbOpenVsExchange(ctx, exchangeSymbols, nowMs = Date.now(), opts = {}) {
     if (!ctx.decisionsClient || !ctx.userId)
         return 0;
@@ -58,7 +66,16 @@ export async function reconcileDbOpenVsExchange(ctx, exchangeSymbols, nowMs = Da
     const exchangeSet = new Set();
     for (const s of exchangeSymbols)
         exchangeSet.add(canonical(s));
-    const orphans = resp.positions.filter((p) => !exchangeSet.has(canonical(p.symbol)));
+    const minOpenAgeMs = opts.minOpenAgeMs ?? DEFAULT_MIN_OPEN_AGE_MS;
+    const absent = resp.positions.filter((p) => !exchangeSet.has(canonical(p.symbol)));
+    const orphans = absent.filter((p) => {
+        const ageMs = nowMs - p.openedAt;
+        if (Number.isFinite(ageMs) && ageMs < minOpenAgeMs) {
+            logger.info(TAG, `${p.symbol}: opened ${Math.round(ageMs / 1000)}s ago and absent from the snapshot — within the ${Math.round(minOpenAgeMs / 1000)}s grace, not treated as an orphan (propagation lag; next sweep re-checks)`);
+            return false;
+        }
+        return true;
+    });
     if (orphans.length === 0) {
         logger.info(TAG, `DB reconcile: all ${resp.positions.length} open row(s) present on exchange`);
         return 0;
@@ -149,7 +166,11 @@ export function startPeriodicDbReconcile(deps, intervalMs = resolveDbReconcileIn
                 logger.warn(TAG, 'periodic sweep skipped — positions fetch untrusted (null)');
                 return 0;
             }
-            return await reconcileDbOpenVsExchange(deps, positions.map((p) => p.symbol), Date.now(), { source: 'db_exchange_sweep_periodic', describeLastExit: deps.describeLastExit });
+            return await reconcileDbOpenVsExchange(deps, positions.map((p) => p.symbol), Date.now(), {
+                source: 'db_exchange_sweep_periodic',
+                describeLastExit: deps.describeLastExit,
+                minOpenAgeMs: deps.minOpenAgeMs,
+            });
         }
         catch (err) {
             logger.warn(TAG, `periodic sweep failed: ${err instanceof Error ? err.message : String(err)}`);

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "reefclaw-paper-trading",
   "name": "ReefClaw Trading",
-  "version": "0.1.26",
+  "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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reefclaw/openclaw-plugin",
-  "version": "0.1.26",
+  "version": "0.1.28",
   "description": "ReefClaw supervised trading plugin for OpenClaw. Runs entirely on YOUR machine and starts in PAPER mode — it cannot trade real funds until you supply exchange credentials and walk the PAPER→MICRO_LIVE→LIVE ladder yourself from the ReefClaw dashboard (the agent cannot make that change; it is refused without operator provenance). Your exchange API keys stay on your machine to sign requests to the exchange and are NEVER sent to ReefClaw — a test in the package asserts this. What does reach ReefClaw is trading telemetry for the dashboard (positions, fills, decision journal). Live trading always carries exchange-native protective stops. Trading instructions can be updated remotely, and every update must carry a valid Ed25519 signature verified against a key pinned in this build before it is applied. Install: npx --yes @reefclaw/connect, or from ClawHub on OpenClaw 2026.8.1+ (Control UI Plugins > Discover, or /plugins install clawhub:@reefclaw/openclaw-plugin then the same with --accept-capabilities after reviewing the listed capabilities)",
   "type": "module",
   "main": "index.js",

package/paper-adapter.js

@@ -25,17 +25,25 @@ export class PaperAdapter {
     async closePosition(symbol, closeReason) {
         return this.simulator.closePosition(symbol, closeReason);
     }
+    // Reads pull a newer state.json first (ExchangeSimulator.refreshState —
+    // no-op without a hook). Out-of-tool readers (DB-vs-exchange sweep,
+    // stop-watcher) otherwise see a stale book in the process that did not
+    // execute the entry and post false synthetic closes / phantom stop fills.
     async getBalance() {
+        this.simulator.refreshState();
         return this.simulator.getBalance();
     }
     async getPositions(symbol) {
+        this.simulator.refreshState();
         return this.simulator.getPositions(symbol);
     }
     /** Paper has no exchange fetch to fail — position state is always known. */
     async getPositionsOrNull(symbol) {
+        this.simulator.refreshState();
         return this.simulator.getPositions(symbol);
     }
     async getOpenOrders(symbol) {
+        this.simulator.refreshState();
         return this.simulator.getOpenOrders(symbol);
     }
     async fetchOrder(orderId, _symbol) {

package/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/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/release-notes.json

@@ -0,0 +1,5 @@
+{
+  "_comment": "One line per released plugin version, shown in the dashboard's update banner. Baked into the webapp at build by webapp/scripts/generate-skill-content.mjs (LATEST_PLUGIN_NOTES = the entry for plugin-package/package.json#version). Add a line in the same PR that bumps the version.",
+  "0.1.27": "Fixes paper positions showing as closed at $0 in the Journal while still open, and adds a 2-minute grace to the position reconciler.",
+  "0.1.28": "Fixes the connector's gateway handshake on OpenClaw 2026.9+ (it now connects as OpenClaw's local-backend client) and adds in-app update notices with one-click updates."
+}

package/simulator/exchange-simulator.d.ts

@@ -63,6 +63,13 @@ export declare class ExchangeSimulator extends EventEmitter {
      *  on open and is released on close, so we must add it back here. */
     computeEquity(): number;
     private getQuoteCurrency;
+    private stateRefresher;
+    /** Install the "reload state.json if it changed" hook (index.ts reloadState). */
+    setStateRefresher(fn: (() => void) | null): void;
+    /** Pull a newer on-disk snapshot before an out-of-tool read. No-op when no
+     *  hook is installed (tests / single-process). Never throws — a failed
+     *  reload leaves the current in-memory book in place. */
+    refreshState(): void;
     getBalance(): CcxtBalance;
     getPositions(symbol?: string): CcxtPosition[];
     getOpenOrders(symbol?: string): CcxtOrder[];

package/simulator/exchange-simulator.js

@@ -153,6 +153,36 @@ export class ExchangeSimulator extends EventEmitter {
     getQuoteCurrency() {
         return this.state.config?.quoteCurrency ?? 'USDT';
     }
+    // ---- Cross-process refresh (two-process architecture) ----
+    //
+    // The agent and gateway processes each hold their own ExchangeSimulator and
+    // share state through state.json. Every paper TOOL path calls index.ts
+    // reloadState() before reading, but out-of-tool readers (the periodic
+    // DB-vs-exchange sweep, the stop-watcher's 3s poll) read the adapter
+    // directly — and a process that did NOT execute the entry then sees a
+    // stale in-memory book. On 2026-09-14 that posted a synthetic
+    // `reconciler_observed_flat` close 5–100s after EVERY entry on a paying
+    // tenant's box while the engine kept the position alive for hours. The
+    // hook lives on the simulator (not the adapter) so every PaperAdapter ever
+    // built from it — boot or any reconnect path — inherits it.
+    stateRefresher = null;
+    /** Install the "reload state.json if it changed" hook (index.ts reloadState). */
+    setStateRefresher(fn) {
+        this.stateRefresher = fn;
+    }
+    /** Pull a newer on-disk snapshot before an out-of-tool read. No-op when no
+     *  hook is installed (tests / single-process). Never throws — a failed
+     *  reload leaves the current in-memory book in place. */
+    refreshState() {
+        if (!this.stateRefresher)
+            return;
+        try {
+            this.stateRefresher();
+        }
+        catch (err) {
+            logger.warn(TAG, `state refresh failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
     // ---- Read operations (for tools) ----
     getBalance() {
         const free = {};