@reefclaw/openclaw-plugin 0.1.24 → 0.1.25

package/bridge/connector.d.ts

@@ -22,7 +22,9 @@ export declare class Connector {
     private lastMessageAt;
     private destroyed;
     constructor(config: ConnectorConfig, callbacks: ConnectorCallbacks);
-    /** Build the relay WebSocket URL (token is sent via Authorization header, not URL) */
+    /** Build the relay WebSocket URL (token is sent via Authorization header, not
+     *  URL; the instance id is non-secret and rides the query string so the
+     *  relay's skill-slot admission can recognise a same-box restart). */
     private buildUrl;
     /** Start connecting to the relay */
     connect(): void;

package/bridge/connector.js

@@ -37,10 +37,15 @@ export class Connector {
         this.reconnectConfig = { ...DEFAULT_RECONNECT, ...config.reconnect };
         this.heartbeatConfig = { ...DEFAULT_HEARTBEAT };
     }
-    /** Build the relay WebSocket URL (token is sent via Authorization header, not URL) */
+    /** Build the relay WebSocket URL (token is sent via Authorization header, not
+     *  URL; the instance id is non-secret and rides the query string so the
+     *  relay's skill-slot admission can recognise a same-box restart). */
     buildUrl() {
         const base = this.config.relayUrl.replace(/\/$/, '');
-        return `${base}/parties/reefclaw/${this.config.userId}`;
+        const path = `${base}/parties/reefclaw/${this.config.userId}`;
+        return this.config.instanceId
+            ? `${path}?instance=${encodeURIComponent(this.config.instanceId)}`
+            : path;
     }
     /** Start connecting to the relay */
     connect() {
@@ -96,6 +101,24 @@ export class Connector {
                 }, 15 * 60_000);
                 return;
             }
+            // 4011 = another agent holds this account's skill slot and is alive
+            // (relay skill-slot admission, 2026-08-25 — the fix for the 4010
+            // ping-pong two bridges used to fight). Retrying fast is pointless and
+            // noisy: the seated agent keeps the slot until it stops. Slow-probe
+            // every 5 min so a deliberate box switch (stop the old one) is picked
+            // up without a manual restart here.
+            if (code === 4011) {
+                logger.error(TAG, `Relay refused this connection (4011): another agent is already connected for this ` +
+                    `account. ReefClaw runs ONE agent per account — stop the other agent (or revoke its ` +
+                    `token in the dashboard) to move this box in. Probing again in 5 min.`);
+                this.setState('failed');
+                this.attempt = 0;
+                this.reconnectTimer = setTimeout(() => {
+                    this.reconnectTimer = null;
+                    this.connect();
+                }, 5 * 60_000);
+                return;
+            }
             // 4002 = stale skill connection on relay. Wait for it to time out, then retry.
             if (code === 4002) {
                 logger.warn(TAG, 'Stale skill connection on relay — waiting 10s before retry');
@@ -275,6 +298,18 @@ export class Connector {
             // Send a native WebSocket ping (protocol-level, handled by PartyKit automatically).
             if (this.ws && this.ws.readyState === WebSocket.OPEN) {
                 this.ws.ping();
+                // App-level keepalive: native pings are absorbed by the PartyKit
+                // runtime and never reach the relay DO, so an idle-but-healthy agent
+                // would look dead to the skill-slot admission's liveness window and
+                // could be evicted by a second box's probe. One tiny frame per
+                // heartbeat tick keeps the seat provably occupied; the relay swallows
+                // it (never forwarded to browsers, never audited).
+                this.ws.send(JSON.stringify({
+                    type: 'event',
+                    event: 'skill_keepalive',
+                    channel: 'agent_state',
+                    payload: { ts: Date.now() },
+                }));
             }
         }, this.heartbeatConfig.intervalMs);
         logger.debug(TAG, `Heartbeat started: interval=${this.heartbeatConfig.intervalMs}ms timeout=${this.heartbeatConfig.timeoutMs}ms`);

package/bridge/gateway/heartbeat-cron.js

@@ -49,7 +49,8 @@ export const HEARTBEAT_MESSAGE = 'Heartbeat. Execute EVERY checkbox in the HEART
     'do NOT re-read SKILL.md from disk unless preparing a NEW entry). ' +
     'NON-SKIPPABLE every beat: (1) query_trades({hours:1}) stop-watcher reconcile; ' +
     '(2) get_wave9_status() once, unconditionally; ' +
-    '(3) if ANY position is open: get_my_recent_reviews() + get_relevant_learnings({applies_at: heartbeat}) in one batch, ' +
+    '(3) if ANY position is open and the Position Decision Journal is enabled (record_position_reviews reports off-mode when it is not): ' +
+    'get_my_recent_reviews() + get_relevant_learnings({applies_at: heartbeat}) in one batch, ' +
     'then record_position_reviews with ONE review per open position, ' +
     'plus get_resting_liquidity + get_liquidation_levels + get_liquidation_pulse for ALL positions in one parallel batch; ' +
     '(4) the Market Assessment reads. ' +

package/bridge/index.js

@@ -16,7 +16,9 @@ import { MockProvider } from './providers/mock.js';
 import { GatewayProvider } from './providers/gateway.js';
 import { resolveConfig } from './config.js';
 import { resolveGatewayConfig, validateGatewayConfig } from './gateway/gateway-config.js';
+import { ShockWakePoller } from './shock-wake.js';
 import { runSetup } from './setup.js';
+import { resolveRelayInstanceId } from './utils/instance-id.js';
 const TAG = 'main';
 // ---- Load .env file (skill/.env only) ----
 function loadEnvFile() {
@@ -191,6 +193,7 @@ async function main() {
     }
     // Create provider
     let provider;
+    let intelligenceUrlForWakes;
     if (args.provider === 'mock') {
         logger.info(TAG, 'Using MockProvider');
         provider = new MockProvider();
@@ -217,14 +220,30 @@ async function main() {
         gwConfig.connectionToken = token;
         logger.info(TAG, `Using GatewayProvider (url=${gwConfig.gatewayUrl}, symbol=${gwConfig.symbol})`);
         provider = new GatewayProvider(gwConfig);
+        intelligenceUrlForWakes = gwConfig.intelligenceUrl;
     }
     // Create bridge
     const connectorConfig = {
         relayUrl,
         userId,
         token,
+        // Stable per-install id → the relay's skill-slot admission recognises a
+        // same-box restart (instant takeover) vs a second box (rejected 4011).
+        instanceId: resolveRelayInstanceId(),
     };
     const bridge = new Bridge(provider, connectorConfig);
+    // Shock-wake poller (WS3, docs/MARKET_ADAPTIVITY_PLAN.md) — watches intel's
+    // /api/shocks (the WS2 change-of-character flags) and delivers an
+    // out-of-band re-evaluation turn to the agent on a genuine market shift.
+    // Inert until the central gate agent_config.gates.shockWake leaves 'off'.
+    const shockWake = intelligenceUrlForWakes
+        ? new ShockWakePoller({ provider, token, intelligenceUrl: intelligenceUrlForWakes })
+        : null;
+    if (shockWake) {
+        // Delivery confirmation: any agent turn STARTING proves the main-session
+        // lane is alive — the gateway ack alone cannot (swallowed-turn class).
+        provider.on('chatMessageStart', () => shockWake.noteAssistantActivity());
+    }
     // Handle graceful shutdown
     let shuttingDown = false;
     async function shutdown(signal) {
@@ -239,6 +258,7 @@ async function main() {
             }
             catch { /* best-effort */ }
         }
+        shockWake?.stop();
         bridge.stop();
         // Allow 1s for final cleanup before force exit
         setTimeout(() => process.exit(0), 1000);
@@ -248,5 +268,6 @@ async function main() {
     // Start
     logger.info(TAG, `Starting ReefClaw skill (provider=${args.provider}, relay=${relayUrl})`);
     bridge.start();
+    shockWake?.start();
 }
 main();

package/bridge/shock-wake.d.ts

@@ -0,0 +1,80 @@
+export type ShockWakeMode = 'off' | 'shadow' | 'on';
+export interface ShockEntry {
+    symbol: string;
+    time: string;
+    flags: string[];
+    shock30mAtr: number;
+    range30mAtr: number;
+    return1hPct: number;
+    return4hPct: number;
+    tape4hAtr: number;
+    regime: string;
+    summary?: string;
+}
+/** 'BTCUSDT' / 'HL_BTC' / 'BTC/USDC' → 'BTC'. Best-effort market vocabulary
+ *  for the wake message — never used to address an order. */
+export declare function coinOf(intelSymbol: string): string;
+/** Parse gates.shockWake off the raw /api/internal/config payload. Central-only
+ *  gate — absent/garbage → 'off'. */
+export declare function parseShockWakeGate(raw: unknown): ShockWakeMode;
+export interface WakeAssessment {
+    wake: boolean;
+    reason?: 'leader_shock' | 'broad_shock';
+    /** Fresh 'shock'-flagged entries, extreme-first (as served). */
+    shocked: ShockEntry[];
+}
+/** Pure wake-worthiness rule. `nowMs` gates staleness. Broad rule (2026-09-06):
+ *  ≥`minBroadCount` distinct coins shocked, OR ≥3 when a major participates. */
+export declare function assessWakeWorthiness(shocks: ShockEntry[], nowMs: number, minBroadCount?: number): WakeAssessment;
+/** The out-of-band agent turn. Clearly machine-labeled (never impersonates the
+ *  operator), mandates re-evaluation, orders nothing. */
+export declare function buildWakeMessage(a: WakeAssessment): string;
+export interface ShockWakeOpts {
+    provider: {
+        handleChat(content: string): Promise<{
+            received: boolean;
+            error?: string;
+        }>;
+    };
+    token: string;
+    intelligenceUrl: string;
+    webappUrl?: string;
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+}
+export declare class ShockWakePoller {
+    private readonly opts;
+    private mode;
+    private pollTimer;
+    private gateTimer;
+    private lastWakeAtMs;
+    private wakesToday;
+    private wakeDayUtc;
+    private polling;
+    private readonly pollMs;
+    private readonly gatePollMs;
+    private readonly cooldownMs;
+    private readonly dailyCap;
+    private readonly minBroad;
+    private readonly replyTimeoutMs;
+    private lastAssistantAtMs;
+    private awaitingSinceMs;
+    private awaitingDeadlineMs;
+    private suspectedSwallows;
+    constructor(opts: ShockWakeOpts);
+    start(): void;
+    stop(): void;
+    getMode(): ShockWakeMode;
+    /** Fed by the bridge from provider `chatMessageStart` — any agent turn
+     *  beginning counts (the wake's reply, or an operator chat's; either proves
+     *  the lane is alive, which is what the swallow check needs). */
+    noteAssistantActivity(atMs?: number): void;
+    /** Suspected-swallow count this process (test/telemetry seam). */
+    getSuspectedSwallows(): number;
+    private checkPendingReply;
+    private refreshGate;
+    /** One poll cycle. Exposed for tests. */
+    tick(): Promise<void>;
+    /** Test seam. */
+    __setModeForTest(mode: ShockWakeMode): void;
+}

package/bridge/shock-wake.js

@@ -0,0 +1,291 @@
+// Shock-wake poller — WS3 of docs/MARKET_ADAPTIVITY_PLAN.md.
+//
+// The agent thinks on a 15–30 min heartbeat; an announcement lands mid-cycle
+// and isn't reconsidered until the next one — the adaptivity investigation's
+// core latency gap. This poller watches intel's /api/shocks (the WS2
+// change-of-character flags, computed each fact pass) and, when the market
+// genuinely changes character, delivers ONE out-of-band agent turn through
+// the same gateway path operator chat uses (provider.handleChat — the
+// precedent is the trade-mission presenter).
+//
+// Guardrails (every one deliberately boring):
+//   - Central gate `agent_config.gates.shockWake`: off (default) → shadow
+//     (logs WOULD WAKE, delivers nothing) → on. Polled from the webapp
+//     every ~5 min; absent/garbage/outage → off. No local file fallback —
+//     this gate is central-only.
+//   - Wake-worthy = a market LEADER (BTC/ETH) flagged 'shock', OR a broad
+//     correlated move: ≥5 distinct coins shocked (env RC_SHOCK_WAKE_MIN_BROAD),
+//     or ≥3 when a MAJOR (BTC/ETH/BNB/SOL/XRP) is among them. Disagreement-only
+//     flags never wake — they are slow-moving and already ride scan_pairs
+//     indication. (Broad bar raised from a flat ≥3 on 2026-09-06: the first
+//     live night delivered 7 wakes on rotating 3-coin mid-cap alt clusters —
+//     routine alt volatility, not announcements. Replayed against the new
+//     rule, those 7 become 1.)
+//   - Stale shocks (fact older than 10 min) are ignored.
+//   - Global cooldown 60 min between wakes + daily cap 8 (UTC), armed in
+//     shadow too so the shadow soak counts exactly what 'on' would deliver.
+//     A FAILED delivery does not arm the cooldown (retry next tick).
+//     (Cooldown default raised 30→60 min 2026-09-05: the shadow soak showed a
+//     single sustained 09-03 event re-firing 4 would-wakes in 95 min — one
+//     re-ping per hour during a long move is the intended cadence.)
+//   - The wake is INDICATION: it mandates re-evaluation, never an action.
+//   - DELIVERY CONFIRMATION (2026-09-06): the gateway acks the RPC even when
+//     the main-session lane silently swallows the turn (the 2026-07-22
+//     OpenClaw class — 7 of the first night's 9 wakes died this way). The
+//     bridge wires provider `chatMessageStart` into noteAssistantActivity();
+//     if no agent turn STARTS within RC_SHOCK_WAKE_REPLY_TIMEOUT_MS (10 min)
+//     of a delivered wake, a WARN names the swallow suspicion (dashboard chat
+//     is likely dead too) and a counter increments. Observability only — no
+//     auto-retry into a wedged lane.
+//
+// Env overrides: RC_SHOCK_WAKE_POLL_MS (60s), RC_SHOCK_WAKE_GATE_POLL_MS
+// (5 min), RC_SHOCK_WAKE_COOLDOWN_MS (30 min), RC_SHOCK_WAKE_DAILY_CAP (8).
+import { logger, formatError } from './logger.js';
+const TAG = 'shock-wake';
+/** Leaders whose lone shock is wake-worthy, as base coins (venue-stripped). */
+const LEADER_COINS = new Set(['BTC', 'ETH']);
+/** Majors (the platform's liquidation-pulse majors group): their participation
+ *  lowers the broad-shock coin bar from 5 to 3 — a SOL-led cluster is market
+ *  information; three rotating meme-alts are Tuesday. */
+const MAJOR_COINS = new Set(['BTC', 'ETH', 'BNB', 'SOL', 'XRP']);
+const STALE_SHOCK_MS = 10 * 60_000;
+function envInt(name, fallback) {
+    const v = Number(process.env[name]);
+    return Number.isFinite(v) && v > 0 ? v : fallback;
+}
+/** 'BTCUSDT' / 'HL_BTC' / 'BTC/USDC' → 'BTC'. Best-effort market vocabulary
+ *  for the wake message — never used to address an order. */
+export function coinOf(intelSymbol) {
+    return intelSymbol
+        .replace(/^HL_/, '')
+        .replace(/\/.*$/, '')
+        .replace(/(USDT|USDC|BUSD)$/i, '')
+        .toUpperCase();
+}
+/** Parse gates.shockWake off the raw /api/internal/config payload. Central-only
+ *  gate — absent/garbage → 'off'. */
+export function parseShockWakeGate(raw) {
+    if (!raw || typeof raw !== 'object')
+        return 'off';
+    const gates = raw.gates;
+    if (!gates || typeof gates !== 'object')
+        return 'off';
+    const v = gates.shockWake;
+    return v === 'shadow' || v === 'on' ? v : 'off';
+}
+/** Pure wake-worthiness rule. `nowMs` gates staleness. Broad rule (2026-09-06):
+ *  ≥`minBroadCount` distinct coins shocked, OR ≥3 when a major participates. */
+export function assessWakeWorthiness(shocks, nowMs, minBroadCount = 5) {
+    const fresh = shocks.filter((s) => {
+        const t = Date.parse(s.time);
+        return Number.isFinite(t) && nowMs - t <= STALE_SHOCK_MS;
+    });
+    const shocked = fresh.filter((s) => s.flags.includes('shock'));
+    // One coin can appear per-venue (BTCUSDT + HL_BTC) — count coins, not rows.
+    const coins = new Set(shocked.map((s) => coinOf(s.symbol)));
+    const leader = shocked.find((s) => LEADER_COINS.has(coinOf(s.symbol)));
+    if (leader)
+        return { wake: true, reason: 'leader_shock', shocked };
+    const hasMajor = [...coins].some((c) => MAJOR_COINS.has(c));
+    if (coins.size >= minBroadCount || (hasMajor && coins.size >= 3)) {
+        return { wake: true, reason: 'broad_shock', shocked };
+    }
+    return { wake: false, shocked };
+}
+/** The out-of-band agent turn. Clearly machine-labeled (never impersonates the
+ *  operator), mandates re-evaluation, orders nothing. */
+export function buildWakeMessage(a) {
+    const seen = new Set();
+    const lines = [];
+    for (const s of a.shocked) {
+        const coin = coinOf(s.symbol);
+        if (seen.has(coin))
+            continue;
+        seen.add(coin);
+        const sign = (v) => (v >= 0 ? '+' : '');
+        lines.push(`- ${coin}: 30m ${Math.max(s.shock30mAtr, s.range30mAtr).toFixed(1)}×ATR, ` +
+            `1h ${sign(s.return1hPct)}${s.return1hPct}%, 4h ${sign(s.return4hPct)}${s.return4hPct}% ` +
+            `(regime label: ${s.regime})`);
+        if (lines.length >= 6)
+            break;
+    }
+    return [
+        '[AUTOMATED MARKET-SHIFT ALERT — from the ReefClaw system, NOT the operator]',
+        '',
+        a.reason === 'leader_shock'
+            ? 'A market leader just moved sharply — the market may have changed character:'
+            : 'Multiple symbols moved sharply together — the market may have changed character:',
+        ...lines,
+        '',
+        'Do this NOW, ahead of your scheduled heartbeat:',
+        '1. Re-derive your directional bias from FRESH data (scan_pairs, get_regime) — do NOT lean on theses formed before this move; regime labels may LAG it (see market_shift_caution in scan results).',
+        '2. For EVERY open position: check the pinned invalidation FIRST. If price is through it, act on your own plan.',
+        '3. Hold off on new entries until the re-derived bias and the tape agree.',
+        '',
+        'This alert is indication only — it does not order you to close anything. Reply with a brief assessment so the operator sees your read.',
+    ].join('\n');
+}
+export class ShockWakePoller {
+    opts;
+    mode = 'off';
+    pollTimer = null;
+    gateTimer = null;
+    lastWakeAtMs = 0;
+    wakesToday = 0;
+    wakeDayUtc = '';
+    polling = false;
+    pollMs = envInt('RC_SHOCK_WAKE_POLL_MS', 60_000);
+    gatePollMs = envInt('RC_SHOCK_WAKE_GATE_POLL_MS', 5 * 60_000);
+    cooldownMs = envInt('RC_SHOCK_WAKE_COOLDOWN_MS', 60 * 60_000);
+    dailyCap = envInt('RC_SHOCK_WAKE_DAILY_CAP', 8);
+    minBroad = envInt('RC_SHOCK_WAKE_MIN_BROAD', 5);
+    replyTimeoutMs = envInt('RC_SHOCK_WAKE_REPLY_TIMEOUT_MS', 10 * 60_000);
+    // Delivery confirmation (see header): a wake is only proven delivered when
+    // an agent turn STARTS after it. lastAssistantAtMs is fed by the bridge's
+    // chatMessageStart wiring; awaitingSince/deadline track one in-flight wake
+    // (the 60-min cooldown guarantees no overlap with the 10-min timeout).
+    lastAssistantAtMs = 0;
+    awaitingSinceMs = null;
+    awaitingDeadlineMs = 0;
+    suspectedSwallows = 0;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    start() {
+        if (this.pollTimer)
+            return;
+        const refresh = () => { void this.refreshGate(); };
+        refresh();
+        this.gateTimer = setInterval(refresh, this.gatePollMs);
+        this.gateTimer.unref?.();
+        this.pollTimer = setInterval(() => { void this.tick(); }, this.pollMs);
+        this.pollTimer.unref?.();
+        logger.info(TAG, `started (poll ${this.pollMs / 1000}s, cooldown ${this.cooldownMs / 60000}m, cap ${this.dailyCap}/day, gate polled ${this.gatePollMs / 60000}m)`);
+    }
+    stop() {
+        if (this.pollTimer)
+            clearInterval(this.pollTimer);
+        if (this.gateTimer)
+            clearInterval(this.gateTimer);
+        this.pollTimer = null;
+        this.gateTimer = null;
+    }
+    getMode() {
+        return this.mode;
+    }
+    /** Fed by the bridge from provider `chatMessageStart` — any agent turn
+     *  beginning counts (the wake's reply, or an operator chat's; either proves
+     *  the lane is alive, which is what the swallow check needs). */
+    noteAssistantActivity(atMs) {
+        const t = atMs ?? this.opts.now?.() ?? Date.now();
+        this.lastAssistantAtMs = t;
+        if (this.awaitingSinceMs !== null && t >= this.awaitingSinceMs) {
+            logger.info(TAG, `wake reply confirmed — agent turn started ${Math.round((t - this.awaitingSinceMs) / 1000)}s after delivery`);
+            this.awaitingSinceMs = null;
+        }
+    }
+    /** Suspected-swallow count this process (test/telemetry seam). */
+    getSuspectedSwallows() {
+        return this.suspectedSwallows;
+    }
+    checkPendingReply(nowMs) {
+        if (this.awaitingSinceMs === null || nowMs <= this.awaitingDeadlineMs)
+            return;
+        this.suspectedSwallows++;
+        logger.warn(TAG, `wake delivered at ${new Date(this.awaitingSinceMs).toISOString()} but NO agent turn started ` +
+            `within ${Math.round(this.replyTimeoutMs / 60_000)}m — the main-session lane may be silently ` +
+            `swallowing turns (known OpenClaw class, 2026-07-22; dashboard chat is likely affected too). ` +
+            `Suspected swallows this process: ${this.suspectedSwallows}`);
+        this.awaitingSinceMs = null;
+    }
+    async refreshGate() {
+        const base = (this.opts.webappUrl ?? process.env.REEFCLAW_API_URL ?? 'https://www.reefclaw.com').replace(/\/$/, '');
+        try {
+            const doFetch = this.opts.fetchImpl ?? fetch;
+            const res = await doFetch(`${base}/api/internal/config`, {
+                headers: { Authorization: `Bearer ${this.opts.token}` },
+            });
+            if (!res.ok)
+                return; // keep last-known mode on outage (fail toward inert)
+            const next = parseShockWakeGate(await res.json());
+            if (next !== this.mode) {
+                logger.info(TAG, `gate: shockWake ${this.mode} → ${next}`);
+                this.mode = next;
+            }
+        }
+        catch (err) {
+            logger.debug(TAG, `gate poll failed (keeping ${this.mode}): ${formatError(err)}`);
+        }
+    }
+    /** One poll cycle. Exposed for tests. */
+    async tick() {
+        const tickNowMs = this.opts.now?.() ?? Date.now();
+        // Runs even when the gate is off — a wake delivered just before an
+        // operator rollback still deserves its confirmation verdict.
+        this.checkPendingReply(tickNowMs);
+        if (this.mode === 'off' || this.polling)
+            return;
+        this.polling = true;
+        try {
+            const nowMs = tickNowMs;
+            const doFetch = this.opts.fetchImpl ?? fetch;
+            const base = this.opts.intelligenceUrl.replace(/\/$/, '');
+            const res = await doFetch(`${base}/api/shocks`, {
+                headers: { Authorization: `Bearer ${this.opts.token}` },
+            });
+            if (!res.ok)
+                return;
+            const body = (await res.json());
+            if (!Array.isArray(body?.shocks))
+                return;
+            const a = assessWakeWorthiness(body.shocks, nowMs, this.minBroad);
+            if (!a.wake)
+                return;
+            // Rate limits — checked only for wake-worthy ticks so quiet markets
+            // never touch the counters.
+            const day = new Date(nowMs).toISOString().slice(0, 10);
+            if (day !== this.wakeDayUtc) {
+                this.wakeDayUtc = day;
+                this.wakesToday = 0;
+            }
+            if (nowMs - this.lastWakeAtMs < this.cooldownMs)
+                return;
+            if (this.wakesToday >= this.dailyCap) {
+                logger.warn(TAG, `daily cap ${this.dailyCap} reached — suppressing further wakes today`);
+                return;
+            }
+            const coins = [...new Set(a.shocked.map((s) => coinOf(s.symbol)))].join(', ');
+            if (this.mode === 'shadow') {
+                this.lastWakeAtMs = nowMs;
+                this.wakesToday++;
+                logger.warn(TAG, `WOULD WAKE (shadow): ${a.reason} — ${coins} (${this.wakesToday}/${this.dailyCap} today)`);
+                return;
+            }
+            const message = buildWakeMessage(a);
+            const out = await this.opts.provider.handleChat(message);
+            if (out.received) {
+                this.lastWakeAtMs = nowMs;
+                this.wakesToday++;
+                // Arm the delivery-confirmation window (see checkPendingReply).
+                this.awaitingSinceMs = nowMs;
+                this.awaitingDeadlineMs = nowMs + this.replyTimeoutMs;
+                logger.warn(TAG, `WAKE delivered: ${a.reason} — ${coins} (${this.wakesToday}/${this.dailyCap} today)`);
+            }
+            else {
+                // Delivery failed (gateway not connected etc.) — no cooldown, retry
+                // on the next tick while the shock is still fresh.
+                logger.warn(TAG, `wake delivery FAILED (${out.error ?? 'unknown'}) — will retry next tick`);
+            }
+        }
+        catch (err) {
+            logger.debug(TAG, `tick failed: ${formatError(err)}`);
+        }
+        finally {
+            this.polling = false;
+        }
+    }
+    /** Test seam. */
+    __setModeForTest(mode) {
+        this.mode = mode;
+    }
+}

package/bridge/types.d.ts

@@ -602,6 +602,10 @@ export interface ConnectorConfig {
     relayUrl: string;
     userId: string;
     token: string;
+    /** Stable per-install id (non-secret), sent as `?instance=` so the relay's
+     *  skill-slot admission can tell "same box restarting" (instant takeover)
+     *  from "second box" (rejected 4011). See utils/instance-id.ts. */
+    instanceId?: string;
     reconnect?: {
         baseDelayMs?: number;
         maxDelayMs?: number;

package/bridge/utils/instance-id.d.ts

@@ -0,0 +1,3 @@
+/** Read-or-create the stable instance id. `baseDir` overrides the storage
+ *  directory (tests; defaults to ~/.reefclaw). Never throws. */
+export declare function resolveRelayInstanceId(baseDir?: string): string;

package/bridge/utils/instance-id.js

@@ -0,0 +1,48 @@
+// Stable per-install relay instance id (2026-08-25, skill-slot admission).
+//
+// The relay seats ONE skill connection per account and refuses newcomers —
+// EXCEPT a newcomer proving it is the same box restarting, which takes over
+// instantly (the graceful-restart property). "Same box" = this id, sent as a
+// non-secret `?instance=` query param on the relay URL. It must therefore
+// survive process restarts: persisted once per install at
+// `~/.reefclaw/relay-instance-id` and reused forever.
+//
+// Fail-open: when the filesystem refuses (read-only home, exotic container),
+// fall back to a per-process id. Takeover-after-crash then degrades to the
+// relay's liveness timeout instead of being instant — worse, never wrong.
+import { randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { logger } from '../logger.js';
+const TAG = 'instance-id';
+const ID_SHAPE = /^[A-Za-z0-9-]{8,64}$/;
+/** Read-or-create the stable instance id. `baseDir` overrides the storage
+ *  directory (tests; defaults to ~/.reefclaw). Never throws. */
+export function resolveRelayInstanceId(baseDir) {
+    // Operator escape hatch (e.g. two deliberate installs sharing one home dir).
+    const fromEnv = process.env.RC_RELAY_INSTANCE_ID?.trim();
+    if (fromEnv && ID_SHAPE.test(fromEnv))
+        return fromEnv;
+    const dir = baseDir ?? join(homedir(), '.reefclaw');
+    const file = join(dir, 'relay-instance-id');
+    try {
+        if (existsSync(file)) {
+            const existing = readFileSync(file, 'utf8').trim();
+            if (ID_SHAPE.test(existing))
+                return existing;
+            // Garbled file: fall through and rewrite — a fresh id only costs one
+            // liveness-timeout takeover, a garbled param corrupts the admission key.
+        }
+        const fresh = randomUUID();
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(file, fresh + '\n', 'utf8');
+        return fresh;
+    }
+    catch (err) {
+        const perProcess = randomUUID();
+        logger.warn(TAG, `Could not persist relay instance id (${err.message}) — using per-process id; ` +
+            `crash takeover degrades to the relay liveness timeout`);
+        return perProcess;
+    }
+}

package/config/agent-config-client.d.ts

@@ -6,12 +6,14 @@
  *  `positionReviewMode` (slice 3, the Position Decision Journal
  *  heartbeat-mandate + superset gate, file key `positionReview.mode`) →
  *  `approvalMode` (slice 4, per-trade operator approval, file key
- *  `approval.mode`). The first two ride the same four-stage
+ *  `approval.mode`) → `reentryCooldown` (create_order re-entry cooldown, file
+ *  key `reentryCooldown.mode`). All but approvalMode ride the same four-stage
  *  `off → shadow → observe → enforce` ladder; approvalMode has its own. */
 export interface AgentGates {
     exitGate?: 'off' | 'shadow' | 'observe' | 'enforce';
     positionReviewMode?: 'off' | 'shadow' | 'observe' | 'enforce';
     approvalMode?: 'off' | 'per_trade';
+    reentryCooldown?: 'off' | 'shadow' | 'observe' | 'enforce';
 }
 /** Server-resolved entitlement verdict (webapp lib/entitlements.ts, computed
  *  from the users row and delivered on the config channel). The plugin NEVER

package/config/agent-config-client.js

@@ -125,6 +125,10 @@ function validateGates(raw) {
     if (typeof approvalMode === 'string' && APPROVAL_MODE_VALUES.has(approvalMode)) {
         gates.approvalMode = approvalMode;
     }
+    const reentryCooldown = obj.reentryCooldown;
+    if (typeof reentryCooldown === 'string' && MODE_LADDER_VALUES.has(reentryCooldown)) {
+        gates.reentryCooldown = reentryCooldown;
+    }
     return gates;
 }
 /** Version-monotonic acceptance (basic rollback/replay protection): a fetched

package/config/brackets-config.d.ts

@@ -1,6 +1,7 @@
 import { type PluginConfigFile } from './plugin-config-io.js';
 export type BracketMode = 'off' | 'observe' | 'enforce';
-/** Read bracket mode from a config object. Invalid values fall back to 'off'. */
+/** Read bracket mode from a config object. Invalid values fall back to the
+ *  context default ('enforce' on a live-Binance box, else 'off'). */
 export declare function getBracketMode(config?: PluginConfigFile, remoteOverride?: BracketMode): BracketMode;
 /** Convenience: load from disk and return the effective mode. */
 export declare function loadBracketMode(): BracketMode;