@reefclaw/connect 0.1.0

package/assets/plugin/config/plugin-config-io.d.ts

@@ -0,0 +1,175 @@
+import type { TradingMode, ExchangeConfig } from '../types.js';
+/** Full on-disk schema. Unknown keys are preserved on round-trip. */
+export interface PluginConfigFile {
+    connectionToken?: string;
+    apiBaseUrl?: string;
+    intelligenceUrl?: string;
+    exchange?: ExchangeConfig;
+    tradingMode?: TradingMode;
+    microLive?: {
+        sizeCapPercent?: number;
+        maxPositionUSDT?: number;
+    };
+    /** Exchange-native bracket orders (STOP_MARKET + TAKE_PROFIT_MARKET).
+     *  mode='off' (default) keeps legacy stop-watcher behaviour.
+     *  mode='observe' submits brackets AND keeps the watcher active (rollout stage).
+     *  mode='enforce' disables watcher for live; brackets are the sole protection.
+     *
+     *  requireStopLoss / requireTakeProfit (default both true) control whether
+     *  the pre-trade gate rejects live entries that don't include the matching
+     *  price. Operator can untick via the Trading Parameters panel; UI shows a
+     *  red warning (stop off) or amber warning (target off) with typed confirm.
+     *  Migration note: these flags move to intelligence DB per-user alongside
+     *  Phase 2.5 (ledger mirror). Plugin-config is the temporary home. */
+    brackets?: {
+        mode?: 'off' | 'observe' | 'enforce';
+        requireStopLoss?: boolean;
+        requireTakeProfit?: boolean;
+    };
+    /** Facts-out signal evaluation (docs/FACTS_OUT_ARCHITECTURE.md step 5).
+     *  evaluator='central' (default) → get_signals calls the intel engine as today.
+     *  'shadow' → also evaluate locally (via the SSE fact stream) and log the
+     *  comparison; central is still authoritative (zero behaviour change).
+     *  'enforce' → get_signals returns the locally-computed snapshot (falling back
+     *  to central when no fact has arrived for a symbol yet).
+     *  `symbols` is the set the local service streams + evaluates; required when
+     *  evaluator != 'central'. Requires the intel fact stream to be on
+     *  (RC_INTEL_FACTS_STREAM=on). */
+    signals?: {
+        evaluator?: 'central' | 'shadow' | 'enforce';
+        symbols?: string[];
+    };
+    /** Binance user-data WebSocket stream (positions/balance/orders via push).
+     *  mode='off' (default) keeps legacy REST polling authoritative.
+     *  mode='shadow' runs the WS alongside REST and logs diffs; REST still authoritative.
+     *  mode='observe' makes WS authoritative for reads; REST drops to 30-60s truth-check.
+     *  mode='enforce' full cutover — skill-side pollers disabled, REST at 60s truth-check only.
+     *
+     *  listenKeyRefreshMs / reconnectBaseMs / reconnectCapMs are escape-hatch tunables
+     *  for runbook use; defaults are production-safe. staleEventWatchdogMs triggers a
+     *  forced reconnect if no events arrive within the window (catches silent drops). */
+    userDataStream?: {
+        mode?: 'off' | 'shadow' | 'observe' | 'enforce';
+        listenKeyRefreshMs?: number;
+        reconnectBaseMs?: number;
+        reconnectCapMs?: number;
+        staleEventWatchdogMs?: number;
+        /** Interval for REST-refreshing algo orders into the store. Binance WS
+         *  never pushes algo-order state changes until trigger, so this loop fills
+         *  the gap. 0 = disabled. Default 15_000 (15s). */
+        algoRefreshMs?: number;
+        /** @deprecated since 2026-04-25 (ping-aware watchdog refactor). Field is
+         *  still parsed and clamped so existing config files don't fail validation,
+         *  but the runtime no longer reads it — the single `staleEventWatchdogMs`
+         *  (default 6 min, ping-aware) plus the active REST probe replace it. */
+        activeStaleEventWatchdogMs?: number;
+        /** Active REST probe interval — polls fetchMyTrades for every open-position
+         *  symbol; if a trade timestamp exceeds the WS lastEventAt, the WS missed
+         *  a fill and the probe forces a reconnect. 0 = disabled. Default 60_000. */
+        activeProbeIntervalMs?: number;
+        /** Audit-trail write path (TRADE_AUDIT_TRAIL_PLAN Phase 1).
+         *  'off' (default) — WS ingest doesn't write to the trades table.
+         *  'on'            — WsIngest forwards each TRADE event to the webapp's
+         *                    /api/internal/trades endpoint. Idempotent on the
+         *                    (exchange, exchange_trade_id) unique index, so it's
+         *                    safe to run alongside the legacy poller-write path.
+         *  Orthogonal to `mode`: `mode` controls the read path; `dbWrite` controls
+         *  the audit-write path. Both must be enabled (mode≠'off' AND dbWrite='on')
+         *  for WS rows to land in the trades table. */
+        dbWrite?: 'off' | 'on';
+        /** Webapp base URL for the WS ingest POST. Defaults to the production
+         *  reefclaw.com if absent; an explicit value overrides for staging /
+         *  local-dev / on-prem deployments. */
+        ingestBaseUrl?: string;
+    };
+    /** Position Decision Journal — per-heartbeat-per-open-position review tool
+     *  + stale-review gate. See docs/POSITION_DECISION_JOURNAL_PLAN.md.
+     *
+     *  mode='off' (default) — `record_position_reviews` tool exists but no
+     *                          SKILL.md mandate; stale-gate is no-op.
+     *  mode='shadow'        — SKILL.md mandate live; per-heartbeat call required.
+     *                          No gate. Operator reads reviews to confirm quality.
+     *  mode='observe'       — `create_order` returns soft warning on stale review.
+     *  mode='enforce'       — `create_order` hard-rejects on stale review.
+     *
+     *  staleAfterMs caps how old the most recent review can be before the gate
+     *  fires. Default = 2 × heartbeatIntervalMs (60 min for a 30 min heartbeat).
+     *
+     *  Entry/close auto-capture is always-on (independent of `mode`) once the
+     *  webapp ingest URL + token are configured. */
+    positionReview?: {
+        mode?: 'off' | 'shadow' | 'observe' | 'enforce';
+        staleAfterMs?: number;
+        /** Exit-gate flag — prevents premature close_position calls per
+         *  docs/EXIT_GATE_DESIGN.md. Orthogonal to `mode`: `mode` drives the
+         *  per-heartbeat review requirement; `exitGate` drives the per-exit
+         *  tier check.
+         *
+         *  exitGate='off' (default)  — gate never runs; behaviour identical to today.
+         *  exitGate='shadow'         — gate runs, result logged to close_assessment.metadata.gate_eval,
+         *                              `close_position` always proceeds.
+         *  exitGate='observe'        — gate runs; on BLOCK returns a soft warning in the
+         *                              tool result but `close_position` still proceeds.
+         *  exitGate='enforce'        — gate runs; on BLOCK rejects the tool call. */
+        exitGate?: 'off' | 'shadow' | 'observe' | 'enforce';
+    };
+    /** Approval Mode — per-user operator-approval-before-trade gate.
+     *  Plugin emits a proposal via /api/internal/proposed_orders; operator decides
+     *  in the browser; ProposalDecisionListener fires the order on approve via the
+     *  existing create_order backend path. See docs/APPROVAL_MODE_DESIGN.md.
+     *
+     *  mode='off' (default) — fully autonomous; create_order fires immediately.
+     *                          Toggle-off is byte-identical to today's behaviour.
+     *  mode='per_trade'    — every create_order emits a proposal and returns
+     *                          {status:'pending_approval'} to the agent. Listener
+     *                          fires the order when the operator clicks Approve.
+     *
+     *  pollIntervalMs caps how often the listener checks for approved-but-unfired
+     *  proposals via GET /api/internal/proposed_orders/pending-decisions. Default
+     *  3 sec — well under typical human approval latency. */
+    approval?: {
+        mode?: 'off' | 'per_trade';
+        pollIntervalMs?: number;
+    };
+    /** Public Binance market microstructure features (cross-market liquidation
+     *  pulse + banded resting liquidity). Data layer lives on the intelligence
+     *  VPS (separate workstream — see docs/MARKET_MICROSTRUCTURE_STREAMS.md);
+     *  this flag controls whether the plugin attaches a per-symbol microstructure
+     *  block to position-aware tool results (e.g. check_position_health) so the
+     *  agent sees orderbook context every heartbeat without an extra tool call.
+     *
+     *  heartbeatPush='off' (default) — no auto-attach. Agent can still call
+     *                                    get_resting_liquidity / get_liquidation_pulse
+     *                                    explicitly.
+     *  heartbeatPush='on'             — block attached when intel data is fresh. */
+    microstructure?: {
+        heartbeatPush?: 'off' | 'on';
+    };
+    /** EFFICIENCY_QUICK_WINS Change 1 — operator override for the legacy
+     *  PositionWatcher poll cadence. Default 10000 (see stop-watcher.ts).
+     *  Lets the operator revert the 3s→10s cut with zero deploy if a soak
+     *  criterion fails. */
+    stopWatcher?: {
+        intervalMs?: number;
+    };
+    [extra: string]: unknown;
+}
+export declare function defaultConfigPath(): string;
+/** Read the config file. Returns `{}` if the file doesn't exist.
+ *  Throws if the file exists but is unreadable or not valid JSON — callers
+ *  should treat that as an abort signal, not silently overwrite. */
+export declare function readPluginConfig(path?: string): PluginConfigFile;
+/** Apply a patch on top of the existing file and write atomically.
+ *  - Unknown top-level keys in the on-disk file are preserved.
+ *  - Unknown sub-keys of `microLive` are preserved.
+ *  - Passing `undefined` as a top-level patch value deletes that key.
+ *  - A `null` for `exchange` clears credentials.
+ *
+ *  Atomicity: we write to `<path>.tmp` then rename. If the process crashes
+ *  mid-write, the original file is untouched. A stale `.tmp` is overwritten
+ *  on the next successful write.
+ */
+export declare function updatePluginConfig(patch: Partial<PluginConfigFile>, path?: string): PluginConfigFile;
+/** Redact a credential for logging — keeps first 4 and last 2 chars.
+ *  Never log the full key/secret. */
+export declare function redactCredential(value: string | undefined | null): string;

package/assets/plugin/config/plugin-config-io.js

@@ -0,0 +1,84 @@
+// Atomic read/write for ~/.reefclaw/plugin-config.json.
+//
+// Historically the plugin only READ this file at startup. As of PR1 of the
+// dashboard onboarding feature, the plugin also WRITES it when the operator
+// sets credentials or switches trading mode from the webapp. Writes must be
+// crash-safe (no half-written JSON) and must preserve keys we don't understand
+// (forwards compatibility — other tools may add fields we don't know about).
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+export function defaultConfigPath() {
+    return join(homedir(), '.reefclaw', 'plugin-config.json');
+}
+/** Read the config file. Returns `{}` if the file doesn't exist.
+ *  Throws if the file exists but is unreadable or not valid JSON — callers
+ *  should treat that as an abort signal, not silently overwrite. */
+export function readPluginConfig(path = defaultConfigPath()) {
+    if (!existsSync(path))
+        return {};
+    const raw = readFileSync(path, 'utf-8');
+    const parsed = JSON.parse(raw);
+    if (parsed == null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error(`plugin-config.json root is not an object`);
+    }
+    return parsed;
+}
+/** Apply a patch on top of the existing file and write atomically.
+ *  - Unknown top-level keys in the on-disk file are preserved.
+ *  - Unknown sub-keys of `microLive` are preserved.
+ *  - Passing `undefined` as a top-level patch value deletes that key.
+ *  - A `null` for `exchange` clears credentials.
+ *
+ *  Atomicity: we write to `<path>.tmp` then rename. If the process crashes
+ *  mid-write, the original file is untouched. A stale `.tmp` is overwritten
+ *  on the next successful write.
+ */
+export function updatePluginConfig(patch, path = defaultConfigPath()) {
+    const dir = dirname(path);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    const current = readPluginConfig(path);
+    const merged = { ...current };
+    for (const [key, value] of Object.entries(patch)) {
+        if (value === undefined) {
+            delete merged[key];
+        }
+        else if (key === 'microLive' && value && typeof value === 'object') {
+            merged.microLive = { ...(current.microLive ?? {}), ...value };
+        }
+        else if (key === 'brackets' && value && typeof value === 'object') {
+            merged.brackets = { ...(current.brackets ?? {}), ...value };
+        }
+        else if (key === 'userDataStream' && value && typeof value === 'object') {
+            merged.userDataStream = { ...(current.userDataStream ?? {}), ...value };
+        }
+        else if (key === 'positionReview' && value && typeof value === 'object') {
+            merged.positionReview = { ...(current.positionReview ?? {}), ...value };
+        }
+        else if (key === 'microstructure' && value && typeof value === 'object') {
+            merged.microstructure = { ...(current.microstructure ?? {}), ...value };
+        }
+        else if (key === 'approval' && value && typeof value === 'object') {
+            merged.approval = { ...(current.approval ?? {}), ...value };
+        }
+        else {
+            merged[key] = value;
+        }
+    }
+    const tmpPath = `${path}.tmp`;
+    const body = JSON.stringify(merged, null, 2) + '\n';
+    writeFileSync(tmpPath, body, { encoding: 'utf-8', mode: 0o600 });
+    renameSync(tmpPath, path);
+    return merged;
+}
+/** Redact a credential for logging — keeps first 4 and last 2 chars.
+ *  Never log the full key/secret. */
+export function redactCredential(value) {
+    if (!value)
+        return '(empty)';
+    if (value.length <= 8)
+        return '***';
+    return `${value.slice(0, 4)}…${value.slice(-2)}`;
+}

package/assets/plugin/config/position-review-config.d.ts

@@ -0,0 +1,35 @@
+import { type PluginConfigFile } from './plugin-config-io.js';
+export type PositionReviewMode = 'off' | 'shadow' | 'observe' | 'enforce';
+export declare function getPositionReviewMode(config?: PluginConfigFile): PositionReviewMode;
+/** Resolve the position-review mode with the central-config precedence
+ *  (TOOL_DISTRIBUTION_ARCHITECTURE.md §11 step 3, slice 3):
+ *
+ *      central (agent_config.gates via gate-store) → plugin-config.json → 'off'
+ *
+ *  The central value is already enum-validated (agent-config-client
+ *  validateGates) and hot-applies on the next poll. `record_position_reviews`
+ *  reads this per call (index.ts), so a dashboard/API flip needs NO restart —
+ *  same mechanics as loadExitGateMode. Kill-switch RC_CENTRAL_GATES=off makes
+ *  the store report null → the file rules again. (The startup log read at
+ *  boot may still show the file value until the first poll applies central;
+ *  it is cosmetic — the behavioural read is per-call.) */
+export declare function loadPositionReviewMode(): PositionReviewMode;
+export type ExitGateMode = 'off' | 'shadow' | 'observe' | 'enforce';
+export declare function getExitGateMode(config?: PluginConfigFile): ExitGateMode;
+/** Resolve the exit-gate mode with the central-config precedence
+ *  (TOOL_DISTRIBUTION_ARCHITECTURE.md §11 step 3, slice 2):
+ *
+ *      central (agent_config.gates via gate-store) → plugin-config.json → 'off'
+ *
+ *  The central value is already enum-validated (agent-config-client
+ *  validateGates) and hot-applies on the next poll — close-position.ts reads
+ *  this per call, so a dashboard/API flip needs NO restart. `deps.exitGateMode`
+ *  at the call site (tests) stays above all of this. Kill-switch
+ *  RC_CENTRAL_GATES=off makes the store report null → the file rules again. */
+export declare function loadExitGateMode(): ExitGateMode;
+/** Stale threshold in ms. Default = 60 minutes (2 × 30-min heartbeat). */
+export declare function getPositionReviewStaleAfterMs(config?: PluginConfigFile): number;
+export declare function loadPositionReviewStaleAfterMs(): number;
+export type MicrostructureHeartbeatPush = 'off' | 'on';
+export declare function getMicrostructureHeartbeatPush(config?: PluginConfigFile): MicrostructureHeartbeatPush;
+export declare function loadMicrostructureHeartbeatPush(): MicrostructureHeartbeatPush;

package/assets/plugin/config/position-review-config.js

@@ -0,0 +1,105 @@
+// Feature-flag readers for the Position Decision Journal.
+//
+// Two flags, both default 'off' so the system ships dead-code:
+//   - positionReview.mode      drives the heartbeat-mandate + stale-gate
+//   - microstructure.heartbeatPush  drives orderbook auto-attach to per-position tools
+//
+// See docs/POSITION_DECISION_JOURNAL_PLAN.md.
+import { readPluginConfig } from './plugin-config-io.js';
+import { gateStore } from './gate-store.js';
+const VALID_REVIEW_MODES = new Set([
+    'off',
+    'shadow',
+    'observe',
+    'enforce',
+]);
+export function getPositionReviewMode(config) {
+    const raw = config?.positionReview?.mode;
+    if (typeof raw === 'string' && VALID_REVIEW_MODES.has(raw)) {
+        return raw;
+    }
+    return 'off';
+}
+/** Resolve the position-review mode with the central-config precedence
+ *  (TOOL_DISTRIBUTION_ARCHITECTURE.md §11 step 3, slice 3):
+ *
+ *      central (agent_config.gates via gate-store) → plugin-config.json → 'off'
+ *
+ *  The central value is already enum-validated (agent-config-client
+ *  validateGates) and hot-applies on the next poll. `record_position_reviews`
+ *  reads this per call (index.ts), so a dashboard/API flip needs NO restart —
+ *  same mechanics as loadExitGateMode. Kill-switch RC_CENTRAL_GATES=off makes
+ *  the store report null → the file rules again. (The startup log read at
+ *  boot may still show the file value until the first poll applies central;
+ *  it is cosmetic — the behavioural read is per-call.) */
+export function loadPositionReviewMode() {
+    const central = gateStore.getPositionReviewMode();
+    if (central)
+        return central;
+    try {
+        return getPositionReviewMode(readPluginConfig());
+    }
+    catch {
+        return 'off';
+    }
+}
+const VALID_EXIT_GATE_MODES = new Set([
+    'off',
+    'shadow',
+    'observe',
+    'enforce',
+]);
+export function getExitGateMode(config) {
+    const raw = config?.positionReview?.exitGate;
+    if (typeof raw === 'string' && VALID_EXIT_GATE_MODES.has(raw)) {
+        return raw;
+    }
+    return 'off';
+}
+/** Resolve the exit-gate mode with the central-config precedence
+ *  (TOOL_DISTRIBUTION_ARCHITECTURE.md §11 step 3, slice 2):
+ *
+ *      central (agent_config.gates via gate-store) → plugin-config.json → 'off'
+ *
+ *  The central value is already enum-validated (agent-config-client
+ *  validateGates) and hot-applies on the next poll — close-position.ts reads
+ *  this per call, so a dashboard/API flip needs NO restart. `deps.exitGateMode`
+ *  at the call site (tests) stays above all of this. Kill-switch
+ *  RC_CENTRAL_GATES=off makes the store report null → the file rules again. */
+export function loadExitGateMode() {
+    const central = gateStore.getExitGate();
+    if (central)
+        return central;
+    try {
+        return getExitGateMode(readPluginConfig());
+    }
+    catch {
+        return 'off';
+    }
+}
+/** Stale threshold in ms. Default = 60 minutes (2 × 30-min heartbeat). */
+export function getPositionReviewStaleAfterMs(config) {
+    const raw = config?.positionReview?.staleAfterMs;
+    if (typeof raw === 'number' && Number.isFinite(raw) && raw > 0)
+        return raw;
+    return 60 * 60 * 1000;
+}
+export function loadPositionReviewStaleAfterMs() {
+    try {
+        return getPositionReviewStaleAfterMs(readPluginConfig());
+    }
+    catch {
+        return 60 * 60 * 1000;
+    }
+}
+export function getMicrostructureHeartbeatPush(config) {
+    return config?.microstructure?.heartbeatPush === 'on' ? 'on' : 'off';
+}
+export function loadMicrostructureHeartbeatPush() {
+    try {
+        return getMicrostructureHeartbeatPush(readPluginConfig());
+    }
+    catch {
+        return 'off';
+    }
+}

package/assets/plugin/config/tool-gate.d.ts

@@ -0,0 +1,53 @@
+/** Safety-floor (core) tools + operator-control tools. Never governable. */
+export declare const UNGOVERNABLE_TOOLS: ReadonlySet<string>;
+export type ToolGateMode = 'enforce' | 'shadow' | 'off';
+/** RC_TOOL_GATE: 'off' = kill-switch (gate never blocks), 'shadow' = log
+ *  would-be blocks but execute anyway, anything else/default = 'enforce'.
+ *  Kill-switch convention per the plugin's other RC_* flags: a systemd env
+ *  override flips it instantly on restart, no redeploy. */
+export declare function resolveToolGateMode(): ToolGateMode;
+/** The structured, agent-visible result for a blocked call. Worded so the
+ *  agent adapts instead of retrying. */
+export declare function disabledToolResult(name: string): {
+    ok: false;
+    error: 'tool_disabled_by_operator';
+    tool: string;
+    message: string;
+};
+/** Minimal structural view of a registered plugin tool. `execute` is variadic
+ *  (toolCallId, params, signal?) and typed loosely to match the plugin-boundary
+ *  PluginTool interface in index.ts, which itself uses `any` for params. The
+ *  generic in wrapTool preserves the concrete tool shape (label, description,
+ *  parameters, …). */
+export interface GateablePluginTool {
+    name: string;
+    execute: (...args: any[]) => any;
+}
+export declare class ToolGate {
+    private readonly mode;
+    private disabled;
+    private version;
+    /** Names already shadow-logged for the current version — avoids log spam. */
+    private shadowLogged;
+    constructor(mode?: ToolGateMode);
+    getMode(): ToolGateMode;
+    getVersion(): number;
+    getDisabled(): string[];
+    /** Apply a validated config. Strips ungovernable names (third enforcement
+     *  layer — the webapp write route and internal read route already did), and
+     *  logs only when the effective set actually changed. */
+    apply(config: {
+        version: number;
+        tools: {
+            disabled: string[];
+        };
+    }): void;
+    /** Should this call be blocked? Ungovernable names short-circuit FIRST —
+     *  the safety floor wins over any disabled set, in any mode. */
+    isBlocked(name: string): boolean;
+    /** Wrap a tool's execute with the gate check. The returned tool is
+     *  identical except `execute` consults the gate's live state per call —
+     *  which is what makes a config change hot-apply without re-registration.
+     *  All original args (toolCallId, params, abort signal) pass through. */
+    wrapTool<T extends GateablePluginTool>(tool: T, jsonResult: (data: unknown) => unknown): T;
+}

package/assets/plugin/config/tool-gate.js

@@ -0,0 +1,125 @@
+// ToolGate — the plugin-side enforcement point for the Tools-tab OFF-list
+// (docs/TOOL_DISTRIBUTION_ARCHITECTURE.md §5f). Every registered tool's
+// `execute` is wrapped once at registration; the wrapper consults the gate's
+// LIVE state on every invocation, so a config change applies on the next call
+// with no re-registration and no restart (§5e hot-reload).
+//
+// ★ §5d SAFETY FLOOR — UNGOVERNABLE_TOOLS is hardcoded here and checked
+// BEFORE the disabled set. Even if a compromised config server, a hand-edited
+// DB row, or a poisoned cache ships `close_position` in the OFF-list, the
+// gate never blocks it. This set is pinned by a test on this side AND a
+// mirror pin in the webapp catalog (tools-catalog.test.ts) — change both
+// deliberately or not at all.
+import { logger } from '../logger.js';
+const TAG = 'tool-gate';
+/** Safety-floor (core) tools + operator-control tools. Never governable. */
+export const UNGOVERNABLE_TOOLS = new Set([
+    // Core safety floor — protecting/exiting positions and the review capture.
+    'create_order',
+    'close_position',
+    'modify_stop',
+    'attach_brackets',
+    'audit_bracket_protection',
+    'record_position_reviews',
+    // Operator-control channel — disabling these would lock the operator out.
+    'set_exchange_credentials',
+    'test_exchange_credentials',
+    'clear_exchange_credentials',
+    'set_trading_mode',
+    'get_bracket_config',
+    'set_bracket_requirement',
+]);
+/** RC_TOOL_GATE: 'off' = kill-switch (gate never blocks), 'shadow' = log
+ *  would-be blocks but execute anyway, anything else/default = 'enforce'.
+ *  Kill-switch convention per the plugin's other RC_* flags: a systemd env
+ *  override flips it instantly on restart, no redeploy. */
+export function resolveToolGateMode() {
+    const raw = (process.env.RC_TOOL_GATE ?? '').toLowerCase();
+    if (raw === 'off')
+        return 'off';
+    if (raw === 'shadow')
+        return 'shadow';
+    return 'enforce';
+}
+/** The structured, agent-visible result for a blocked call. Worded so the
+ *  agent adapts instead of retrying. */
+export function disabledToolResult(name) {
+    return {
+        ok: false,
+        error: 'tool_disabled_by_operator',
+        tool: name,
+        message: `The ${name} tool has been disabled by your operator in the ReefClaw dashboard Tools tab. ` +
+            `Do not retry this call — adapt your plan without it, and mention to your operator that ` +
+            `re-enabling it in the dashboard would help if you believe it is needed.`,
+    };
+}
+export class ToolGate {
+    mode;
+    disabled = new Set();
+    version = 0;
+    /** Names already shadow-logged for the current version — avoids log spam. */
+    shadowLogged = new Set();
+    constructor(mode = resolveToolGateMode()) {
+        this.mode = mode;
+        if (mode !== 'enforce')
+            logger.info(TAG, `mode=${mode}`);
+    }
+    getMode() {
+        return this.mode;
+    }
+    getVersion() {
+        return this.version;
+    }
+    getDisabled() {
+        return [...this.disabled].sort();
+    }
+    /** Apply a validated config. Strips ungovernable names (third enforcement
+     *  layer — the webapp write route and internal read route already did), and
+     *  logs only when the effective set actually changed. */
+    apply(config) {
+        const next = new Set(config.tools.disabled.filter((n) => !UNGOVERNABLE_TOOLS.has(n)));
+        const changed = next.size !== this.disabled.size || [...next].some((n) => !this.disabled.has(n));
+        this.version = config.version;
+        if (!changed)
+            return;
+        this.disabled = next;
+        this.shadowLogged.clear();
+        logger.info(TAG, `applied config v${config.version}: ${next.size} tool(s) disabled${next.size > 0 ? ` (${[...next].sort().join(', ')})` : ''}`);
+    }
+    /** Should this call be blocked? Ungovernable names short-circuit FIRST —
+     *  the safety floor wins over any disabled set, in any mode. */
+    isBlocked(name) {
+        if (this.mode === 'off')
+            return false;
+        if (UNGOVERNABLE_TOOLS.has(name))
+            return false;
+        if (!this.disabled.has(name))
+            return false;
+        if (this.mode === 'shadow') {
+            if (!this.shadowLogged.has(name)) {
+                this.shadowLogged.add(name);
+                logger.info(TAG, `SHADOW: would block ${name} (config v${this.version})`);
+            }
+            return false;
+        }
+        return true;
+    }
+    /** Wrap a tool's execute with the gate check. The returned tool is
+     *  identical except `execute` consults the gate's live state per call —
+     *  which is what makes a config change hot-apply without re-registration.
+     *  All original args (toolCallId, params, abort signal) pass through. */
+    wrapTool(tool, jsonResult) {
+        const originalExecute = tool.execute.bind(tool);
+        return {
+            ...tool,
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            execute: (...args) => {
+                if (this.isBlocked(tool.name)) {
+                    logger.info(TAG, `blocked ${tool.name} (disabled by operator, config v${this.version})`);
+                    return Promise.resolve(jsonResult(disabledToolResult(tool.name)));
+                }
+                return originalExecute(...args);
+            },
+        };
+    }
+}

package/assets/plugin/config/user-data-stream-config.d.ts

@@ -0,0 +1,85 @@
+import { type PluginConfigFile } from './plugin-config-io.js';
+export type UserDataStreamMode = 'off' | 'shadow' | 'observe' | 'enforce';
+/** Production-safe defaults. Override via plugin-config for runbook use only. */
+export interface UserDataStreamTunables {
+    /** How often to call PUT /fapi/v1/listenKey to keep the stream alive.
+     *  Binance kills the key after 60 min of no keepalive; 25 min gives a 2x
+     *  safety margin under jitter and transient failures. */
+    listenKeyRefreshMs: number;
+    /** Initial backoff delay after a WS disconnect. Doubles on each attempt
+     *  up to reconnectCapMs. ±20% jitter applied to avoid thundering herd. */
+    reconnectBaseMs: number;
+    /** Cap on the exponential backoff. Keeps us trying indefinitely but not
+     *  more than once/minute after repeated failures. */
+    reconnectCapMs: number;
+    /** If no WS frame of any kind (message, ping, or pong) arrives within this
+     *  window, force a reconnect. Binance documents server pings every 3 min on
+     *  the user-data stream; a 6-min default catches a truly dead socket while
+     *  remaining quiet on calm accounts that get only the periodic pings. */
+    staleEventWatchdogMs: number;
+    /** How often to REST-refresh algo (STOP_MARKET / TAKE_PROFIT_MARKET / bracket)
+     *  orders into the store. Binance's user-data WS does NOT emit
+     *  ORDER_TRADE_UPDATE for algo orders until they trigger, so the store has no
+     *  other way to observe algo-order add/cancel events. Without this loop, the
+     *  60s truth-check reports MAJOR order drift every cycle any time brackets
+     *  are touched. Set to 0 to disable (falls back to snapshot-only). */
+    algoRefreshMs: number;
+    /** @deprecated since 2026-04-25 (ping-aware watchdog refactor). Field kept
+     *  for backward compatibility with existing plugin-config.json files; the
+     *  runtime no longer consults it. Empirically 99% of its fires were
+     *  false positives because the 90 s default sat below Binance's 180 s
+     *  server-ping interval and the watchdog only counted message frames as
+     *  liveness. The single `staleEventWatchdogMs` (6 min default, ping-aware)
+     *  is now sufficient; the active REST probe handles per-position freshness. */
+    activeStaleEventWatchdogMs: number;
+    /** How often the active REST probe checks for fills the WS missed.
+     *  Iterates open positions, calls fetchMyTrades(since=lastEventAt), and
+     *  forces a reconnect if any trade newer than lastEventAt is found.
+     *  Set to 0 to disable. Cost: ~5 weight per open position per probe. */
+    activeProbeIntervalMs: number;
+}
+export declare const DEFAULT_TUNABLES: UserDataStreamTunables;
+/** Read user-data-stream mode from a config object. Invalid values fall back to 'off'. */
+export declare function getUserDataStreamMode(config?: PluginConfigFile, remoteOverride?: UserDataStreamMode): UserDataStreamMode;
+/** Convenience: load from disk and return the effective mode. */
+export declare function loadUserDataStreamMode(): UserDataStreamMode;
+/** Is the WS stream enabled at all (anything other than 'off')? */
+export declare function userDataStreamEnabled(mode: UserDataStreamMode): boolean;
+export type UserDataStreamDbWrite = 'off' | 'on';
+/** Read the dbWrite flag.  Orthogonal to `mode`: `mode` controls the read
+ *  path (WS vs REST authoritative for getPositions etc.); `dbWrite` controls
+ *  whether WS-observed fills are POSTed to the webapp's audit-trail store.
+ *  Both must be enabled together for WS rows to land in `trades`. */
+export declare function getUserDataStreamDbWrite(config?: PluginConfigFile): UserDataStreamDbWrite;
+export declare function loadUserDataStreamDbWrite(): UserDataStreamDbWrite;
+/** Webapp ingest base URL (POST target).  Defaults to production reefclaw.com. */
+export declare function getUserDataStreamIngestBaseUrl(config?: PluginConfigFile): string;
+/** Resolve the webapp-ingest credential (the per-user `rc_*` token).
+ *
+ *  Prefers `connectionToken` in plugin-config.json — the same `rc_*` token
+ *  already stored there for the intel-service client, so there's one fewer
+ *  place to update on rotation than the legacy `WEBAPP_INGEST_TOKEN` systemd
+ *  env var. Falls back to that env var so existing deployments that haven't
+ *  moved the token into plugin-config.json keep working unchanged.
+ *
+ *  Both ingest paths (position-decisions journal + WS audit-trail) use this. */
+export declare function resolveIngestToken(config?: PluginConfigFile): string;
+/** Is the WS authoritative for reads (observe or enforce)? In shadow it's
+ *  only observed — REST remains the source of truth for getPositions etc. */
+export declare function userDataStreamAuthoritative(mode: UserDataStreamMode): boolean;
+/** Should REST polling cadence be reduced? True in observe/enforce where
+ *  WS is carrying the hot-path signal and REST is only a truth-check. */
+export declare function restPollingReduced(mode: UserDataStreamMode): boolean;
+/** Read tunables, falling back to DEFAULT_TUNABLES for any missing field.
+ *  Clamps are defense-in-depth against a truncated or nonsensical config. */
+export declare function getUserDataStreamTunables(config?: PluginConfigFile): UserDataStreamTunables;
+export declare function loadUserDataStreamTunables(): UserDataStreamTunables;
+/** Validate a proposed transition. Returns `{ allowed: false, reason }` when
+ *  the move is blocked so the deploy script can refuse. Forward transitions
+ *  must progress through stages; reverse transitions (to any earlier stage,
+ *  including 'off') are always permitted as a safety-net rollback. */
+export interface TransitionCheck {
+    allowed: boolean;
+    reason?: string;
+}
+export declare function checkTransition(from: UserDataStreamMode, to: UserDataStreamMode): TransitionCheck;