@reefclaw/openclaw-plugin 0.1.24 → 0.1.26

package/config/reentry-cooldown-config.js

@@ -0,0 +1,59 @@
+// Feature-flag readers for the re-entry cooldown gate (create_order).
+//
+// Mode default 'off' so the gate ships dead-code; the cooldown window default
+// (60 min) matches the 2026-09-02 measurement window that motivated the gate.
+// Mode resolution follows the exitGate pattern (config-service slice 2):
+//
+//     central (agent_config.gates.reentryCooldown via gate-store)
+//       → plugin-config.json reentryCooldown.mode
+//       → 'off'
+//
+// create_order reads the mode PER CALL, so a dashboard/API flip via
+// scripts/enable-reentry-cooldown.py hot-applies within one config poll —
+// no restart. Kill-switch RC_CENTRAL_GATES=off hands control back to the
+// local file. The minutes knob is LOCAL-only (mechanism tunable, not a
+// ladder) — central carries only the mode.
+import { readPluginConfig } from './plugin-config-io.js';
+import { gateStore } from './gate-store.js';
+const VALID_MODES = new Set([
+    'off',
+    'shadow',
+    'observe',
+    'enforce',
+]);
+export const DEFAULT_REENTRY_COOLDOWN_MINUTES = 60;
+const MIN_COOLDOWN_MINUTES = 5;
+const MAX_COOLDOWN_MINUTES = 1440;
+export function getReentryCooldownMode(config) {
+    const raw = config?.reentryCooldown?.mode;
+    if (typeof raw === 'string' && VALID_MODES.has(raw)) {
+        return raw;
+    }
+    return 'off';
+}
+export function loadReentryCooldownMode() {
+    const central = gateStore.getReentryCooldown();
+    if (central)
+        return central;
+    try {
+        return getReentryCooldownMode(readPluginConfig());
+    }
+    catch {
+        return 'off';
+    }
+}
+export function getReentryCooldownMinutes(config) {
+    const raw = config?.reentryCooldown?.minutes;
+    if (typeof raw === 'number' && Number.isFinite(raw)) {
+        return Math.max(MIN_COOLDOWN_MINUTES, Math.min(MAX_COOLDOWN_MINUTES, raw));
+    }
+    return DEFAULT_REENTRY_COOLDOWN_MINUTES;
+}
+export function loadReentryCooldownMinutes() {
+    try {
+        return getReentryCooldownMinutes(readPluginConfig());
+    }
+    catch {
+        return DEFAULT_REENTRY_COOLDOWN_MINUTES;
+    }
+}

package/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.
@@ -1418,6 +1427,11 @@ const paperTradingPlugin = {
                             // F26: same wiring object as the Binance arm — the SIGTERM
                             // drain covers both venues because it drains this client.
                             tradeIngest,
+                            // Journal close capture (close-bypass fix, HL arm): without
+                            // this, every bracket SL/TP fill leaked as status='open'
+                            // until the reconciler healed it reason-less (50% of wisekid
+                            // 30d closes were reconciler_observed_flat).
+                            autoCapture,
                         },
                     }
                     : {
@@ -2623,6 +2637,11 @@ const paperTradingPlugin = {
                     decisionsClient: positionDecisionsClient,
                     userId: positionDecisionsUserId,
                     reentryTracker,
+                    // WS2 directional scoreboard (docs/MARKET_ADAPTIVITY_PLAN.md §3):
+                    // tracked positions from the state store (no exchange round-trip)
+                    // + book resolved per call so a paper↔live flip follows.
+                    openPositions: () => positionStateStore.getAll().map((e) => ({ side: e.side })),
+                    book: () => (runtime.adapter.isLive ? 'live' : 'paper'),
                 })),
             },
             {
@@ -2920,6 +2939,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/ingest/position-auto-capture.js

@@ -19,7 +19,7 @@
 // that hooks into the WS-ingest pipeline (see POSITION_DECISION_JOURNAL_PLAN
 // §5.1 for the longer-term design).
 import { logger } from '../logger.js';
-import { isBracketCid } from '../live/bracket-id.js';
+import { isBracketClientId, parseBracketClientId } from '../live/bracket-id.js';
 import { normalizeBracketSymbol } from '../live/bracket-ledger.js';
 import { fillPriceFromOrder } from '../live/fill-price.js';
 import { getSkillVersionCached, withSkillVersion } from './skill-version-reader.js';
@@ -306,12 +306,27 @@ export async function onClosePositionFilled(ctx, inputs, order) {
     };
     ctx.decisionsClient.postClose(ctx.userId, close);
     // Re-entry indication (issue #204) — record the exit so scan_pairs can flag
-    // same-bar re-entries on this (symbol, setup).
+    // same-bar re-entries on this (symbol, setup), and so the reentryCooldown
+    // gate can see recent losses. Live agent-closes have no engine trade record
+    // here (exchange-exact PnL arrives later on the WS fill, racing this path),
+    // so the loss sign falls back to the agent's own r_multiple_at_close — the
+    // same validator-checked field the exit gate trusts. lossSource lets the
+    // shadow soak audit that sign against the DB before enforce.
+    const rRaw = inputs.closeAssessment?.['r_multiple_at_close'];
+    const rAtClose = typeof rRaw === 'number' && Number.isFinite(rRaw) ? rRaw : undefined;
     ctx.reentryTracker?.recordExit({
         symbol: inputs.symbol,
         setupType: stateEntry.setupType ?? paperTrade?.setupType,
         side: stateEntry.side,
-        wasLoss: paperTrade ? paperTrade.netRealizedPnl < 0 : undefined,
+        wasLoss: paperTrade
+            ? paperTrade.netRealizedPnl < 0
+            : rAtClose != null
+                ? rAtClose < 0
+                : undefined,
+        lossSource: paperTrade ? 'paper_engine' : rAtClose != null ? 'assessment_r' : undefined,
+        mode: ctx.resolveMode?.(),
+        realizedR: rAtClose,
+        realizedPnl: paperTrade?.netRealizedPnl,
         closedAtMs: closeAtMs,
     });
     // Drop local state — symbol can re-enter as a new position.
@@ -388,6 +403,7 @@ export async function onAutoFlattenClose(ctx, inputs, lookup = {
         symbol: inputs.symbol,
         setupType: flattenState?.setupType,
         side: flattenState?.side ?? 'long',
+        mode: ctx.resolveMode?.(),
         closedAtMs: inputs.observedAtMs ?? Date.now(),
     });
     ctx.stateStore.remove(inputs.symbol);
@@ -421,6 +437,9 @@ export async function onStopWatcherClose(ctx, inputs) {
         setupType: stateEntry?.setupType ?? paperTrade?.setupType,
         side: stateEntry?.side ?? 'long',
         wasLoss: paperTrade ? paperTrade.netRealizedPnl < 0 : undefined,
+        lossSource: paperTrade ? 'paper_engine' : undefined,
+        mode: ctx.resolveMode?.(),
+        realizedPnl: paperTrade?.netRealizedPnl,
         closedAtMs: closeAtMs,
     });
     const dropState = () => { ctx.stateStore?.remove(inputs.symbol); };
@@ -627,7 +646,13 @@ async function handleReduceOnlyExit(ctx, fill) {
     // onClosePositionFilled) or a manual/external close — both are handled by
     // their own paths (close_position's rich reason+assessment, or the reconciler
     // backstop). Closing here would clobber the agent's close reasoning, so defer.
-    const isBracket = fill.clientOrderId ? isBracketCid(fill.clientOrderId) : false;
+    // Recognition is VENUE-DISPATCHED (bracket-id rule): Binance `bkt…`/`rc-…`
+    // cids, Hyperliquid `0xbc7…` cloids — the Binance-only check silently
+    // classed every HL bracket fill as external and deferred it forever.
+    const cidVenue = ctx.venue ?? 'binance';
+    const isBracket = fill.clientOrderId
+        ? isBracketClientId(cidVenue, fill.clientOrderId)
+        : false;
     if (!isBracket) {
         logger.info(TAG, `${fill.symbol} flat via non-bracket reduce-only fill (cid=${fill.clientOrderId ?? 'none'}) — ` +
             `deferring close to close_position / reconciler backstop (no clobber)`);
@@ -643,6 +668,12 @@ async function handleReduceOnlyExit(ctx, fill) {
                 'Auto-journaled from the WS fill — no close_position call (close-bypass path).',
             observedFrom: 'ws_reduce_only_fill',
             clientOrderId: fill.clientOrderId,
+            // Which protective leg fired ('stop' | 'target'), parsed from the cid.
+            // Kept in the assessment (not a new close reason) so the close_reason
+            // vocabulary stays stable for the miner's plan-adherence classifier.
+            leg: fill.clientOrderId
+                ? parseBracketClientId(cidVenue, fill.clientOrderId)?.role
+                : undefined,
         },
         scorecardVerdict: 'NO_GO',
         confluenceScore: 0,
@@ -668,6 +699,9 @@ async function handleReduceOnlyExit(ctx, fill) {
         setupType: stateEntry.setupType,
         side: stateEntry.side,
         wasLoss: realizedPnl < 0,
+        lossSource: 'ws_fill',
+        mode: ctx.resolveMode?.(),
+        realizedPnl,
         closedAtMs: fill.exchangeTimeMs ?? Date.now(),
     });
     ctx.stateStore.remove(fill.symbol);
@@ -733,5 +767,16 @@ export function buildEntryPlanMetadata(md) {
             j.note = rr.note;
         out.realization_rule = j;
     }
+    // Cooldown-gate measurement tag (snake_case per the canonical JSONB key
+    // rule) — present only when the gate triggered and the entry fired anyway.
+    const rc = md.reentryCooldown;
+    if (rc) {
+        out.reentry_cooldown = {
+            mode: rc.mode,
+            minutes_since_loss: rc.minutesSinceLoss,
+            cooldown_minutes: rc.cooldownMinutes,
+            would_block: rc.wouldBlock,
+        };
+    }
     return Object.keys(out).length > 0 ? out : undefined;
 }

package/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/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/onboarding/runtime.js

@@ -63,6 +63,10 @@ export function buildAdapter(input) {
                 marketSlippagePct: readPluginConfig().hl?.marketSlippagePct,
                 microLive,
                 tradeIngest,
+                // Journal close capture (close-bypass fix) — same wiring the boot
+                // path passes; omitting it here would shed the capture on every
+                // reconnect-built adapter (the F9 class).
+                autoCapture: input.wiring?.autoCapture,
             },
         });
     }

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "reefclaw-paper-trading",
   "name": "ReefClaw Trading",
-  "version": "0.1.24",
+  "version": "0.1.26",
   "description": "Supervised trading plugin for the ReefClaw dashboard. It runs on YOUR machine and starts in PAPER mode with no API keys. It cannot trade real funds until you supply exchange credentials and step PAPER→MICRO_LIVE→LIVE yourself from the dashboard — the agent cannot make that change (the tool is refused without operator provenance). Exchange keys stay local, are used only to sign requests to the exchange, and are never transmitted to ReefClaw (asserted by a test in this package). Trading telemetry — positions, fills, decision journal — is sent to ReefClaw to render the dashboard. Every live position carries exchange-native protective stops. Remote updates to the agent's trading instructions are applied only after an Ed25519 signature is verified against a public key pinned in this build.",
   "author": "ReefClaw",
   "activation": {

package/package.json

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

package/portfolio/directional-scoreboard.d.ts

@@ -0,0 +1,17 @@
+import type { ReentryExitRecord } from './reentry-tracker.js';
+export interface ScoreboardInputs {
+    /** Tracked open positions on the current book (state store, not exchange). */
+    openPositions: Array<{
+        side: 'long' | 'short';
+    }>;
+    /** Tracker exit records, oldest first (as stored). */
+    exitRecords: readonly ReentryExitRecord[];
+    book: 'paper' | 'live';
+    /** e.g. "BTC 4h −2.4% (−2.3×ATR)" — from the leader fact's changeOfCharacter. */
+    tapeLine?: string;
+    /** How many recent closes to summarize. */
+    lastN?: number;
+}
+/** Build the scoreboard line, or undefined when there is nothing to show
+ *  (no open positions AND no recent closes on this book). */
+export declare function buildDirectionalScoreboard(inputs: ScoreboardInputs): string | undefined;

package/portfolio/directional-scoreboard.js

@@ -0,0 +1,71 @@
+// Directional scoreboard — WS2 of docs/MARKET_ADAPTIVITY_PLAN.md.
+//
+// One compact line of counter-evidence attached to the entry funnel
+// (scan_pairs): the book's current directional tilt, how the last N closes
+// per direction actually went, and what the market-leader tape did — the
+// three facts an anchored agent never sees together. Pure indication: it
+// never blocks or vetoes anything (that is the refuted-ledger's territory).
+//
+// Data sources are all local + free: the PositionStateStore (tracked open
+// positions — no exchange round-trip, so no HL address-budget cost) and the
+// ReentryTracker exit records (persisted; realizedR/realizedPnl where a
+// source had them). The tape line comes from the market leader's
+// change-of-character block on the intel facts the caller already fetched.
+const emptyStats = () => ({
+    wins: 0, losses: 0, unknown: 0, pnl: 0, pnlKnown: false, rSum: 0, rKnown: false,
+});
+function fmtDir(label, s) {
+    const n = s.wins + s.losses + s.unknown;
+    if (n === 0)
+        return undefined;
+    let out = `${label} ${s.wins}W/${s.losses}L${s.unknown > 0 ? `/${s.unknown}?` : ''}`;
+    if (s.rKnown)
+        out += ` ${s.rSum >= 0 ? '+' : ''}${Math.round(s.rSum * 100) / 100}R`;
+    else if (s.pnlKnown) {
+        const abs = Math.round(Math.abs(s.pnl) * 100) / 100;
+        out += ` ${s.pnl >= 0 ? '+' : '-'}$${abs}`;
+    }
+    return out;
+}
+/** Build the scoreboard line, or undefined when there is nothing to show
+ *  (no open positions AND no recent closes on this book). */
+export function buildDirectionalScoreboard(inputs) {
+    const lastN = inputs.lastN ?? 8;
+    const longs = inputs.openPositions.filter((p) => p.side === 'long').length;
+    const shorts = inputs.openPositions.filter((p) => p.side === 'short').length;
+    // Newest-first walk over this book's records (legacy untagged match either).
+    const recent = [];
+    for (let i = inputs.exitRecords.length - 1; i >= 0 && recent.length < lastN; i--) {
+        const r = inputs.exitRecords[i];
+        if (r.mode && r.mode !== inputs.book)
+            continue;
+        recent.push(r);
+    }
+    if (longs + shorts === 0 && recent.length === 0)
+        return undefined;
+    const stats = { long: emptyStats(), short: emptyStats() };
+    for (const r of recent) {
+        const s = stats[r.side];
+        if (r.wasLoss === true)
+            s.losses++;
+        else if (r.wasLoss === false)
+            s.wins++;
+        else
+            s.unknown++;
+        if (typeof r.realizedPnl === 'number' && Number.isFinite(r.realizedPnl)) {
+            s.pnl += r.realizedPnl;
+            s.pnlKnown = true;
+        }
+        if (typeof r.realizedR === 'number' && Number.isFinite(r.realizedR)) {
+            s.rSum += r.realizedR;
+            s.rKnown = true;
+        }
+    }
+    const parts = [`book: ${longs}L/${shorts}S open`];
+    const closeBits = [fmtDir('longs', stats.long), fmtDir('shorts', stats.short)].filter((v) => v !== undefined);
+    if (closeBits.length > 0)
+        parts.push(`last ${recent.length} closes: ${closeBits.join(', ')}`);
+    if (inputs.tapeLine)
+        parts.push(`tape: ${inputs.tapeLine}`);
+    return parts.join(' · ');
+}

package/portfolio/reentry-tracker.d.ts

@@ -4,8 +4,24 @@ export interface ReentryExitRecord {
     /** setup_type / strategy name from the entry metadata, when known. */
     setupType?: string;
     side: 'long' | 'short';
-    /** Whether the closed trade realized a loss (drives the stronger caution). */
+    /** Whether the closed trade realized a loss (drives the stronger caution
+     *  and arms the reentryCooldown gate). */
     wasLoss?: boolean;
+    /** Where the wasLoss sign came from, for auditing sign-accuracy before the
+     *  cooldown gate is promoted past shadow: engine-exact ('paper_engine',
+     *  'ws_fill') vs the agent's own close assessment ('assessment_r'). */
+    lossSource?: 'paper_engine' | 'assessment_r' | 'ws_fill';
+    /** Trading book at close time. The cooldown gate filters to the current
+     *  book so a paper loss can't cool down a live entry after a mode flip.
+     *  Legacy records (absent) match either book — they age out of any
+     *  realistic cooldown window within the hour anyway. */
+    mode?: 'paper' | 'live';
+    /** Realized R at close where a source had it (agent assessment on live
+     *  tool-closes). Feeds the WS2 directional scoreboard. */
+    realizedR?: number;
+    /** Realized net PnL (quote ccy) where engine/exchange-exact (paper engine,
+     *  WS bracket fills). Feeds the WS2 directional scoreboard. */
+    realizedPnl?: number;
     closedAtMs: number;
 }
 /** Signal-bar duration for a strategy/setup name. Name-suffix inference:
@@ -26,6 +42,27 @@ export declare class ReentryTracker {
     /** Most recent exit for (symbol[, setup]). A setup-specific record wins over
      *  a symbol-only match so multi-strategy books get precise cautions. */
     lastExit(symbol: string, setupType?: string): ReentryExitRecord | undefined;
+    /** Most recent LOSSY exit for `symbol` within `windowMs`, or undefined.
+     *  Feeds the reentryCooldown gate (evidence 2026-09-02: 58 re-entries within
+     *  60m of a same-symbol losing close ran −0.077R mean vs +0.090R baseline).
+     *  Any direction, any setup — the measured pathology is symbol churn, not
+     *  setup churn. `mode` filters to the current trading book; records without
+     *  a mode tag (pre-upgrade) match either book. */
+    lastLossyExit(symbol: string, windowMs: number, opts?: {
+        mode?: 'paper' | 'live';
+        nowMs?: number;
+    }): ReentryExitRecord | undefined;
+    /** Trailing consecutive LOSSY closes on `book`, newest first, across ALL
+     *  symbols — the live feed for the graduated loss-streak sizing brake in
+     *  preTradeRiskCheck (WS1, docs/MARKET_ADAPTIVITY_PLAN.md §3; live was fed a
+     *  hardcoded 0 since the beginning while paper computed it from engine
+     *  history). Semantics: a WIN breaks the streak, and so does an
+     *  UNKNOWN-outcome record (wasLoss undefined) — unknown is never counted as
+     *  a loss, and stopping there under-counts, which only makes the brake
+     *  gentler. Records from the OTHER book are skipped entirely (a paper loss
+     *  neither extends nor breaks a live streak); legacy untagged records match
+     *  either book, same as lastLossyExit. */
+    consecutiveLosses(book: 'paper' | 'live'): number;
     /** Structured caution when (symbol, strategy) was already traded within the
      *  current signal bar. Undefined = no caution. Pure indication (issue #204):
      *  the agent decides; nothing here blocks an order. */

package/portfolio/reentry-tracker.js

@@ -98,6 +98,55 @@ export class ReentryTracker {
         }
         return bySetup ?? bySymbol;
     }
+    /** Most recent LOSSY exit for `symbol` within `windowMs`, or undefined.
+     *  Feeds the reentryCooldown gate (evidence 2026-09-02: 58 re-entries within
+     *  60m of a same-symbol losing close ran −0.077R mean vs +0.090R baseline).
+     *  Any direction, any setup — the measured pathology is symbol churn, not
+     *  setup churn. `mode` filters to the current trading book; records without
+     *  a mode tag (pre-upgrade) match either book. */
+    lastLossyExit(symbol, windowMs, opts) {
+        const key = normalizeBracketSymbol(symbol);
+        const now = opts?.nowMs ?? Date.now();
+        for (let i = this.records.length - 1; i >= 0; i--) {
+            const r = this.records[i];
+            if (r.symbol !== key)
+                continue;
+            if (r.wasLoss !== true)
+                continue;
+            if (opts?.mode && r.mode && r.mode !== opts.mode)
+                continue;
+            const ageMs = now - r.closedAtMs;
+            // Tolerate small clock skew on exchange timestamps (up to 60s in the
+            // future still counts as "just closed").
+            if (ageMs >= -60_000 && ageMs <= windowMs)
+                return r;
+        }
+        return undefined;
+    }
+    /** Trailing consecutive LOSSY closes on `book`, newest first, across ALL
+     *  symbols — the live feed for the graduated loss-streak sizing brake in
+     *  preTradeRiskCheck (WS1, docs/MARKET_ADAPTIVITY_PLAN.md §3; live was fed a
+     *  hardcoded 0 since the beginning while paper computed it from engine
+     *  history). Semantics: a WIN breaks the streak, and so does an
+     *  UNKNOWN-outcome record (wasLoss undefined) — unknown is never counted as
+     *  a loss, and stopping there under-counts, which only makes the brake
+     *  gentler. Records from the OTHER book are skipped entirely (a paper loss
+     *  neither extends nor breaks a live streak); legacy untagged records match
+     *  either book, same as lastLossyExit. */
+    consecutiveLosses(book) {
+        let n = 0;
+        for (let i = this.records.length - 1; i >= 0; i--) {
+            const r = this.records[i];
+            if (r.mode && r.mode !== book)
+                continue;
+            if (r.wasLoss === true) {
+                n++;
+                continue;
+            }
+            break; // win or unknown outcome ends the trailing streak
+        }
+        return n;
+    }
     /** Structured caution when (symbol, strategy) was already traded within the
      *  current signal bar. Undefined = no caution. Pure indication (issue #204):
      *  the agent decides; nothing here blocks an order. */

package/signals/change-of-character.d.ts

@@ -0,0 +1,38 @@
+/** 30m move ≥ this ×ATR(1h) ⇒ 'shock'. */
+export declare const SHOCK_ATR_MULT_30M = 2;
+/** 4h tape opposing a directional regime label by ≥ this ×ATR(1h) ⇒ 'regime_tape_disagreement'. */
+export declare const DISAGREEMENT_ATR_MULT_4H = 2;
+export type ChangeOfCharacterFlag = 'shock' | 'regime_tape_disagreement';
+export interface ChangeOfCharacter {
+    /** |price now − close ~30m ago| ÷ ATR(1h). */
+    shock30mAtr: number;
+    /** (max high − min low) over the last ~30m ÷ ATR(1h) — catches a spike-and-revert the close-to-close move misses. */
+    range30mAtr: number;
+    /** % return vs the close ~1h ago. */
+    return1hPct: number;
+    /** % return vs the close ~4h ago. */
+    return4hPct: number;
+    /** Signed (price now − close ~4h ago) ÷ ATR(1h) — the tape the regime label must answer to. */
+    tape4hAtr: number;
+    /** ATR(1h) as % of price — the volatility yardstick the multiples are in. */
+    atrPct: number;
+    flags: ChangeOfCharacterFlag[];
+    /** Agent-facing one-liner. Present ONLY when a flag fired — silence stays silent. */
+    summary?: string;
+}
+interface BarLike {
+    high: number;
+    low: number;
+    close: number;
+}
+export interface ChangeOfCharacterInputs {
+    /** 5m bars, oldest first (≥7 required). */
+    ohlcv5m: BarLike[];
+    /** 1h bars, oldest first (≥5 required). */
+    ohlcv1h: BarLike[];
+    atr14: number;
+    currentPrice: number;
+    regime: string;
+}
+export declare function computeChangeOfCharacter(inputs: ChangeOfCharacterInputs): ChangeOfCharacter | undefined;
+export {};