@reefclaw/connect 0.1.32 → 0.1.33

package/assets/plugin/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/assets/plugin/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/assets/plugin/index.js

@@ -1385,12 +1385,21 @@ const paperTradingPlugin = {
                 // Micro-live cap — same loader every runtime reconnect uses
                 // (buildAdapter), so boot and reconnect can never disagree (F8).
                 const microLiveConfig = loadMicroLiveConfig();
-                // Bracket-orders feature flag read from plugin-config at construction time.
-                // Default 'off' keeps legacy stop-watcher behaviour while the feature rolls out.
+                // Bracket-orders feature flag read from plugin-config at construction
+                // time. Since 2026-08-25 (E2E audit #3) the default on a live-Binance
+                // box is 'enforce' — the old 'off' default meant a fresh npx install
+                // flipped to live traded genuinely naked (no exchange stops AND the
+                // mandatory-stop gate skipped, since it is wired behind
+                // bracketsEnabled). An 'off' here can only be an explicit override.
                 const bracketMode = loadBracketMode();
                 if (bracketMode !== 'off') {
                     logger.info(TAG, `Bracket orders enabled in mode=${bracketMode}`);
                 }
+                else {
+                    logger.warn(TAG, `LIVE Binance with brackets.mode='off' (explicit config override) — NO exchange-side ` +
+                        `stops; positions rely on the software watcher alone and the mandatory-stop ` +
+                        `pre-trade gate is OFF. The dashboard readiness banner will show this red.`);
+                }
                 // User-data WebSocket stream flag — same mode-ladder pattern as brackets.
                 // Default 'off' keeps REST polling authoritative. Phase 1 ships dead-code;
                 // the flag flip to 'shadow' / 'observe' / 'enforce' is operator-driven.
@@ -2925,6 +2934,14 @@ const paperTradingPlugin = {
             venue,
             publicApi: hlPublicApi ?? binanceApi,
             toolCount: toolNames.length,
+            // 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.
+            resolveStopProtection: () => ({
+                tradingMode: runtime.mode,
+                venueEnforced: runtime.adapter.bracketsAlwaysEnforced === true,
+                bracketMode: loadBracketMode(),
+            }),
         });
         maybeStartConnectorSupervisor();
     },

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

@@ -1,4 +1,4 @@
-import { type ReadinessReport, type VenueId, type VenueReachabilityResult } from '@reefclaw/shared';
+import { type ReadinessCheck, type ReadinessReport, type VenueId, type VenueReachabilityResult } from '@reefclaw/shared';
 /** 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. */
@@ -11,6 +11,23 @@ export declare function attributeStall(stallMs: number, runqueueWaitMs: number |
 export interface VenueReachabilityProbe {
     probeReachability(): Promise<VenueReachabilityResult>;
 }
+/** Snapshot for the `live_stop_protection` check (E2E audit #3, 2026-08-25):
+ *  what — if anything — would stop a losing live position. Resolved per cycle
+ *  via a deferred closure over the runtime so it follows paper↔live flips and
+ *  adapter swaps without a restart. */
+export interface StopProtectionSnapshot {
+    /** 'PAPER' | 'SHADOW' | 'MICRO_LIVE' | 'LIVE' (runtime.mode). */
+    tradingMode: string;
+    /** Adapter declares venue-enforced brackets (Hyperliquid live). */
+    venueEnforced: boolean;
+    /** The effective Binance bracket mode ('off' | 'observe' | 'enforce'). */
+    bracketMode: string;
+}
+/** Map a snapshot to the readiness check. Pure — the whole point of the row is
+ *  that `fail` means REAL MONEY WITH NO STOP, so the mapping is unit-tested
+ *  branch by branch. Null snapshot → null (older wiring: omit the row rather
+ *  than fabricate a verdict). */
+export declare function stopProtectionCheck(snap: StopProtectionSnapshot | null, checkedAt: number): ReadinessCheck | null;
 /** Cross-cycle memory for the debounced rungs. Held by the interval loop and
  *  passed in explicitly so `collectReadiness` stays a pure function of its
  *  inputs — a module-global counter would leak between unit tests. */
@@ -31,6 +48,10 @@ export interface ReadinessReporterOptions {
     publicApi: VenueReachabilityProbe;
     /** Number of trading tools registered (a health signal). */
     toolCount: number;
+    /** 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. */
+    resolveStopProtection?: () => StopProtectionSnapshot | null;
     fetchImpl?: typeof fetch;
     intervalMs?: number;
     requestTimeoutMs?: number;
@@ -46,7 +67,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'>, bootWarmup?: boolean, deps?: {
+export declare function collectReadiness(opts: Pick<ReadinessReporterOptions, 'venue' | 'publicApi' | 'toolCount' | 'resolveStopProtection'>, 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

@@ -43,6 +43,45 @@ export function attributeStall(stallMs, runqueueWaitMs) {
     const hostThreshold = Math.max(HOST_WAIT_FLOOR_MS, stallMs * HOST_WAIT_SHARE_OF_STALL);
     return runqueueWaitMs >= hostThreshold ? 'host' : 'self';
 }
+/** Map a snapshot to the readiness check. Pure — the whole point of the row is
+ *  that `fail` means REAL MONEY WITH NO STOP, so the mapping is unit-tested
+ *  branch by branch. Null snapshot → null (older wiring: omit the row rather
+ *  than fabricate a verdict). */
+export function stopProtectionCheck(snap, checkedAt) {
+    if (!snap)
+        return null;
+    const live = snap.tradingMode === 'LIVE' || snap.tradingMode === 'MICRO_LIVE';
+    if (!live) {
+        return makeReadinessCheck('live_stop_protection', 'pass', {
+            detail: 'paper — software stop-watcher',
+            checkedAt,
+        });
+    }
+    if (snap.venueEnforced) {
+        return makeReadinessCheck('live_stop_protection', 'pass', {
+            detail: 'venue-enforced exchange brackets',
+            checkedAt,
+        });
+    }
+    if (snap.bracketMode === 'enforce') {
+        return makeReadinessCheck('live_stop_protection', 'pass', {
+            detail: 'exchange-native brackets (enforce)',
+            checkedAt,
+        });
+    }
+    if (snap.bracketMode === 'observe') {
+        return makeReadinessCheck('live_stop_protection', 'pass', {
+            detail: 'exchange brackets (observe) + software watcher',
+            checkedAt,
+        });
+    }
+    // LIVE with brackets off — with the live-enforce default this can only be an
+    // explicit operator override, and it must burn red on every surface.
+    return makeReadinessCheck('live_stop_protection', 'fail', {
+        detail: `brackets.mode='${snap.bracketMode}' on a ${snap.tradingMode} box`,
+        checkedAt,
+    });
+}
 export function createReadinessCycleState() {
     return { consecutiveReachFailures: 0 };
 }
@@ -84,6 +123,17 @@ export async function collectReadiness(opts, bootWarmup = false, deps = {}) {
         detail: `${opts.toolCount} tools`,
         checkedAt: now,
     }));
+    // live_stop_protection — a local config/adapter read, no network. Resolved
+    // per cycle so a paper→live flip surfaces on the next report without a
+    // restart. Resolver failure → omit the row (absent evidence stays absent).
+    try {
+        const stopCheck = stopProtectionCheck(opts.resolveStopProtection?.() ?? null, now);
+        if (stopCheck)
+            checks.push(stopCheck);
+    }
+    catch (err) {
+        logger.warn(TAG, `stop-protection snapshot failed (row omitted): ${formatError(err)}`);
+    }
     // ★ Probe FIRST, sample the loop delay AFTER. The freeze that makes a probe
     // abort happens *during* the probe, so sampling first would file the evidence
     // in the NEXT cycle's window — reachability would read 'stalled' this cycle
@@ -296,7 +346,12 @@ export function startReadinessReporter(opts) {
     const state = createReadinessCycleState();
     const cycle = async (bootWarmup) => {
         try {
-            const report = await collectReadiness({ venue: opts.venue, publicApi: opts.publicApi, toolCount: opts.toolCount }, bootWarmup, { state });
+            const report = await collectReadiness({
+                venue: opts.venue,
+                publicApi: opts.publicApi,
+                toolCount: opts.toolCount,
+                resolveStopProtection: opts.resolveStopProtection,
+            }, bootWarmup, { state });
             await postReadiness(opts.apiBaseUrl, opts.token, report, fetchImpl, timeoutMs);
             if (report.overall === 'fail') {
                 const failing = report.checks.filter((c) => c.status === 'fail').map((c) => c.id).join(', ');

package/assets/shared/readiness.d.ts

@@ -2,7 +2,7 @@ export type ReadinessStatus = 'pass' | 'warn' | 'fail' | 'unknown';
 /** Which lifecycle phase a check belongs to. `connect` runs with NO Binance API
  *  keys (covers paper trading too); `golive` needs keys (Phase 2). */
 export type ReadinessPhase = 'connect' | 'golive';
-export type ReadinessCheckId = 'binance_reachable' | 'hyperliquid_reachable' | 'clock_in_sync' | 'plugin_loaded' | 'tools_registered' | 'host_responsive';
+export type ReadinessCheckId = 'binance_reachable' | 'hyperliquid_reachable' | 'clock_in_sync' | 'plugin_loaded' | 'tools_registered' | 'host_responsive' | 'live_stop_protection';
 /** What a venue reachability probe concluded.
  *
  *  ★ `stalled` is the one that is NOT about the venue: it means the probe's own

package/assets/shared/readiness.js

@@ -68,6 +68,17 @@ export const READINESS_CHECK_COPY = {
         phase: 'connect',
         fixHint: 'The agent process froze for seconds at a time, so order handling, stop attachment and bracket resync can be delayed by that much. Two things cause this and we could not tell them apart on this host: the host being short of CPU/memory (other containers, agents or a leaking process competing for the box), or something inside the agent process blocking it — note the AI agent itself runs in this same process. Check host load first; if it is idle, the freeze came from inside.',
     },
+    // The safety-floor visibility row (2026-08-25, E2E audit #3): a live box
+    // whose stop protection is not armed used to be indistinguishable from a
+    // healthy one on every dashboard surface. `fail` here means REAL MONEY WITH
+    // NO STOP — the one readiness state that is never acceptable. Emitted with a
+    // detail naming the active protection (exchange brackets / venue-enforced /
+    // paper watcher) so a passing row is informative, not just green.
+    live_stop_protection: {
+        label: 'Live stop protection',
+        phase: 'connect',
+        fixHint: 'This agent is LIVE but exchange-side stop protection is OFF — positions have no stop-loss the exchange would honor if the agent host dies. This only happens when brackets.mode was explicitly set to "off" in the agent\'s plugin-config.json (live boxes default to enforce). Remove that override (or set brackets.mode to "enforce") and restart the agent.',
+    },
 };
 /** Assertive copy for a stall we COULD attribute, passed explicitly as the
  *  `fixHint` override — the same "only name a cause you measured" rule that

package/package.json

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