@reefclaw/connect 0.1.39 → 0.1.41

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

@@ -33,6 +33,22 @@
 //     `classifyTransportLoss`.
 //   - The PTY runs as the gateway's own user (`openclaw`), which is exactly the
 //     user the installer must run as. Correct by construction.
+//
+// Hardening after the 2026-09-16 self-hoster audit (a relay message that ends
+// in a PTY on the operator's machine is a capability worth fencing even with
+// a constant command):
+//   - Per-host opt-out: REEFCLAW_ALLOW_CONNECTOR_UPDATE=0 (or plugin-config.json
+//     `"connectorUpdate": "off"`) makes the provider refuse before any gateway
+//     call (`describeUpdateDisabled`). The gateway's own switch
+//     `gateway.terminal.enabled=false` is honoured too (`describeOpenFailure`).
+//   - terminal.* needs operator.admin: the update opens a separate short-lived
+//     admin session and checks the granted scopes before `terminal.open`.
+//   - Residual trust: `@latest` resolves on the npm registry, so the trust root
+//     is the registry plus the publisher account (2FA), exactly as for a manual
+//     `npx`. Pinning an exact, offline-signed version is the planned follow-up
+//     (the SKILL.md OTA already carries the Ed25519 key for it).
+//   - The updater overwrites local modifications to the placed bridge/plugin,
+//     as any reinstall would. Self-hosters carrying patches: switch it off.
 import { logger } from '../logger.js';
 const TAG = 'connector-update';
 /**
@@ -85,12 +101,36 @@ 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',
         message: `Could not open a terminal on the box: ${raw}`,
     };
 }
+/** The operator switched one-click updates off on this box. Refused before
+ *  any gateway call is made; the copy carries the manual path. */
+export function describeUpdateDisabled() {
+    return {
+        ok: false,
+        status: 'blocked',
+        message: 'One-click updates are switched off on this box (REEFCLAW_ALLOW_CONNECTOR_UPDATE=0). '
+            + `Update from a shell on the box instead: ${CONNECTOR_UPDATE_COMMAND}`,
+    };
+}
 /**
  * Once the command is running, losing the transport is EXPECTED — the installer
  * restarts the gateway, which is the process hosting both the PTY and our own
@@ -210,3 +250,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

@@ -40,6 +40,11 @@ export declare class GatewayProvider implements OpenClawProvider {
      *  Surfaced in agent_state so the dashboard header can show the real agent +
      *  model instead of a hardcoded placeholder. Empty until the gateway answers. */
     private agentIdentity;
+    /** Foreign agent ids whose runs we have already logged as ignored (once each). */
+    private readonly ignoredForeignAgents;
+    /** The OpenClaw agent this bridge serves: chat goes to it, and only its runs
+     *  reach the dashboard (gateway/agent-scope.ts). */
+    private agentId;
     /** Emit the one-time rollout probe (gateway response shape) only on the first attempt. */
     private loggedAgentIdentityProbe;
     /** Last IDENTITY.md read (epoch ms) — TTL gate for the display-name re-read. */
@@ -265,11 +270,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 +306,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,8 @@ 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, describeUpdateDisabled, } from './connector-update.js';
+import { DEFAULT_AGENT_ID, isForeignAgentEvent, resolveAgentEventOwner } from '../gateway/agent-scope.js';
 const TAG = 'gateway';
 // ---- Day-start NAV persistence ----
 // Persists sessionStartNav (the UTC-day P&L anchor) per date so Day P&L
@@ -159,6 +160,13 @@ export class GatewayProvider {
      *  Surfaced in agent_state so the dashboard header can show the real agent +
      *  model instead of a hardcoded placeholder. Empty until the gateway answers. */
     agentIdentity = {};
+    /** Foreign agent ids whose runs we have already logged as ignored (once each). */
+    ignoredForeignAgents = new Set();
+    /** The OpenClaw agent this bridge serves: chat goes to it, and only its runs
+     *  reach the dashboard (gateway/agent-scope.ts). */
+    agentId() {
+        return this.config.agentId ?? DEFAULT_AGENT_ID;
+    }
     /** Emit the one-time rollout probe (gateway response shape) only on the first attempt. */
     loggedAgentIdentityProbe = false;
     /** Last IDENTITY.md read (epoch ms) — TTL gate for the display-name re-read. */
@@ -669,7 +677,7 @@ export class GatewayProvider {
         }
         try {
             const idempotencyKey = `chat-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
-            await ws.sendRpc('agent', { message: content, idempotencyKey, agentId: 'main' });
+            await ws.sendRpc('agent', { message: content, idempotencyKey, agentId: this.agentId() });
             return { received: true };
         }
         catch (err) {
@@ -749,87 +757,51 @@ export class GatewayProvider {
      * `restarting` and the dashboard waits for the reconnect.
      */
     async updateConnector(args) {
-        const ws = this.wsClient;
-        if (!ws) {
+        // Per-host opt-out FIRST: a box whose operator switched this off must
+        // never open a PTY, connected or not (REEFCLAW_ALLOW_CONNECTOR_UPDATE=0 /
+        // plugin-config.json connectorUpdate:'off').
+        if (this.config.allowConnectorUpdate === false) {
+            logger.info(TAG, 'connector.update refused: one-click updates are switched off on this box');
+            return describeUpdateDisabled();
+        }
+        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 +1255,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 +1281,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))
@@ -1378,6 +1381,19 @@ export class GatewayProvider {
     onAgentEvent(payload) {
         if (!this.started || !this.eventParser)
             return;
+        // Only OUR agent's runs belong in the dashboard. The gateway broadcasts
+        // every agent's events to every operator connection, so on a shared
+        // gateway a neighbour's cron briefing used to stream into the chat and
+        // across the relay (2026-09-16 audit, item 1). See gateway/agent-scope.ts.
+        if (isForeignAgentEvent(payload, this.agentId())) {
+            const owner = resolveAgentEventOwner(payload) ?? '?';
+            if (!this.ignoredForeignAgents.has(owner)) {
+                this.ignoredForeignAgents.add(owner);
+                logger.warn(TAG, `Ignoring run events from agent '${owner}' — this bridge serves '${this.agentId()}' ` +
+                    '(the gateway default agent unless overridden; set OPENCLAW_AGENT_ID / --agent-id if that is the wrong agent)');
+            }
+            return;
+        }
         // Turn lifecycle WITH the session key — the heartbeat flight recorder
         // keys off `agent:main:cron:…` to scan the beat's transcript right after
         // it ends. Fired before parsing so it never depends on parser state.
@@ -2357,7 +2373,8 @@ export class GatewayProvider {
             (Array.isArray(root.data) && root.data) ||
             [root];
         const rows = rowsRaw.filter((r) => !!r && typeof r === 'object');
-        const row = rows.find((r) => r.agentId === 'main') ?? rows[0];
+        const own = this.agentId();
+        const row = rows.find((r) => r.agentId === own) ?? rows[0];
         const runtime = row ? (asObj(row.agentRuntime) ?? asObj(row.runtime)) : undefined;
         const defaults = asObj(root.defaults);
         return flatModel(row?.model) ?? flatModel(runtime?.model) ?? flatModel(defaults?.model) ?? flatModel(root.model);
@@ -3116,7 +3133,7 @@ export class GatewayProvider {
         ].join('\n');
         try {
             const idempotencyKey = `mission-${mission.missionId}-${Date.now()}`;
-            await ws.sendRpc('agent', { message, idempotencyKey, agentId: 'main' });
+            await ws.sendRpc('agent', { message, idempotencyKey, agentId: this.agentId() });
             logger.info(TAG, `Presented mission ${mission.missionId} to agent ($${absoluteSize.toFixed(2)}, ${quantity.toFixed(6)} units)`);
         }
         catch (err) {

package/assets/plugin/exchange-adapter.d.ts

@@ -48,8 +48,13 @@ export interface IExchangeAdapter {
      *  @param closeReason Tags the resulting Trade record with who initiated the close.
      *    Paper mode persists it on the closing Trade.metadata.closeReason so the agent
      *    can see on its next heartbeat that e.g. a stop_watcher auto-closed the trade.
-     *    Live mode currently ignores this (metadata not tracked in live path). */
-    closePosition(symbol: string, closeReason?: CloseReason): Promise<CcxtOrder>;
+     *    Live mode currently ignores this (metadata not tracked in live path).
+     *  @param referencePrice Paper-only: the price the closing DECISION was made
+     *    on (a stop's breach mark, a target level). The simulator anchors the
+     *    fill to it instead of whatever tick/book it has cached: a stop that
+     *    filled off an entry-time cache booked a -1.04R loss as -0.02R
+     *    (2026-09-16 audit). Live venues fill at market and ignore it. */
+    closePosition(symbol: string, closeReason?: CloseReason, referencePrice?: number): Promise<CcxtOrder>;
     getBalance(): Promise<CcxtBalance>;
     getPositions(symbol?: string): Promise<CcxtPosition[]>;
     /**

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/live/stop-watcher.js

@@ -212,7 +212,13 @@ export class PositionWatcher extends EventEmitter {
                 throw new Error(`Wave 9 ownership resolution failed before stop close submission: ${ownershipError}; ` +
                     'IMMEDIATE MANUAL INTERVENTION REQUIRED');
             }
-            closeOrder = await this.adapter.closePosition(trustedPosition.symbol, 'stop_watcher');
+            // Fill at the mark the breach decision was made on, not at whatever the
+            // paper engine has cached (the take-profit leg already passes its level
+            // the same way). Live adapters fill at market and ignore the reference.
+            const stopFillPrice = Number.isFinite(trustedPosition.markPrice) && trustedPosition.markPrice > 0
+                ? trustedPosition.markPrice
+                : undefined;
+            closeOrder = await this.adapter.closePosition(trustedPosition.symbol, 'stop_watcher', stopFillPrice);
             if (!candidateId || !this.wave9CloseLifecycle)
                 return 'closed';
             const outcome = await this.wave9CloseLifecycle.settleAfterClose(candidateId, trustedPosition.symbol);

package/assets/plugin/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "reefclaw-paper-trading",
   "name": "ReefClaw Trading",
-  "version": "0.1.27",
+  "version": "0.1.29",
   "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/paper-adapter.d.ts

@@ -13,7 +13,7 @@ export declare class PaperAdapter implements IExchangeAdapter {
     createOrder(symbol: string, side: 'buy' | 'sell', type: 'market' | 'limit', amount: number, price?: number, metadata?: PositionMetadata, _options?: OrderOptions): Promise<CcxtOrder>;
     cancelOrder(orderId: string, _symbol?: string): Promise<CcxtOrder>;
     cancelAllOrders(symbol?: string): Promise<CcxtOrder[]>;
-    closePosition(symbol: string, closeReason?: CloseReason): Promise<CcxtOrder>;
+    closePosition(symbol: string, closeReason?: CloseReason, referencePrice?: number): Promise<CcxtOrder>;
     getBalance(): Promise<CcxtBalance>;
     getPositions(symbol?: string): Promise<CcxtPosition[]>;
     /** Paper has no exchange fetch to fail — position state is always known. */

package/assets/plugin/paper-adapter.js

@@ -22,8 +22,8 @@ export class PaperAdapter {
     async cancelAllOrders(symbol) {
         return this.simulator.cancelAllOrders(symbol);
     }
-    async closePosition(symbol, closeReason) {
-        return this.simulator.closePosition(symbol, closeReason);
+    async closePosition(symbol, closeReason, referencePrice) {
+        return this.simulator.closePosition(symbol, closeReason, referencePrice);
     }
     // Reads pull a newer state.json first (ExchangeSimulator.refreshState —
     // no-op without a hook). Out-of-tool readers (DB-vs-exchange sweep,

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;