@reefclaw/openclaw-plugin 0.1.0

package/tools/create-order.js

@@ -0,0 +1,338 @@
+// Tool: create_order — order execution with real price data + pre-trade risk gate
+// Readiness gate: BLOCKED unless adapter.readiness === 'READY'.
+import { formatError } from '../logger.js';
+import { getQuoteBalance, getQuoteWalletBalance } from '../balance-utils.js';
+import { fetchCurrentPrice, fetchOrderBook, isError } from './helpers.js';
+import { validateCreateOrder, sanitizeRealizationRule } from './assessment-validation.js';
+import { preTradeRiskCheck, getDefaultPreTradeLimits, computeConsecutiveLosses } from '../risk/pre-trade-check.js';
+import { bracketsEnabled, loadBracketMode, loadBracketRequirements } from '../config/brackets-config.js';
+import { onCreateOrderFilled } from '../ingest/position-auto-capture.js';
+/** Build a PortfolioSnapshot from current simulator state (paper mode). */
+function buildPortfolioSnapshotFromSimulator(simulator) {
+    const state = simulator.getState();
+    const quoteCurrency = state.config.quoteCurrency;
+    const walletBal = state.wallet[quoteCurrency];
+    return {
+        positions: state.positions.map(p => {
+            const ticker = simulator.getLastTicker(p.symbol);
+            return {
+                symbol: p.symbol,
+                side: p.side,
+                quantity: p.quantity,
+                entryPrice: p.entryPrice,
+                markPrice: ticker?.last ?? p.entryPrice,
+            };
+        }),
+        walletTotal: walletBal?.total ?? 0,
+        walletAvailable: walletBal?.available ?? 0,
+        sessionStartNav: simulator.getSessionStartNav(),
+        equity: simulator.computeEquity(),
+        isLive: false,
+    };
+}
+/** Build a PortfolioSnapshot from adapter (live mode). */
+async function buildPortfolioSnapshotFromAdapter(adapter) {
+    const [balance, positions] = await Promise.all([
+        adapter.getBalance(),
+        adapter.getPositionsOrNull(),
+    ]);
+    // null = positions fetch FAILED (429 / weight-paced / transient). If we
+    // collapsed that to [], existing open positions become invisible to the
+    // pre-trade risk check below — gross exposure / max-open-positions / net
+    // tilt would all be under-counted and a trade that should be blocked could
+    // pass. Refuse to size off a phantom-flat account; abort so the agent
+    // retries next heartbeat. Same null≠empty contract as the close/flatten path.
+    if (positions === null) {
+        throw new Error('Cannot build portfolio snapshot — position fetch failed (exchange data ' +
+            'unavailable, likely Binance 429 or transient). Order NOT placed; retry next heartbeat.');
+    }
+    const walletTotal = getQuoteWalletBalance(balance);
+    // Use the session-start NAV captured once at initialization, not the current balance.
+    // If not available (shouldn't happen after init), fall back to current balance.
+    const sessionNav = adapter.getSessionStartNav?.() ?? walletTotal;
+    // Live Binance wallet already includes margin; equity = wallet + unrealized P&L.
+    let liveEquity = walletTotal;
+    for (const p of positions) {
+        const mark = p.markPrice ?? p.entryPrice;
+        const pnl = p.side === 'long'
+            ? (mark - p.entryPrice) * p.contracts
+            : (p.entryPrice - mark) * p.contracts;
+        liveEquity += pnl;
+    }
+    return {
+        positions: positions.map(p => ({
+            symbol: p.symbol,
+            side: p.side,
+            quantity: p.contracts,
+            entryPrice: p.entryPrice,
+            markPrice: p.markPrice,
+        })),
+        walletTotal,
+        walletAvailable: getQuoteBalance(balance.free),
+        sessionStartNav: sessionNav,
+        equity: liveEquity,
+        isLive: true,
+    };
+}
+export async function createOrderTool(args, deps) {
+    // ---- Readiness gate (live mode only) ----
+    if (deps.adapter.readiness !== 'READY') {
+        return { error: `Trading blocked: adapter is ${deps.adapter.readiness}. Wait for initialization to complete.` };
+    }
+    // ---- Assessment-schema gate (SKILL.md v2.10.0 — live mode only) ----
+    // In live mode the agent must include thesis + setup_type + regime +
+    // regime_confidence + scorecard_verdict + confluence_score.  This is the
+    // same data the heartbeat reassessment uses to detect scorecard reversal /
+    // regime flip — if the agent can't produce it at entry, it can't produce
+    // it mid-trade either.
+    const gateCheck = validateCreateOrder(args, deps.adapter.isLive);
+    if (!gateCheck.ok) {
+        return { error: gateCheck.error ?? 'Invalid create_order arguments.' };
+    }
+    // Validate side
+    const side = args.side.toLowerCase();
+    if (side !== 'buy' && side !== 'sell') {
+        return { error: `Invalid side: ${args.side}. Must be 'buy' or 'sell'.` };
+    }
+    // Validate type
+    const type = args.type.toLowerCase();
+    if (type !== 'market' && type !== 'limit') {
+        return { error: `Invalid type: ${args.type}. Must be 'market' or 'limit'.` };
+    }
+    // Validate amount
+    if (!args.amount || args.amount <= 0) {
+        return { error: 'Amount must be a positive number.' };
+    }
+    // Validate price for limit orders
+    if (type === 'limit' && (!args.price || args.price <= 0)) {
+        return { error: 'Limit orders require a positive price.' };
+    }
+    // In paper mode, fetch latest ticker + order book for realistic fills
+    let ticker = null;
+    if (!deps.adapter.isLive) {
+        const paperDeps = { binanceApi: deps.binanceApi, simulator: deps.adapter.getSimulator() };
+        const [priceResult] = await Promise.all([
+            fetchCurrentPrice(args.symbol, paperDeps),
+            fetchOrderBook(args.symbol, paperDeps),
+        ]);
+        if (isError(priceResult))
+            return priceResult;
+        ticker = priceResult;
+    }
+    else {
+        // Live mode: fetch ticker for risk check reference price
+        const lastPrice = await deps.adapter.getLastPrice(args.symbol);
+        if (lastPrice != null) {
+            ticker = {
+                symbol: args.symbol, last: lastPrice,
+                bid: lastPrice, ask: lastPrice, baseVolume: 0, quoteVolume: 0,
+                change: 0, percentage: 0, timestamp: Date.now(), datetime: new Date().toISOString(),
+            };
+        }
+    }
+    if (!ticker) {
+        return { error: `Failed to fetch current price for ${args.symbol}` };
+    }
+    // ---- Pre-trade risk gate ----
+    const orderPrice = type === 'limit' ? args.price : ticker.last;
+    const proposed = {
+        symbol: args.symbol,
+        side: side,
+        type: type,
+        amount: args.amount,
+        price: orderPrice,
+        stopPrice: args.stopPrice,
+        targetPrice: args.target_price,
+    };
+    // Build portfolio snapshot based on mode
+    let portfolio;
+    let consecutiveLosses = 0;
+    if (!deps.adapter.isLive) {
+        const simulator = deps.adapter.getSimulator();
+        portfolio = buildPortfolioSnapshotFromSimulator(simulator);
+        consecutiveLosses = computeConsecutiveLosses(simulator.getState().tradeHistory);
+    }
+    else {
+        portfolio = await buildPortfolioSnapshotFromAdapter(deps.adapter);
+        // In live mode, consecutive losses would come from intelligence DB — use 0 for now
+    }
+    // Bracket enforcement only applies in live mode when the feature is enabled.
+    // Paper mode uses the stop-watcher and doesn't care about these flags.
+    let bracketEnforcement;
+    if (deps.adapter.isLive && bracketsEnabled(loadBracketMode())) {
+        bracketEnforcement = loadBracketRequirements();
+    }
+    const riskCheck = preTradeRiskCheck(proposed, portfolio, getDefaultPreTradeLimits(), {
+        volFactor: !deps.adapter.isLive ? deps.adapter.getSimulator().getVolFactor() : 1.0,
+        consecutiveLosses,
+        bracketEnforcement,
+    });
+    if (!riskCheck.allowed) {
+        const reasons = riskCheck.violations.map(v => v.message).join('; ');
+        return {
+            error: `Order REJECTED by risk gate [${riskCheck.drawdownZone} zone]: ${reasons}`,
+        };
+    }
+    // Build position metadata from optional args (only if any metadata provided)
+    // Sanitize numeric metadata — reject non-finite values, clamp ranges
+    const num = (v) => typeof v === 'number' && Number.isFinite(v) ? v : undefined;
+    const clamp = (v, min, max) => {
+        const n = num(v);
+        return n != null ? Math.max(min, Math.min(max, n)) : undefined;
+    };
+    const hasMetadata = args.setup_type || args.thesis || args.target_price != null
+        || args.regime || args.scorecard_verdict || args.confluence_score != null
+        || args.invalidation_price != null || args.realization_rule != null;
+    const metadata = hasMetadata ? {
+        setupType: args.setup_type,
+        thesis: args.thesis?.slice(0, 500), // Cap length
+        stopPrice: num(args.stopPrice),
+        targetPrice: num(args.target_price),
+        regime: args.regime,
+        regimeConfidence: clamp(args.regime_confidence, 0, 100),
+        scorecardVerdict: args.scorecard_verdict,
+        confluenceScore: clamp(args.confluence_score, 0, 10),
+        invalidationPrice: num(args.invalidation_price),
+        realizationRule: sanitizeRealizationRule(args.realization_rule),
+    } : undefined;
+    // ---- Approval-mode branches ----
+    // Both shadow and per_trade need full v2.10.0 metadata so the proposal is
+    // operator-meaningful. Metadata is the agent's responsibility; ingest creds
+    // are the operator's. Separate so the error messages can be precise.
+    const argsMetadataComplete = !!(args.thesis &&
+        args.setup_type &&
+        args.target_price != null &&
+        args.stopPrice != null &&
+        args.regime &&
+        typeof args.regime_confidence === 'number' &&
+        args.scorecard_verdict &&
+        typeof args.confluence_score === 'number');
+    const proposalPathWired = !!(deps.proposalManager && deps.userId);
+    const approvalMode = deps.approvalMode ?? 'off';
+    // per_trade mode: propose and EARLY-RETURN. The agent's call doesn't fire;
+    // the operator approves and ProposalDecisionListener fires via this same
+    // tool with proposalManager omitted (which takes the real path below).
+    //
+    // If proposalManager isn't wired (operator set approval.mode=per_trade in
+    // config but ingest creds aren't present), we fall through to the normal
+    // fire path — the startup warning is the operator's signal. We never trap
+    // the agent inside an unfireable per_trade branch.
+    if (approvalMode === 'per_trade' && proposalPathWired) {
+        if (!argsMetadataComplete) {
+            return {
+                error: 'approval.mode=per_trade requires the full v2.10.0 metadata block on every create_order: ' +
+                    'thesis, setup_type, target_price, stopPrice, regime, regime_confidence, ' +
+                    'scorecard_verdict, confluence_score. The operator approves on this metadata.',
+            };
+        }
+        try {
+            const result = deps.proposalManager.propose(deps.userId, {
+                symbol: args.symbol,
+                side: side,
+                orderType: type,
+                size: args.amount,
+                proposedEntry: orderPrice,
+                stopPrice: args.stopPrice,
+                targetPrice: args.target_price,
+                riskUsd: Math.abs(orderPrice - args.stopPrice) * args.amount,
+                thesis: args.thesis,
+                setupType: args.setup_type,
+                regime: args.regime,
+                regimeConfidence: args.regime_confidence,
+                scorecardVerdict: args.scorecard_verdict,
+                confluenceScore: args.confluence_score,
+                ...(args.supersedes_id ? { supersedesId: args.supersedes_id } : {}),
+                // Real, operator-actionable. Default would also resolve to 'real' but
+                // we set it explicitly so the intent reads at the call site.
+                origin: 'real',
+            });
+            return {
+                status: 'pending_approval',
+                proposal_id: result.proposalUuid,
+                hard_expires_at: result.hardExpiresAt.toISOString(),
+                setup_bucket: result.setupBucket,
+                message: `Order awaits operator approval (${result.setupBucket} bucket, expires ` +
+                    `${result.hardExpiresAt.toISOString()}). Do not call create_order again ` +
+                    `for this setup; the listener will fire on approval. If the operator ` +
+                    `requests modifications in chat, call create_order with supersedes_id=` +
+                    `<id from the chat-context header>.`,
+            };
+        }
+        catch (err) {
+            return { error: `Proposal submission failed: ${formatError(err)}` };
+        }
+    }
+    // shadow mode: dual-write a telemetry proposal AND continue to the real
+    // fire below. Never blocks the hot path on a propose() failure.
+    if (approvalMode === 'shadow' && proposalPathWired && argsMetadataComplete) {
+        try {
+            deps.proposalManager.propose(deps.userId, {
+                symbol: args.symbol,
+                side: side,
+                orderType: type,
+                size: args.amount,
+                proposedEntry: orderPrice,
+                stopPrice: args.stopPrice,
+                targetPrice: args.target_price,
+                riskUsd: Math.abs(orderPrice - args.stopPrice) * args.amount,
+                thesis: args.thesis,
+                setupType: args.setup_type,
+                regime: args.regime,
+                regimeConfidence: args.regime_confidence,
+                scorecardVerdict: args.scorecard_verdict,
+                confluenceScore: args.confluence_score,
+                ...(args.supersedes_id ? { supersedesId: args.supersedes_id } : {}),
+                // Phase A telemetry — agent's create_order ALSO fires the real order
+                // synchronously below. Hidden from operator UI by origin='shadow'.
+                origin: 'shadow',
+            });
+        }
+        catch (err) {
+            // eslint-disable-next-line no-console
+            console.warn(`[approval-shadow] propose() threw: ${formatError(err)}`);
+        }
+    }
+    try {
+        const order = await deps.adapter.createOrder(args.symbol, side, type, args.amount, args.price, metadata);
+        // Auto-capture entry to the Position Decision Journal — fail-open, never
+        // block the trading hot path on a webapp ingest blip.
+        if (deps.autoCapture) {
+            // ALWAYS stash the metadata first (fixed 2026-07-05). Binance futures
+            // market orders routinely come back filled>0 but with NO average price
+            // in the immediate REST response — the synchronous capture below then
+            // bails ("missing fill price; skipping capture") and, before this fix,
+            // the metadata was dropped on the floor because the stash only ran in
+            // the not-filled branch. The WS-driven onWsFillObserved captured those
+            // entries seconds later with metadata=none → the live journal filled
+            // with '(no thesis recorded)' / setup_type='unknown' rows (majority of
+            // 2026-07 live entries) even though the agent supplied full v2.10.0
+            // metadata every time. When the synchronous capture DOES succeed, the
+            // WS dedup (openedFromExchangeTradeId === orderId) skips the duplicate
+            // and the unused stash entry simply expires (24h TTL, pruned).
+            if (metadata &&
+                deps.autoCapture.pendingEntries &&
+                typeof order.id === 'string' &&
+                order.id.length > 0) {
+                deps.autoCapture.pendingEntries.put({
+                    orderId: order.id,
+                    symbol: args.symbol,
+                    side: side,
+                    metadata,
+                });
+            }
+            const filledNow = typeof order.filled === 'number' && order.filled > 0;
+            if (filledNow) {
+                // Order filled at submit (market, or limit-that-crossed). Capture
+                // synchronously — same as the original PR1 path.
+                onCreateOrderFilled(deps.autoCapture, { symbol: args.symbol, side: side, metadata }, order).catch((err) => {
+                    // eslint-disable-next-line no-console
+                    console.warn(`[position-auto-capture] entry capture threw: ${formatError(err)}`);
+                });
+            }
+        }
+        return order;
+    }
+    catch (err) {
+        return { error: formatError(err) };
+    }
+}

package/tools/exit-gate.d.ts

@@ -0,0 +1,58 @@
+export type ExitGateMode = 'off' | 'shadow' | 'observe' | 'enforce';
+export type ThesisStatusForGate = 'intact' | 'weakening' | 'invalidated' | 'evolving';
+export type ReviewVerdictForGate = 'hold' | 'add_on' | 'close_recommended';
+export interface ExitGateInputs {
+    /** The close_position reason the agent supplied. `operator_command` always
+     *  passes; the other five reasons go through tier evaluation. */
+    reason: 'regime_flip' | 'scorecard_reversal' | 'risk_limit' | 'bracket_integrity' | 'operator_command';
+    /** Max favorable excursion in R-multiples ever reached on this position.
+     *  Undefined => gate skips (PASS with code 'inputs_unavailable_mfe'). */
+    mfe_r_peak?: number;
+    /** Current R-multiple at the close price. Undefined => gate skips. */
+    current_r?: number;
+    /** Telemetry only (0a/0b) — provenance of the mfe_r_peak / current_r values
+     *  above. Ignored by evaluateExitGate; set by buildExitGateInputs and
+     *  persisted in gate_eval.inputs so the inputs_unavailable_* and
+     *  computed-fallback paths are diagnosable from the journal. */
+    mfe_src?: 'assessment' | 'pos.mfeR' | 'computed_floor';
+    current_r_src?: 'assessment' | 'computed';
+    /** Implied or explicit vol-shock flag from the caller. The caller computes
+     *  this from recent ATR vs latest adverse 5m bar. Default false. */
+    volShock?: boolean;
+    /** Position side — needed for the T2a stop-trail check (long stop ≥ entry,
+     *  short stop ≤ entry). */
+    side?: 'long' | 'short';
+    /** Current bracket stop price. Undefined => T2a check is skipped (PASS with
+     *  code 't2a_skipped_no_stop_known' rather than block). */
+    stopPrice?: number;
+    /** Entry price for the position. Used as the BE level in T2a. */
+    entryPrice?: number;
+    /** Most recent record_position_reviews entry for this position. Drives the
+     *  contradicts-own-review block and the review-override pass. */
+    lastReview?: {
+        verdict: ReviewVerdictForGate;
+        thesis_status: ThesisStatusForGate;
+        review_at_ms: number;
+    };
+    /** Current time in ms — explicit for testability. */
+    now_ms: number;
+}
+export type GateOutcome = 'PASS' | 'BLOCK';
+export interface GateVerdict {
+    outcome: GateOutcome;
+    /** Tier classification: T1 / T2a / T2b / override / skipped. */
+    tier: 'T1' | 'T2a' | 'T2b' | 'override' | 'skipped';
+    /** Stable code identifying the specific predicate that fired.
+     *  e.g. 't1_premature_exit', 't2a_stop_not_trailed_to_BE',
+     *  'operator_command', 'vol_shock', 'contradicts_own_recent_hold_verdict'. */
+    code: string;
+    /** Optional recovery hint for BLOCK outcomes — surfaced back to the agent
+     *  via the tool error so it can self-correct mid-turn. */
+    recovery_hint?: string;
+    /** Optional discipline-failure flag, currently only set on T2b passes so
+     *  we capture "winner peaked, reversed, no stop-trail done". */
+    discipline_failure?: string;
+}
+/** Evaluate the exit gate against the supplied inputs. Pure; safe to call
+ *  from anywhere. See module header for semantics. */
+export declare function evaluateExitGate(inputs: ExitGateInputs): GateVerdict;

package/tools/exit-gate.js

@@ -0,0 +1,162 @@
+// Exit gate — prevents the agent from closing positions before they've
+// meaningfully developed, while preserving override paths for genuine adverse
+// signals. See docs/EXIT_GATE_DESIGN.md for the full spec and §3 for the
+// tier table this function implements.
+//
+// Pure function — caller supplies all inputs, including the mode flag, and the
+// function returns a structured verdict. Caller (close-position.ts) is
+// responsible for actually blocking, soft-warning, or logging based on mode.
+//
+// Design contract:
+//   - In `off` mode the gate is never called at all (don't pay the input
+//     computation cost).
+//   - In `shadow` / `observe` / `enforce` the gate runs; the caller decides
+//     what to do with BLOCK verdicts.
+//   - If inputs are partial (e.g., MFE not supplied), the gate returns
+//     PASS('inputs_unavailable') — never BLOCK on missing data. The shadow
+//     soak surfaces these so we can fix plumbing before enforce.
+//   - The "contradicts-own-review" rule applies pre-tier (blocks T2b too).
+//     See §8 R4 in the design doc — this is the conservative default; we
+//     watch shadow telemetry and demote to T1-only if it blocks legit exits.
+/** Window during which a hold-verdict review blocks a contradicting close. */
+const CONTRADICTS_OWN_REVIEW_WINDOW_MS = 5 * 60 * 1000;
+/** Developed-position threshold in R-multiples. */
+const DEVELOPED_MFE_R = 0.5;
+/** T1 escape threshold — position deteriorating fast. */
+const T1_ESCAPE_CURRENT_R = -0.5;
+/** 0c — floor for the 'weakening' review override. The t1_review_override pass
+ *  was the dominant exit (~42% of agent closes) and, by construction, every one
+ *  is a T1-premature position — the exact population the gate exists to BLOCK.
+ *  It was fully agent-self-served: file verdict='close_recommended' +
+ *  thesis_status='weakening' and the block lifted with zero objective
+ *  corroboration. We now split by strength of claim: 'invalidated' (a strong,
+ *  falsifiable thesis break — regime flip / level broken) keeps the FULL
+ *  override even at breakeven; 'weakening' (a soft, abuse-prone signal) only
+ *  overrides once price has ALSO moved adversely to at least this floor.
+ *  ⚠ This threshold is a value to SOAK in shadow (compare would_have_blocked vs
+ *  which positions later hit TP), NOT a derived optimum — tightening reclassifies
+ *  a large population. See docs/EXIT_DISCIPLINE_BUILD_PLAN.md Step 0c. */
+const T1_WEAKENING_OVERRIDE_FLOOR_R = -0.25;
+/** Evaluate the exit gate against the supplied inputs. Pure; safe to call
+ *  from anywhere. See module header for semantics. */
+export function evaluateExitGate(inputs) {
+    // 0. Always-allow overrides — checked first, before any input-availability
+    //    checks, so the operator can ALWAYS get out.
+    if (inputs.reason === 'operator_command') {
+        return { outcome: 'PASS', tier: 'override', code: 'operator_command' };
+    }
+    if (inputs.volShock === true) {
+        return { outcome: 'PASS', tier: 'override', code: 'vol_shock' };
+    }
+    // 1. Contradicts-own-review block — pre-tier.
+    //    The "intact + hold → close" pattern from the May 12 analysis. If the
+    //    agent's last review said hold AND was recent, refuse to immediately
+    //    contradict it. Operator command (above) is the only override.
+    const lr = inputs.lastReview;
+    if (lr && lr.verdict === 'hold') {
+        const age = inputs.now_ms - lr.review_at_ms;
+        if (age < CONTRADICTS_OWN_REVIEW_WINDOW_MS && age >= 0) {
+            return {
+                outcome: 'BLOCK',
+                tier: 'override',
+                code: 'contradicts_own_recent_hold_verdict',
+                recovery_hint: `Last record_position_reviews filed verdict='hold' ${Math.round(age / 1000)}s ago. ` +
+                    `If conditions have genuinely changed, file a fresh review with verdict='close_recommended' first. ` +
+                    `Operator can override via reason='operator_command'.`,
+            };
+        }
+    }
+    // 2. Input availability — we need mfe_r_peak + current_r to do tier work.
+    //    Missing => PASS with a skip code so shadow telemetry can surface the
+    //    plumbing gap.
+    if (typeof inputs.mfe_r_peak !== 'number' || !Number.isFinite(inputs.mfe_r_peak)) {
+        return { outcome: 'PASS', tier: 'skipped', code: 'inputs_unavailable_mfe' };
+    }
+    if (typeof inputs.current_r !== 'number' || !Number.isFinite(inputs.current_r)) {
+        return { outcome: 'PASS', tier: 'skipped', code: 'inputs_unavailable_current_r' };
+    }
+    // 3. Review override — well-formed close_recommended on a genuine adverse
+    //    signal. 0c split (see T1_WEAKENING_OVERRIDE_FLOOR_R): 'invalidated' (a
+    //    strong, falsifiable break) overrides outright; 'weakening' (soft, the
+    //    scratch-laundering vector) overrides ONLY with price confirmation
+    //    (current_r ≤ the floor). inputs.current_r is guaranteed finite here
+    //    (checked in step 2 above).
+    const reviewOverride = !!lr &&
+        lr.verdict === 'close_recommended' &&
+        (lr.thesis_status === 'invalidated' ||
+            (lr.thesis_status === 'weakening' && inputs.current_r <= T1_WEAKENING_OVERRIDE_FLOOR_R));
+    // 4. Tier classification.
+    const developed = inputs.mfe_r_peak >= DEVELOPED_MFE_R;
+    if (!developed) {
+        // ── Tier 1: never developed (mfe_r_peak < 0.5) ──
+        if (inputs.current_r <= T1_ESCAPE_CURRENT_R) {
+            return {
+                outcome: 'PASS',
+                tier: 'T1',
+                code: 't1_escape_deteriorating',
+            };
+        }
+        if (reviewOverride) {
+            return {
+                outcome: 'PASS',
+                tier: 'T1',
+                code: 't1_review_override',
+            };
+        }
+        return {
+            outcome: 'BLOCK',
+            tier: 'T1',
+            code: 't1_premature_exit',
+            recovery_hint: `Position has not developed (mfe_r_peak=${inputs.mfe_r_peak.toFixed(2)}R < 0.5R) and is not deteriorating ` +
+                `(current_r=${inputs.current_r.toFixed(2)}R > -0.5R). ` +
+                `Let the bracket be the exit. Override paths: ` +
+                `(a) file verdict='close_recommended' with thesis_status='invalidated' — a real, falsifiable ` +
+                `thesis break (regime flip, key level broken), not a soft read; ` +
+                `(b) thesis_status='weakening' overrides ONLY once current_r ≤ -0.25R (soft signals need price confirmation); ` +
+                `(c) wait for current_r ≤ -0.5R; (d) operator_command.`,
+        };
+    }
+    // ── Tier 2: developed (mfe_r_peak ≥ 0.5) ──
+    if (inputs.current_r >= 0) {
+        // T2a — in profit. Require stop has been trailed to BE-or-better.
+        // Need side + stopPrice + entryPrice to check; if any missing, pass with
+        // a skip code so shadow telemetry surfaces it.
+        if (!inputs.side ||
+            typeof inputs.stopPrice !== 'number' ||
+            !Number.isFinite(inputs.stopPrice) ||
+            typeof inputs.entryPrice !== 'number' ||
+            !Number.isFinite(inputs.entryPrice)) {
+            return {
+                outcome: 'PASS',
+                tier: 'T2a',
+                code: 't2a_skipped_no_stop_known',
+            };
+        }
+        const stopAtBE = inputs.side === 'long' ? inputs.stopPrice >= inputs.entryPrice : inputs.stopPrice <= inputs.entryPrice;
+        if (!stopAtBE) {
+            return {
+                outcome: 'BLOCK',
+                tier: 'T2a',
+                code: 't2a_stop_not_trailed_to_BE',
+                recovery_hint: `Position developed to mfe_r_peak=${inputs.mfe_r_peak.toFixed(2)}R and is currently in profit ` +
+                    `(current_r=${inputs.current_r.toFixed(2)}R), but stop is still at original level ` +
+                    `(stop=${inputs.stopPrice}, entry=${inputs.entryPrice}). ` +
+                    `Call modify_stop to move stop to ${inputs.entryPrice} (break-even) or better before closing. ` +
+                    `This locks in profit and is the v2.10.0 winner-protection rule.`,
+            };
+        }
+        return {
+            outcome: 'PASS',
+            tier: 'T2a',
+            code: 't2a_developed_in_profit_stop_trailed',
+        };
+    }
+    // T2b — developed, now in red. Horse has bolted; allow the exit but flag
+    // as discipline failure so we can study these later.
+    return {
+        outcome: 'PASS',
+        tier: 'T2b',
+        code: 't2b_developed_reversed',
+        discipline_failure: 'unmanaged_winner_reversed',
+    };
+}

package/tools/fetch-balance.d.ts

@@ -0,0 +1,5 @@
+import type { IExchangeAdapter } from '../exchange-adapter.js';
+import type { CcxtBalance } from '../types.js';
+export declare function fetchBalanceTool(_args: Record<string, unknown>, deps: {
+    adapter: IExchangeAdapter;
+}): Promise<CcxtBalance>;

package/tools/fetch-balance.js

@@ -0,0 +1,4 @@
+// Tool: fetch_balance — wallet balance (paper or live)
+export async function fetchBalanceTool(_args, deps) {
+    return deps.adapter.getBalance();
+}

package/tools/fetch-ohlcv.d.ts

@@ -0,0 +1,11 @@
+import type { BinancePublicApi } from '../ccxt/binance-public.js';
+import type { CcxtOHLCV } from '../types.js';
+export declare function fetchOhlcvTool(args: {
+    symbol: string;
+    timeframe?: string;
+    limit?: number;
+}, deps: {
+    binanceApi: BinancePublicApi;
+}): Promise<CcxtOHLCV[] | {
+    error: string;
+}>;

package/tools/fetch-ohlcv.js

@@ -0,0 +1,8 @@
+// Tool: fetch_ohlcv — real Binance OHLCV candles via CCXT
+export async function fetchOhlcvTool(args, deps) {
+    const candles = await deps.binanceApi.fetchOHLCV(args.symbol, args.timeframe ?? '1h', args.limit ?? 100);
+    if (!candles) {
+        return { error: `Failed to fetch OHLCV for ${args.symbol}` };
+    }
+    return candles;
+}

package/tools/fetch-open-orders.d.ts

@@ -0,0 +1,7 @@
+import type { IExchangeAdapter } from '../exchange-adapter.js';
+import type { CcxtOrder } from '../types.js';
+export declare function fetchOpenOrdersTool(args: {
+    symbol?: string;
+}, deps: {
+    adapter: IExchangeAdapter;
+}): Promise<CcxtOrder[]>;

package/tools/fetch-open-orders.js

@@ -0,0 +1,4 @@
+// Tool: fetch_open_orders — pending orders (paper or live)
+export async function fetchOpenOrdersTool(args, deps) {
+    return deps.adapter.getOpenOrders(args.symbol);
+}

package/tools/fetch-positions.d.ts

@@ -0,0 +1,7 @@
+import type { IExchangeAdapter } from '../exchange-adapter.js';
+import type { CcxtPosition } from '../types.js';
+export declare function fetchPositionsTool(args: {
+    symbol?: string;
+}, deps: {
+    adapter: IExchangeAdapter;
+}): Promise<CcxtPosition[]>;

package/tools/fetch-positions.js

@@ -0,0 +1,4 @@
+// Tool: fetch_positions — open positions (paper or live)
+export async function fetchPositionsTool(args, deps) {
+    return deps.adapter.getPositions(args.symbol);
+}

package/tools/fetch-ticker.d.ts

@@ -0,0 +1,11 @@
+import type { BinancePublicApi } from '../ccxt/binance-public.js';
+import type { ExchangeSimulator } from '../simulator/exchange-simulator.js';
+import type { CcxtTicker } from '../types.js';
+export declare function fetchTickerTool(args: {
+    symbol: string;
+}, deps: {
+    binanceApi: BinancePublicApi;
+    simulator: ExchangeSimulator;
+}): Promise<CcxtTicker | {
+    error: string;
+}>;

package/tools/fetch-ticker.js

@@ -0,0 +1,5 @@
+// Tool: fetch_ticker — real Binance market data via CCXT
+import { fetchCurrentPrice } from './helpers.js';
+export async function fetchTickerTool(args, deps) {
+    return fetchCurrentPrice(args.symbol, deps);
+}

package/tools/get-agent-profile.d.ts

@@ -0,0 +1,4 @@
+import type { IntelApiDeps } from './intel-api.js';
+export declare function getAgentProfileTool(deps: IntelApiDeps): Promise<Record<string, unknown> | {
+    error: string;
+}>;

package/tools/get-agent-profile.js

@@ -0,0 +1,6 @@
+// Tool: get_agent_profile — returns earned autonomy tier and permissions.
+// The agent checks this at session start to know what it's allowed to adjust.
+import { fetchIntelApi } from './intel-api.js';
+export async function getAgentProfileTool(deps) {
+    return fetchIntelApi('/api/agent-profile', deps);
+}