@reefclaw/connect 0.1.30 → 0.1.32

package/assets/bridge/types.d.ts

@@ -3,7 +3,7 @@ export type { Channel, RequestFrame, ResponseFrame, EventFrame, Frame, Emergency
 export { VALID_CHANNELS, VALID_EMERGENCY_ACTIONS } from '@reefclaw/shared';
 type EventFrame = _EventFrame;
 /** Methods the skill accepts from the relay (browser → skill) */
-export declare const ALLOWED_METHODS: readonly ["emergency.kill", "emergency.flatten", "emergency.pause", "emergency.resume", "reconcile", "chat.send", "skill.update", "close_position", "set_trading_mode", "set_exchange_credentials", "test_exchange_credentials", "clear_exchange_credentials", "hl_provision_agent_wallet", "hl_agent_wallet_status", "hl_submit_agent_approval", "get_bracket_config", "set_bracket_requirement"];
+export declare const ALLOWED_METHODS: readonly ["emergency.kill", "emergency.flatten", "emergency.pause", "emergency.resume", "reconcile", "chat.send", "skill.update", "close_position", "set_trading_mode", "set_exchange_credentials", "test_exchange_credentials", "clear_exchange_credentials", "hl_provision_agent_wallet", "hl_agent_wallet_status", "hl_submit_agent_approval", "get_bracket_config", "set_bracket_requirement", "connector.update"];
 /** Subset of ALLOWED_METHODS that require operator.write scope. The bridge
  *  enforces this before dispatching — a session without the scope gets a
  *  403 error. PR2 ships the scope as session-wide (inherited from the Clerk
@@ -602,6 +602,10 @@ export interface ConnectorConfig {
     relayUrl: string;
     userId: string;
     token: string;
+    /** Stable per-install id (non-secret), sent as `?instance=` so the relay's
+     *  skill-slot admission can tell "same box restarting" (instant takeover)
+     *  from "second box" (rejected 4011). See utils/instance-id.ts. */
+    instanceId?: string;
     reconnect?: {
         baseDelayMs?: number;
         maxDelayMs?: number;

package/assets/bridge/types.js

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

package/assets/bridge/utils/instance-id.d.ts

@@ -0,0 +1,3 @@
+/** Read-or-create the stable instance id. `baseDir` overrides the storage
+ *  directory (tests; defaults to ~/.reefclaw). Never throws. */
+export declare function resolveRelayInstanceId(baseDir?: string): string;

package/assets/bridge/utils/instance-id.js

@@ -0,0 +1,48 @@
+// Stable per-install relay instance id (2026-08-25, skill-slot admission).
+//
+// The relay seats ONE skill connection per account and refuses newcomers —
+// EXCEPT a newcomer proving it is the same box restarting, which takes over
+// instantly (the graceful-restart property). "Same box" = this id, sent as a
+// non-secret `?instance=` query param on the relay URL. It must therefore
+// survive process restarts: persisted once per install at
+// `~/.reefclaw/relay-instance-id` and reused forever.
+//
+// Fail-open: when the filesystem refuses (read-only home, exotic container),
+// fall back to a per-process id. Takeover-after-crash then degrades to the
+// relay's liveness timeout instead of being instant — worse, never wrong.
+import { randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { logger } from '../logger.js';
+const TAG = 'instance-id';
+const ID_SHAPE = /^[A-Za-z0-9-]{8,64}$/;
+/** Read-or-create the stable instance id. `baseDir` overrides the storage
+ *  directory (tests; defaults to ~/.reefclaw). Never throws. */
+export function resolveRelayInstanceId(baseDir) {
+    // Operator escape hatch (e.g. two deliberate installs sharing one home dir).
+    const fromEnv = process.env.RC_RELAY_INSTANCE_ID?.trim();
+    if (fromEnv && ID_SHAPE.test(fromEnv))
+        return fromEnv;
+    const dir = baseDir ?? join(homedir(), '.reefclaw');
+    const file = join(dir, 'relay-instance-id');
+    try {
+        if (existsSync(file)) {
+            const existing = readFileSync(file, 'utf8').trim();
+            if (ID_SHAPE.test(existing))
+                return existing;
+            // Garbled file: fall through and rewrite — a fresh id only costs one
+            // liveness-timeout takeover, a garbled param corrupts the admission key.
+        }
+        const fresh = randomUUID();
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(file, fresh + '\n', 'utf8');
+        return fresh;
+    }
+    catch (err) {
+        const perProcess = randomUUID();
+        logger.warn(TAG, `Could not persist relay instance id (${err.message}) — using per-process id; ` +
+            `crash takeover degrades to the relay liveness timeout`);
+        return perProcess;
+    }
+}

package/assets/plugin/ccxt/binance-private.js

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

package/assets/plugin/ccxt/binance-public.js

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

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

@@ -4,11 +4,14 @@
  *  never whole-payload rejection. Gates are added one at a time
  *  (TOOL_DISTRIBUTION_ARCHITECTURE.md §11 step 3): `exitGate` (slice 2) →
  *  `positionReviewMode` (slice 3, the Position Decision Journal
- *  heartbeat-mandate + superset gate, file key `positionReview.mode`). Both
- *  ride the same four-stage `off → shadow → observe → enforce` ladder. */
+ *  heartbeat-mandate + superset gate, file key `positionReview.mode`) →
+ *  `approvalMode` (slice 4, per-trade operator approval, file key
+ *  `approval.mode`). The first two ride the same four-stage
+ *  `off → shadow → observe → enforce` ladder; approvalMode has its own. */
 export interface AgentGates {
     exitGate?: 'off' | 'shadow' | 'observe' | 'enforce';
     positionReviewMode?: 'off' | 'shadow' | 'observe' | 'enforce';
+    approvalMode?: 'off' | 'per_trade';
 }
 /** Server-resolved entitlement verdict (webapp lib/entitlements.ts, computed
  *  from the users row and delivered on the config channel). The plugin NEVER

package/assets/plugin/config/agent-config-client.js

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

package/assets/plugin/config/agent-config-poller.js

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

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

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

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

@@ -30,11 +30,13 @@ class GateStore {
     apply(gates) {
         const next = gates ?? {};
         const changed = next.exitGate !== this.gates.exitGate ||
-            next.positionReviewMode !== this.gates.positionReviewMode;
+            next.positionReviewMode !== this.gates.positionReviewMode ||
+            next.approvalMode !== this.gates.approvalMode;
         this.gates = { ...next };
         if (changed) {
             logger.info(TAG, `applied central gates: exitGate=${next.exitGate ?? UNSET} ` +
-                `positionReviewMode=${next.positionReviewMode ?? UNSET}`);
+                `positionReviewMode=${next.positionReviewMode ?? UNSET} ` +
+                `approvalMode=${next.approvalMode ?? UNSET}`);
         }
     }
     /** The central exitGate mode, or null when central has no value (or the
@@ -51,6 +53,19 @@ class GateStore {
             return null;
         return this.gates.positionReviewMode ?? null;
     }
+    /** The central approval.mode, or null when central has no value (or the
+     *  kill-switch is on) — null tells the reader to fall back to the file.
+     *
+     *  ★ Central can only ever say 'off' or 'per_trade'. It cannot enable shadow
+     *  telemetry (that's the local APPROVAL_SHADOW_MODE env flag) and it cannot
+     *  weaken the hardcoded safety floor — per_trade only ADDS a gate, and 'off'
+     *  is the pre-existing autonomous behaviour, so neither value can leave a
+     *  position unprotected. */
+    getApprovalMode() {
+        if (!centralGatesEnabled())
+            return null;
+        return this.gates.approvalMode ?? null;
+    }
     /** Test-only. */
     __reset() {
         this.gates = {};

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

@@ -10,7 +10,7 @@
 // operator-only tool gated on dashboard provenance (verifyOperatorProvenance,
 // audit F12) — the agent cannot reach these writes conversationally. The file
 // is the plugin's OWN config store; nothing here touches OpenClaw's config.
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync, } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { logger } from '../logger.js';
@@ -82,17 +82,39 @@ export function loadMicroLiveConfig(path) {
     catch { /* best-effort — adapter default applies */ }
     return undefined;
 }
+// mtime(ns)+size memo: several hot paths re-read this file per tool call
+// (approval mode, bracket mode/requirements, exit gate, review mode, the
+// microstructure flag × N symbols on the review path). A write always bumps
+// mtime, so the documented per-call hot-reload semantics are preserved
+// exactly — an unchanged file just costs one stat instead of read+parse.
+// structuredClone on both sides keeps today's fresh-object-per-call contract.
+const readMemo = new Map();
 /** 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))
+    if (!existsSync(path)) {
+        readMemo.delete(path);
         return {};
+    }
+    let stat;
+    try {
+        const s = statSync(path, { bigint: true });
+        stat = { mtimeNs: s.mtimeNs, size: s.size };
+        const hit = readMemo.get(path);
+        if (hit && hit.mtimeNs === stat.mtimeNs && hit.size === stat.size) {
+            return structuredClone(hit.parsed);
+        }
+    }
+    catch { /* stat raced a delete — fall through to the plain read */ }
     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`);
     }
+    if (stat) {
+        readMemo.set(path, { ...stat, parsed: structuredClone(parsed) });
+    }
     return parsed;
 }
 /** Apply a patch on top of the existing file and write atomically.

package/assets/plugin/http/keepalive-fetch.d.ts

@@ -0,0 +1,5 @@
+export type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+/** Drop-in fetch with connection keep-alive; falls back to global fetch when
+ *  undici is unavailable, and defers to globalThis.fetch whenever it has been
+ *  replaced (mocks/instrumentation). */
+export declare function keepAliveFetch(url: string, init?: RequestInit): Promise<Response>;

package/assets/plugin/http/keepalive-fetch.js

@@ -0,0 +1,50 @@
+// Keep-alive HTTP for the plugin's intel/webapp clients.
+//
+// Node's built-in fetch closes idle sockets after undici's 4s default, and the
+// gap between two agent tool calls is LLM think-time (seconds to tens of
+// seconds) — so every intel/webapp call was paying a fresh TCP+TLS handshake
+// (~2 RTTs) before any server work started. A dedicated undici Agent with a
+// 60s idle timeout holds the connection across those gaps.
+//
+// undici loads via createRequire (same rule as CCXT — see
+// docs/CLAUDE/plugin-integration.md) and the whole module FAILS OPEN to the
+// global fetch: dist-only overlay deploys land on boxes whose node_modules
+// predate this dependency, and a missing package must degrade to today's
+// behaviour, never crash the connector.
+import { createRequire } from 'node:module';
+// Captured at module load. When someone REPLACES globalThis.fetch later
+// (vitest fetch mocks, tracing wrappers), keepAliveFetch honors the
+// replacement instead of undici — otherwise every fetch-stubbing test (and
+// any legitimate instrumentation) would be silently bypassed onto the real
+// network.
+const nativeFetch = globalThis.fetch;
+let cached;
+function build() {
+    try {
+        const req = createRequire(import.meta.url);
+        const undici = req('undici');
+        const dispatcher = new undici.Agent({
+            keepAliveTimeout: 60_000,
+            keepAliveMaxTimeout: 300_000,
+            connections: 16,
+        });
+        // undici's own fetch + Agent are used together: passing an npm-undici
+        // dispatcher to Node's built-in fetch can fail an instanceof check against
+        // the internal undici copy.
+        return (url, init) => undici.fetch(url, { ...init, dispatcher });
+    }
+    catch {
+        return (url, init) => fetch(url, init);
+    }
+}
+/** Drop-in fetch with connection keep-alive; falls back to global fetch when
+ *  undici is unavailable, and defers to globalThis.fetch whenever it has been
+ *  replaced (mocks/instrumentation). */
+export function keepAliveFetch(url, init) {
+    if (globalThis.fetch !== nativeFetch) {
+        return globalThis.fetch(url, init);
+    }
+    if (!cached)
+        cached = build();
+    return cached(url, init);
+}

package/assets/plugin/index.js

@@ -989,7 +989,10 @@ const paperTradingPlugin = {
         // gateway process must reload it before serving HTTP API calls.
         const reloadState = () => {
             try {
-                const fresh = stateManager.loadSync();
+                // Skips the full read+parse (and replaceState) when the on-disk file
+                // hasn't changed since the last load — this runs on every paper-mode
+                // tool call and the file grows with trade history.
+                const fresh = stateManager.loadSyncIfChanged();
                 if (fresh) {
                     simulator.replaceState(fresh);
                 }
@@ -1293,11 +1296,32 @@ const paperTradingPlugin = {
         // rows while collecting real ones). See docs/APPROVAL_MODE_DESIGN.md §12.
         const approvalShadowEnabled = (process.env.APPROVAL_SHADOW_MODE ?? '').trim() === '1';
         const resolveApprovalMode = () => {
-            try {
-                if (readPluginConfig().approval?.mode === 'per_trade')
-                    return 'per_trade';
+            // Precedence (config-service slice 4, mirrors loadExitGateMode /
+            // loadPositionReviewMode):
+            //
+            //   central (agent_config.gates.approvalMode) → plugin-config.json →
+            //   APPROVAL_SHADOW_MODE env → 'off'
+            //
+            // Central is enum-validated plugin-side (agent-config-client
+            // validateGates) and can only ever say 'off' | 'per_trade' — it cannot
+            // enable shadow telemetry and cannot weaken the safety floor. Kill-switch
+            // RC_CENTRAL_GATES=off makes the store report null and the file rules
+            // again. Read per call, so a dashboard flip applies within one poll
+            // (~60 s) with no restart.
+            const central = gateStore.getApprovalMode();
+            if (central === 'per_trade')
+                return 'per_trade';
+            if (central !== 'off') {
+                // No central value — fall back to the local file.
+                try {
+                    if (readPluginConfig().approval?.mode === 'per_trade')
+                        return 'per_trade';
+                }
+                catch { /* config unreadable — env-only fallback below */ }
             }
-            catch { /* config unreadable — env-only fallback below */ }
+            // Central 'off' still permits local shadow telemetry: shadow does not
+            // change trading behaviour (the order fires either way), it only writes
+            // an extra row, and the env flag is the operator's own local choice.
             return approvalShadowEnabled ? 'shadow' : 'off';
         };
         // Proposal manager + listener credentials: built whenever ingest
@@ -1327,8 +1351,18 @@ const paperTradingPlugin = {
                     logger.info(TAG, `Approval wiring active (mode=${bootApprovalMode}) → ${ingestBaseUrl} (userId=${reefclawUserId.slice(0, 8)}…)`);
                 }
             }
+            else if (bootApprovalMode === 'per_trade') {
+                // FAIL-CLOSED state: create_order will REFUSE every new entry until the
+                // credentials are restored or approval.mode is set back to off. Loud at
+                // boot AND at each refusal (create-order.ts) — a boot-only signal is how
+                // this used to go unnoticed while orders fired without the gate.
+                logger.error(TAG, `approval mode=per_trade but ingest token / REEFCLAW_USER_ID missing — proposals CANNOT ` +
+                    `reach the operator, so create_order will REFUSE every new entry (fail-closed). ` +
+                    `Restore the plugin connectionToken/WEBAPP_INGEST_TOKEN + REEFCLAW_USER_ID, or set ` +
+                    `approval.mode=off. Exits, stops, brackets and operator controls are unaffected.`);
+            }
             else if (bootApprovalMode !== 'off') {
-                logger.warn(TAG, `approval mode=${bootApprovalMode} but ingest token / REEFCLAW_USER_ID missing — proposal path disabled (orders fire directly)`);
+                logger.warn(TAG, `approval mode=${bootApprovalMode} but ingest token / REEFCLAW_USER_ID missing — shadow telemetry disabled (orders fire directly, as in off mode)`);
             }
         }
         // ---- Create exchange adapter based on trading mode ----
@@ -1384,6 +1418,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,
                         },
                     }
                     : {
@@ -1887,6 +1926,14 @@ const paperTradingPlugin = {
                     pollIntervalMs: approvalCfg?.pollIntervalMs ?? 3_000,
                 });
             },
+            // The approval path just went away (mode flipped off, or live→PAPER).
+            // Anything still pending is now un-fireable but still shows an Approve
+            // button — cancel it rather than leave the operator a dead control.
+            onApprovalPathDisabled: async () => {
+                if (!proposalManagerCtx)
+                    return;
+                await proposalManagerCtx.manager.cancelAll(proposalManagerCtx.userId, 'mode_disabled');
+            },
         });
         runtime.setOnAdapterSwapped((a) => { void approvalLifecycle.onAdapterSwapped(a); });
         // Boot application — the same path every later swap takes.

package/assets/plugin/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';
@@ -627,7 +627,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 +649,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,

package/assets/plugin/ingest/position-decisions-client.d.ts

@@ -322,6 +322,12 @@ export declare class PositionDecisionsClient {
     private fireAndForget;
     private run;
     private runReturning;
+    /** Decision-path GET budget. Every read caller degrades to empty/null on
+     *  failure, so burning the write-grade budget (4 × 10s + backoff ≈ 42s
+     *  worst case) of the agent's turn to reach an optional result is pure
+     *  heartbeat latency. Background reads (reconcile sweep) override per call. */
+    private static readonly READ_MAX_ATTEMPTS;
+    private static readonly READ_DEADLINE_MS;
     private runGetReturning;
     private sleepBackoff;
 }

package/assets/plugin/ingest/position-decisions-client.js

@@ -12,6 +12,7 @@
 //   - postEntry/Review/Close are fire-and-forget (don't block the WS hot path).
 //
 // All four routes accept the same auth: Bearer + X-User-Id headers.
+import { keepAliveFetch } from '../http/keepalive-fetch.js';
 import { logger, formatError } from '../logger.js';
 const TAG = 'position-decisions-client';
 export class PositionDecisionsClient {
@@ -25,7 +26,7 @@ export class PositionDecisionsClient {
         this.opts = {
             baseUrl: options.baseUrl.replace(/\/+$/, ''),
             ingestToken: options.ingestToken,
-            fetchImpl: options.fetchImpl ?? fetch,
+            fetchImpl: options.fetchImpl ?? keepAliveFetch,
             requestTimeoutMs: options.requestTimeoutMs ?? 10_000,
             maxAttempts: options.maxAttempts ?? 4,
             baseBackoffMs: options.baseBackoffMs ?? 250,
@@ -65,7 +66,12 @@ export class PositionDecisionsClient {
             qs.set('mode', mode);
         if (exchange)
             qs.set('exchange', exchange);
-        return this.runGetReturning(userId, `/api/internal/positions?${qs.toString()}`);
+        return this.runGetReturning(userId, `/api/internal/positions?${qs.toString()}`, {
+            // Reconcile-sweep read, NOT on the agent decision path — keep the
+            // write-grade retry budget: a null here skips a whole reconcile pass.
+            maxAttempts: this.opts.maxAttempts,
+            deadlineMs: Number.POSITIVE_INFINITY,
+        });
     }
     /** Read endpoint for the Phase 1 self-reflection feature. Awaited.
      *  Returns null on terminal/retry-exhausted failure (caller logs + degrades). */
@@ -246,12 +252,24 @@ export class PositionDecisionsClient {
         logger.error(TAG, `POST ${url} dropped after ${this.opts.maxAttempts} attempts. userId=${userId}.`);
         return null;
     }
-    async runGetReturning(userId, path) {
+    /** Decision-path GET budget. Every read caller degrades to empty/null on
+     *  failure, so burning the write-grade budget (4 × 10s + backoff ≈ 42s
+     *  worst case) of the agent's turn to reach an optional result is pure
+     *  heartbeat latency. Background reads (reconcile sweep) override per call. */
+    static READ_MAX_ATTEMPTS = 2;
+    static READ_DEADLINE_MS = 8_000;
+    async runGetReturning(userId, path, budget) {
         const url = `${this.opts.baseUrl}${path}`;
-        for (let attempt = 1; attempt <= this.opts.maxAttempts; attempt++) {
+        const maxAttempts = budget?.maxAttempts ??
+            Math.min(this.opts.maxAttempts, PositionDecisionsClient.READ_MAX_ATTEMPTS);
+        const deadlineAt = Date.now() + (budget?.deadlineMs ?? PositionDecisionsClient.READ_DEADLINE_MS);
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            const remainingMs = deadlineAt - Date.now();
+            if (remainingMs <= 0)
+                break;
             try {
                 const ac = new AbortController();
-                const tid = setTimeout(() => ac.abort(), this.opts.requestTimeoutMs);
+                const tid = setTimeout(() => ac.abort(), Math.min(this.opts.requestTimeoutMs, remainingMs));
                 let res;
                 try {
                     res = await this.opts.fetchImpl(url, {
@@ -285,16 +303,16 @@ export class PositionDecisionsClient {
                     logger.warn(TAG, `GET ${url} → ${res.status} (terminal, dropped). userId=${userId} body=${errBody.slice(0, 200)}`);
                     return null;
                 }
-                logger.warn(TAG, `GET ${url} → ${res.status} (attempt ${attempt}/${this.opts.maxAttempts}).`);
+                logger.warn(TAG, `GET ${url} → ${res.status} (attempt ${attempt}/${maxAttempts}).`);
             }
             catch (err) {
-                logger.warn(TAG, `GET ${url} threw (attempt ${attempt}/${this.opts.maxAttempts}): ${formatError(err)}`);
+                logger.warn(TAG, `GET ${url} threw (attempt ${attempt}/${maxAttempts}): ${formatError(err)}`);
             }
-            if (attempt < this.opts.maxAttempts) {
+            if (attempt < maxAttempts && Date.now() < deadlineAt) {
                 await this.sleepBackoff(attempt);
             }
         }
-        logger.error(TAG, `GET ${url} failed after ${this.opts.maxAttempts} attempts. userId=${userId}.`);
+        logger.error(TAG, `GET ${url} failed after ${maxAttempts} attempt(s)/deadline. userId=${userId}.`);
         return null;
     }
     async sleepBackoff(attempt) {

package/assets/plugin/live/approval-lifecycle.d.ts

@@ -14,6 +14,16 @@ export interface ApprovalLifecycleDeps {
     hasWiring: () => boolean;
     /** Build a listener bound to THIS adapter. Called only when starting. */
     buildListener: (adapter: IExchangeAdapter) => StartableListener;
+    /** Called when a RUNNING listener was torn down and no replacement started —
+     *  i.e. the approval path was deliberately disabled (mode flipped away from
+     *  per_trade, or the live adapter went away). Any proposal still pending is
+     *  now un-fireable but still approvable on the dashboard, so the caller
+     *  cancels them (design doc §10 row 12).
+     *
+     *  Deliberately NOT called from stop() — a shutdown drain is a restart, not a
+     *  disable, and cancelling the operator's live proposals on every plugin
+     *  restart would be both wrong and obnoxious. */
+    onApprovalPathDisabled?: () => void | Promise<void>;
 }
 export declare class ApprovalListenerLifecycle {
     private readonly deps;

package/assets/plugin/live/approval-lifecycle.js

@@ -52,14 +52,28 @@ export class ApprovalListenerLifecycle {
         return this.chain;
     }
     async apply(adapter) {
+        // A listener was running before this swap? Then if we end up NOT starting a
+        // replacement, whatever is still pending has been orphaned.
+        const hadListener = this.listener !== undefined;
         // Always tear down the previous listener first — it is bound to the OLD
         // adapter and must never fire through it again.
         await this.stopCurrent();
+        const orphaned = async (why) => {
+            if (!hadListener || !this.deps.onApprovalPathDisabled)
+                return;
+            logger.info(TAG, `approval path disabled (${why}) — cancelling any pending proposals`);
+            try {
+                await this.deps.onApprovalPathDisabled();
+            }
+            catch (err) {
+                logger.warn(TAG, `pending-proposal cancel failed: ${formatError(err)}`);
+            }
+        };
         if (!adapter.isLive)
-            return;
+            return orphaned('adapter is no longer live');
         const mode = this.deps.resolveApprovalMode();
         if (mode !== 'per_trade')
-            return;
+            return orphaned(`approval.mode=${mode}`);
         if (!this.deps.hasWiring()) {
             logger.warn(TAG, "approval.mode='per_trade' but ingest credentials/proposal manager missing — listener NOT started; approvals will not fire");
             return;

package/assets/plugin/live/microstructure-assembler.js

@@ -66,9 +66,18 @@ export class IntelMicrostructureAssembler {
             return cached.block;
         // Map canonical "BTC/USDT" → intel "BTCUSDT".
         const intelSymbol = canonical.replace('/', '');
+        // cacheTtlMs mirrors the agent-facing tools (get_resting_liquidity /
+        // get_liquidation_pulse) so the assembler and the agent's own calls share
+        // one round-trip per heartbeat instead of duplicate-fetching.
         const [restingResult, pulseResult] = await Promise.allSettled([
-            fetchIntelApi(`/api/resting-liquidity/${enc(intelSymbol)}`, this.intelDeps),
-            fetchIntelApi(`/api/liquidation-pulse?symbol=${enc(intelSymbol)}&window_seconds=60`, this.intelDeps),
+            fetchIntelApi(`/api/resting-liquidity/${enc(intelSymbol)}`, this.intelDeps, {
+                cacheTtlMs: 15_000,
+                timeoutMs: 10_000,
+            }),
+            fetchIntelApi(`/api/liquidation-pulse?symbol=${enc(intelSymbol)}&window_seconds=60`, this.intelDeps, {
+                cacheTtlMs: 10_000,
+                timeoutMs: 10_000,
+            }),
         ]);
         const block = { symbol: canonical, updatedAt: ts };
         let anySignal = false;