@reefclaw/openclaw-plugin 0.1.23 → 0.1.25

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

@@ -3,7 +3,7 @@ export type { Channel, RequestFrame, ResponseFrame, EventFrame, Frame, Emergency
 export { VALID_CHANNELS, VALID_EMERGENCY_ACTIONS } from '@reefclaw/shared';
 type EventFrame = _EventFrame;
 /** Methods the skill accepts from the relay (browser → skill) */
-export declare const ALLOWED_METHODS: readonly ["emergency.kill", "emergency.flatten", "emergency.pause", "emergency.resume", "reconcile", "chat.send", "skill.update", "close_position", "set_trading_mode", "set_exchange_credentials", "test_exchange_credentials", "clear_exchange_credentials", "hl_provision_agent_wallet", "hl_agent_wallet_status", "hl_submit_agent_approval", "get_bracket_config", "set_bracket_requirement"];
+export declare const ALLOWED_METHODS: readonly ["emergency.kill", "emergency.flatten", "emergency.pause", "emergency.resume", "reconcile", "chat.send", "skill.update", "close_position", "set_trading_mode", "set_exchange_credentials", "test_exchange_credentials", "clear_exchange_credentials", "hl_provision_agent_wallet", "hl_agent_wallet_status", "hl_submit_agent_approval", "get_bracket_config", "set_bracket_requirement", "connector.update"];
 /** Subset of ALLOWED_METHODS that require operator.write scope. The bridge
  *  enforces this before dispatching — a session without the scope gets a
  *  403 error. PR2 ships the scope as session-wide (inherited from the Clerk
@@ -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/types.js

@@ -25,6 +25,10 @@ export const ALLOWED_METHODS = [
     // Bracket-orders config (Phase 3.5b) — operator.write-gated.
     'get_bracket_config',
     'set_bracket_requirement',
+    // Operator-triggered connector update. Runs a FIXED command on the box over
+    // the gateway PTY — carries no command/version/args field by design (see the
+    // security note in providers/connector-update.ts). operator.write-gated.
+    'connector.update',
 ];
 /** Subset of ALLOWED_METHODS that require operator.write scope. The bridge
  *  enforces this before dispatching — a session without the scope gets a
@@ -42,6 +46,7 @@ export const OPERATOR_WRITE_METHODS = new Set([
     'hl_submit_agent_approval',
     'get_bracket_config',
     'set_bracket_requirement',
+    'connector.update',
     'emergency.kill',
     'emergency.flatten',
     'emergency.pause',

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/ccxt/binance-private.js

@@ -813,7 +813,8 @@ export class BinancePrivateApi {
             const raw = await this.exchange.fetchTicker(symbol);
             noteSuccess();
             return {
-                symbol: raw.symbol,
+                // Echo the REQUESTED symbol — see BinancePublicApi.fetchTicker.
+                symbol,
                 last: raw.last ?? 0,
                 bid: raw.bid ?? 0,
                 ask: raw.ask ?? 0,

package/ccxt/binance-public.js

@@ -86,7 +86,12 @@ export class BinancePublicApi {
             const raw = await this.exchange.fetchTicker(symbol);
             noteSuccess();
             return {
-                symbol: raw.symbol,
+                // Echo the REQUESTED symbol, not ccxt's unified form. ccxt rewrites
+                // 'ETH/USDT' → 'ETH/USDT:USDT' on USDM futures; returning that made
+                // callers key per-symbol caches under a name the caller never asked
+                // for (see the simulator's tickerKey note). Same invariant that
+                // intel-public.ts fetchTicker already documents.
+                symbol,
                 last: raw.last ?? 0,
                 bid: raw.bid ?? 0,
                 ask: raw.ask ?? 0,

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

@@ -4,11 +4,16 @@
  *  never whole-payload rejection. Gates are added one at a time
  *  (TOOL_DISTRIBUTION_ARCHITECTURE.md §11 step 3): `exitGate` (slice 2) →
  *  `positionReviewMode` (slice 3, the Position Decision Journal
- *  heartbeat-mandate + superset gate, file key `positionReview.mode`). Both
- *  ride the same four-stage `off → shadow → observe → enforce` ladder. */
+ *  heartbeat-mandate + superset gate, file key `positionReview.mode`) →
+ *  `approvalMode` (slice 4, per-trade operator approval, file key
+ *  `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

@@ -23,6 +23,15 @@ const TAG = 'agent-config';
  *  because exitGate + positionReviewMode use identical values; a future gate
  *  with a different enum gets its own constant. */
 const MODE_LADDER_VALUES = new Set(['off', 'shadow', 'observe', 'enforce']);
+/** approvalMode's own enum — deliberately NOT the four-stage ladder.
+ *
+ *  ★ `shadow` is absent on purpose. Shadow proposal telemetry is driven by the
+ *  APPROVAL_SHADOW_MODE systemd env flag, which is boot-snapshotted and local
+ *  to the box; it is not a central value. Accepting 'shadow' here would let a
+ *  central push silently enable telemetry writes the operator never configured,
+ *  and would collide with the env flag's precedence. Central can express
+ *  exactly the two states that change trading behaviour. */
+const APPROVAL_MODE_VALUES = new Set(['off', 'per_trade']);
 const ENTITLEMENT_STATES = new Set([
     'active',
     'trialing',
@@ -112,6 +121,14 @@ function validateGates(raw) {
     if (typeof positionReviewMode === 'string' && MODE_LADDER_VALUES.has(positionReviewMode)) {
         gates.positionReviewMode = positionReviewMode;
     }
+    const approvalMode = obj.approvalMode;
+    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/agent-config-poller.js

@@ -65,7 +65,11 @@ export function startAgentConfigPoller(opts) {
         });
         if (fetched) {
             loggedFetchFailure = false;
-            if (applyIfAcceptable(fetched, 'network')) {
+            // Only touch the cache file when the config actually changed —
+            // isAcceptableVersion accepts equal versions, so this used to do a
+            // blocking write+rename every 60s poll forever.
+            const prevJson = JSON.stringify(current);
+            if (applyIfAcceptable(fetched, 'network') && JSON.stringify(fetched) !== prevJson) {
                 writeCachedConfig(fetched, opts.cachePath);
             }
             return;

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;

package/config/brackets-config.js

@@ -5,10 +5,32 @@
 //      in memory on the plugin after push; not persisted to plugin-config.json.
 //      Wired in Phase 2; for Phase 1 this is always undefined.
 //   2. Local plugin-config.json `brackets.mode` field.
-//   3. Default: 'off' (legacy stop-watcher remains authoritative).
+//   3. Default: CONTEXT-AWARE since 2026-08-25 (E2E audit #3, the last
+//      real-money item on the fresh-box list): a box whose persisted
+//      tradingMode is MICRO_LIVE/LIVE on the BINANCE venue defaults to
+//      'enforce' — the historical 'off' default meant a fresh npx install
+//      flipped to live traded with NO exchange-side stops AND no mandatory-
+//      stop pre-trade gate (the gate is wired behind bracketsEnabled), i.e.
+//      genuinely naked, with no in-product way to notice. Everything else
+//      (paper, shadow, hyperliquid — whose adapter enforces brackets
+//      unconditionally and ignores this Binance-only knob) keeps 'off'.
+//      An EXPLICIT 'off' in config is still honored (operator break-glass,
+//      behind the Settings type-to-confirm guard) — with the new default it
+//      can only ever be a deliberate choice.
 import { readPluginConfig } from './plugin-config-io.js';
 const VALID = new Set(['off', 'observe', 'enforce']);
-/** Read bracket mode from a config object. Invalid values fall back to 'off'. */
+/** Does this config describe a live-Binance box — the one context where an
+ *  unset bracket mode must NOT mean "no protection"? Reads the PERSISTED
+ *  trading mode (set_trading_mode persists BEFORE the adapter swap, so
+ *  construction-time and per-call reads agree). */
+function isLiveBinanceContext(config) {
+    const mode = config?.tradingMode;
+    if (mode !== 'MICRO_LIVE' && mode !== 'LIVE')
+        return false;
+    return config?.exchange?.venue !== 'hyperliquid';
+}
+/** Read bracket mode from a config object. Invalid values fall back to the
+ *  context default ('enforce' on a live-Binance box, else 'off'). */
 export function getBracketMode(config, remoteOverride) {
     if (remoteOverride && VALID.has(remoteOverride))
         return remoteOverride;
@@ -16,7 +38,7 @@ export function getBracketMode(config, remoteOverride) {
     if (typeof raw === 'string' && VALID.has(raw)) {
         return raw;
     }
-    return 'off';
+    return isLiveBinanceContext(config) ? 'enforce' : 'off';
 }
 /** Convenience: load from disk and return the effective mode. */
 export function loadBracketMode() {

package/config/gate-store.d.ts

@@ -9,6 +9,18 @@ declare class GateStore {
     /** The central positionReview.mode, or null when central has no value (or the
      *  kill-switch is on) — null tells the reader to fall back to the file. */
     getPositionReviewMode(): AgentGates['positionReviewMode'] | null;
+    /** The central approval.mode, or null when central has no value (or the
+     *  kill-switch is on) — null tells the reader to fall back to the file.
+     *
+     *  ★ Central can only ever say 'off' or 'per_trade'. It cannot enable shadow
+     *  telemetry (that's the local APPROVAL_SHADOW_MODE env flag) and it cannot
+     *  weaken the hardcoded safety floor — per_trade only ADDS a gate, and 'off'
+     *  is the pre-existing autonomous behaviour, so neither value can leave a
+     *  position unprotected. */
+    getApprovalMode(): AgentGates['approvalMode'] | null;
+    /** The central reentryCooldown mode, or null when central has no value (or
+     *  the kill-switch is on) — null tells the reader to fall back to the file. */
+    getReentryCooldown(): AgentGates['reentryCooldown'] | null;
     /** Test-only. */
     __reset(): void;
 }