@reefclaw/openclaw-plugin 0.1.12 → 0.1.14

package/ingest/event-loop-monitor.js

@@ -0,0 +1,113 @@
+// Event-loop delay monitor — the signal that tells "this process was frozen"
+// apart from "the venue was unreachable" (issue #265).
+//
+// Why this exists: the readiness probe wraps its request in a 10s abort timer.
+// When the HOST starves the process (CPU contention, a neighbouring container
+// leaking into swap), the loop stops running — the request never gets a fair
+// chance and the abort fires late. The old code fell into one catch and blamed
+// the venue, producing a false "cannot reach the API — check DNS/firewall"
+// banner. Live evidence on the HL rig: a 10s timer that fired 86s late, with
+// OpenClaw's own diagnostic recording loop delays up to 556s at 2-17% of one
+// core (loop runnable, never scheduled).
+//
+// perf_hooks.monitorEventLoopDelay samples libuv timer lag into an
+// IntervalHistogram. Its internal timer does NOT hold the process open, and
+// every entry point is wrapped so a failure here can never break readiness
+// reporting — an unavailable monitor reports `null` (⇒ 'unknown'), never a
+// fabricated zero.
+// ★ Static import, NOT require(): this package is ESM ("type":"module" +
+// module:ES2022), so tsc emits a bare `require` verbatim and Node throws
+// ReferenceError on it. The throw landed in the catch below, which set
+// initFailed and disabled the monitor FOREVER — the check would have reported
+// 'unknown' on every cycle in production while every test passed (vitest's
+// CJS interop defines `require`). node:perf_hooks is a builtin with no
+// CJS-shape problem, so there is nothing here to defer: the ccxt-style
+// createRequire dance exists for that dependency's module shape, not for
+// builtins. See docs/CLAUDE/plugin-integration.md.
+import { monitorEventLoopDelay } from 'node:perf_hooks';
+import { logger } from '../logger.js';
+const TAG = 'event-loop-monitor';
+/** Sampling resolution. 20ms is fine-grained enough to catch a real stall
+ *  without meaningful overhead — we only ever read the MAX. */
+const RESOLUTION_MS = 20;
+/** How long after enabling before a reading means anything.
+ *
+ *  ★ The histogram is BLIND to a block that happens in the same tick as
+ *  `enable()`: Node baselines it at its first internal timer fire, not at the
+ *  enable call, so a stall that predates that fire is never attributed.
+ *  Measured (node 22): identical 300ms block reads 30ms when it runs in the
+ *  enable tick vs 300ms once the loop has turned. The floor it reports instead
+ *  (~30ms on Windows, the timer-coalescing noise) looks exactly like a healthy
+ *  host — a `pass` from a measurement that CANNOT fail, which is the same
+ *  false-green this check exists to kill. So we withhold judgement until the
+ *  histogram's own timer has fired: this delay is > 2× RESOLUTION_MS, and a
+ *  starved loop only pushes it later, never earlier. */
+const ARM_DELAY_MS = 50;
+let histogram = null;
+let initFailed = false;
+/** False until the histogram can actually attribute a stall (see ARM_DELAY_MS).
+ *  While false, sampling reports `null` ⇒ 'unknown' rather than the floor. */
+let armed = false;
+/** Lazily create + enable the histogram. Returns null if the runtime refuses
+ *  one (never throws — readiness must survive a missing monitor). */
+function getHistogram() {
+    if (histogram || initFailed)
+        return histogram;
+    try {
+        const h = monitorEventLoopDelay({ resolution: RESOLUTION_MS });
+        h.enable();
+        histogram = h;
+        // unref'd: arming must never be a reason the process stays alive.
+        const t = setTimeout(() => {
+            armed = true;
+        }, ARM_DELAY_MS);
+        t.unref?.();
+        return histogram;
+    }
+    catch (err) {
+        initFailed = true;
+        logger.warn(TAG, `event-loop monitor unavailable (host-responsiveness check will report unknown): ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+}
+/** Start sampling. Safe to call repeatedly (idempotent). */
+export function startEventLoopMonitor() {
+    getHistogram();
+}
+/** Worst event-loop delay (ms) observed since the previous call, then reset —
+ *  so consecutive calls partition the timeline into non-overlapping windows.
+ *  Returns null when the monitor is unavailable or has no sample yet.
+ *
+ *  The histogram stores nanoseconds; `max` is Infinity-safe but can read as a
+ *  sentinel before the first sample lands, so anything non-finite → null. */
+export function sampleEventLoopDelayMs() {
+    const h = getHistogram();
+    if (!h)
+        return null;
+    // Not yet able to measure — report 'unknown' rather than the idle floor, which
+    // would read as a healthy host on a boot cycle that never observed anything.
+    if (!armed)
+        return null;
+    try {
+        const maxNs = Number(h.max);
+        h.reset();
+        if (!Number.isFinite(maxNs) || maxNs < 0)
+            return null;
+        return maxNs / 1e6;
+    }
+    catch {
+        return null;
+    }
+}
+/** Test-only — drop the singleton so a fresh histogram is created. */
+export function __resetEventLoopMonitorForTests() {
+    try {
+        histogram?.disable();
+    }
+    catch {
+        /* ignore */
+    }
+    histogram = null;
+    initFailed = false;
+    armed = false;
+}

package/ingest/position-auto-capture.d.ts

@@ -105,6 +105,11 @@ export interface StopWatcherCloseInputs {
     symbol: string;
     stopPrice: number;
     markPrice: number;
+    /** Which protective leg fired. Defaults to the stop (the historical caller).
+     *  'exchange_target' is the paper take-profit leg — the same journal path,
+     *  because a target close bypasses close_position exactly like a stop does
+     *  and would otherwise leave a phantom-open row (issue #199). */
+    leg?: 'stop_watcher' | 'exchange_target';
     /** The executed close order from adapter.closePosition (may be absent if the
      *  close resolved through a path that didn't surface it). */
     order?: CcxtOrder;

package/ingest/position-auto-capture.js

@@ -22,6 +22,7 @@ import { logger } from '../logger.js';
 import { isBracketCid } 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';
 const TAG = 'position-auto-capture';
 /** Flatness tolerance for remaining-contracts tracking. Reduce-only fills sum
  *  exactly to the position size on Binance, so any residual below this is noise
@@ -428,14 +429,19 @@ export async function onStopWatcherClose(ctx, inputs) {
         dropState();
         return;
     }
+    const leg = inputs.leg ?? 'stop_watcher';
     const close = {
         positionId: stateEntry.webappPositionId,
         closeAt: closeAtMs,
-        closeReason: 'stop_watcher',
+        closeReason: leg,
         closeAssessment: {
-            note: 'Position auto-closed by the stop-watcher: mark crossed the pinned stopPrice. ' +
-                'Journaled from the watcher close fill — no close_position call (issue #199).',
-            observedFrom: 'stop_watcher',
+            note: leg === 'exchange_target'
+                ? 'Position auto-closed by the paper take-profit leg: price reached the pinned targetPrice. ' +
+                    'The live analog is an exchange-native TAKE_PROFIT_MARKET fill. Journaled from the close ' +
+                    'fill — no close_position call.'
+                : 'Position auto-closed by the stop-watcher: mark crossed the pinned stopPrice. ' +
+                    'Journaled from the watcher close fill — no close_position call (issue #199).',
+            observedFrom: leg,
             stop_price: inputs.stopPrice,
             mark_price: inputs.markPrice,
             ...(paperTrade
@@ -669,7 +675,10 @@ function buildEntryPayload(args) {
         fillPrice: args.fillPrice,
         fillSize: args.fillSize,
         exchangeTradeId: args.exchangeTradeId,
-        metadata: buildEntryPlanMetadata(md),
+        // skill_version stamp: makes every SKILL.md release measurable against
+        // outcomes (capture ratio / scratch rate per doctrine version). Fail-soft —
+        // unreadable/absent SKILL.md just omits the key.
+        metadata: withSkillVersion(buildEntryPlanMetadata(md), getSkillVersionCached()),
     };
 }
 /** Pinned-plan subset persisted to position_entries.metadata (free-form JSONB).

package/ingest/readiness-reporter.d.ts

@@ -1,12 +1,16 @@
-import { type ReadinessReport, type VenueId } from '@reefclaw/shared';
+import { type ReadinessReport, type VenueId, type VenueReachabilityResult } from '@reefclaw/shared';
 /** Venue-agnostic reachability probe — BinancePublicApi.probeReachability and
  *  HyperliquidPublicApi.probeReachability both return exactly this shape. */
 export interface VenueReachabilityProbe {
-    probeReachability(): Promise<{
-        outcome: 'reachable' | 'geo_blocked' | 'unreachable' | 'unknown';
-        driftMs: number | null;
-    }>;
+    probeReachability(): Promise<VenueReachabilityResult>;
 }
+/** Cross-cycle memory for the debounced rungs. Held by the interval loop and
+ *  passed in explicitly so `collectReadiness` stays a pure function of its
+ *  inputs — a module-global counter would leak between unit tests. */
+export interface ReadinessCycleState {
+    consecutiveReachFailures: number;
+}
+export declare function createReadinessCycleState(): ReadinessCycleState;
 export interface ReadinessReporterOptions {
     apiBaseUrl: string;
     token: string;
@@ -35,7 +39,14 @@ export interface ReadinessReporterOptions {
  *  warn/fail drift is reported 'unknown' (not amber/red) so the readiness
  *  banner doesn't cry-wolf for ~5 min after every restart; a genuinely
  *  skewed clock still surfaces on cycle 2. */
-export declare function collectReadiness(opts: Pick<ReadinessReporterOptions, 'venue' | 'publicApi' | 'toolCount'>, bootWarmup?: boolean): Promise<ReadinessReport>;
+export declare function collectReadiness(opts: Pick<ReadinessReporterOptions, 'venue' | 'publicApi' | 'toolCount'>, bootWarmup?: boolean, deps?: {
+    /** Debounce memory. Omitted → a fresh state, so a lone unreachable reads
+     *  `unknown`; only a caller that persists state across cycles can ever
+     *  reach the warn rung. */
+    state?: ReadinessCycleState;
+    /** Injected for tests; production reads the real event-loop histogram. */
+    sampleHostStallMs?: () => number | null;
+}): Promise<ReadinessReport>;
 /** Test-only — reset the singleton guard between unit tests. */
 export declare function __resetReadinessReporterForTests(): void;
 /** Fire the readiness report once at boot then on an unref'd interval. */

package/ingest/readiness-reporter.js

@@ -8,13 +8,26 @@
 // module-level singleton guard mirrors `pluginInitialised` in index.ts — OpenClaw
 // calls register() multiple times per process and we must never spawn a second
 // timer. The interval is unref()'d so it never holds the process open.
-import { makeReadinessCheck, deriveOverallReadiness, } from '@reefclaw/shared';
+import { makeReadinessCheck, deriveOverallReadiness, GEO_BLOCK_FIX_HINT, } from '@reefclaw/shared';
 import { logger, formatError } from '../logger.js';
+import { startEventLoopMonitor, sampleEventLoopDelayMs } from './event-loop-monitor.js';
 const TAG = 'readiness';
 const DEFAULT_INTERVAL_MS = 300_000; // 5 min — geo/clock state changes rarely.
 const MIN_INTERVAL_MS = 60_000;
 /** Best-effort display fact; kept in sync with the register() banner in index.ts. */
 const PLUGIN_VERSION = '3.8.0';
+/** Consecutive non-pass reachability probes required before the banner goes
+ *  amber. One 5-min sample is not enough evidence to send an operator hunting a
+ *  network fault — the intel-health AMBER rung already debounces the same way
+ *  (docs/CLAUDE/intel-health.md), readiness had no equivalent (issue #265). */
+const REACH_WARN_AFTER_FAILURES = 2;
+/** Worst event-loop delay in a cycle that still counts as a responsive host.
+ *  Well above ordinary GC/boot jitter (tens to low hundreds of ms) and far
+ *  below the freezes worth alarming on — the live incident produced 89s-556s. */
+const HOST_STALL_WARN_MS = 5_000;
+export function createReadinessCycleState() {
+    return { consecutiveReachFailures: 0 };
+}
 function resolveIntervalMs(explicit) {
     if (explicit && explicit > 0)
         return Math.max(MIN_INTERVAL_MS, explicit);
@@ -34,9 +47,11 @@ function resolveIntervalMs(explicit) {
  *  warn/fail drift is reported 'unknown' (not amber/red) so the readiness
  *  banner doesn't cry-wolf for ~5 min after every restart; a genuinely
  *  skewed clock still surfaces on cycle 2. */
-export async function collectReadiness(opts, bootWarmup = false) {
+export async function collectReadiness(opts, bootWarmup = false, deps = {}) {
     const now = Date.now();
     const checks = [];
+    const state = deps.state ?? createReadinessCycleState();
+    const sampleStall = deps.sampleHostStallMs ?? sampleEventLoopDelayMs;
     // The venue decides which reachability check this report carries; the copy
     // for both ids lives in shared/src/readiness.ts. Clock drift comes from the
     // same probe on both venues (Binance fapi serverTime / Hyperliquid
@@ -50,9 +65,41 @@ export async function collectReadiness(opts, bootWarmup = false) {
         detail: `${opts.toolCount} tools`,
         checkedAt: now,
     }));
-    // venue reachability (+ clock drift from the same probe response)
+    // ★ Probe FIRST, sample the loop delay AFTER. The freeze that makes a probe
+    // abort happens *during* the probe, so sampling first would file the evidence
+    // in the NEXT cycle's window — reachability would read 'stalled' this cycle
+    // while host_responsive still read 'pass', putting the two halves of one
+    // incident 5 minutes apart. The checks are still pushed in display order.
     const probe = await opts.publicApi.probeReachability();
+    // host_responsive — the signal that actually matters on a trading rig, and the
+    // one whose absence let a starved host masquerade as an unreachable venue.
+    // A null sample means the monitor is unavailable or has no window yet: report
+    // 'unknown', never a fabricated healthy zero — except that a probe which
+    // measured its own overshoot IS a stall measurement, so it stands in.
+    const stallMs = sampleStall() ?? (probe.outcome === 'stalled' ? (probe.stallMs ?? null) : null);
+    if (stallMs == null) {
+        checks.push(makeReadinessCheck('host_responsive', 'unknown', { checkedAt: now }));
+    }
+    else {
+        const rawStatus = stallMs < HOST_STALL_WARN_MS ? 'pass' : 'warn';
+        // Boot congestion (WS start, snapshot, seed all racing) legitimately stalls
+        // the loop for seconds — same warm-up rule as the clock check below.
+        const status = bootWarmup && rawStatus !== 'pass' ? 'unknown' : rawStatus;
+        checks.push(makeReadinessCheck('host_responsive', status, {
+            detail: rawStatus === 'pass'
+                ? `max loop delay ${Math.round(stallMs)}ms`
+                : bootWarmup
+                    ? `froze ${(stallMs / 1000).toFixed(1)}s (boot warm-up — rechecking)`
+                    : `froze ${(stallMs / 1000).toFixed(1)}s`,
+            checkedAt: now,
+        }));
+        if (rawStatus !== 'pass' && !bootWarmup) {
+            logger.warn(TAG, `host starved: event loop froze ${(stallMs / 1000).toFixed(1)}s this cycle — order handling and bracket resync can lag by that much`);
+        }
+    }
+    // venue reachability (+ clock drift from the same probe response)
     if (probe.outcome === 'reachable') {
+        state.consecutiveReachFailures = 0;
         checks.push(makeReadinessCheck(reachId, 'pass', { checkedAt: now }));
         const drift = probe.driftMs;
         if (drift == null) {
@@ -74,21 +121,47 @@ export async function collectReadiness(opts, bootWarmup = false) {
         }
     }
     else if (probe.outcome === 'geo_blocked') {
+        // The venue ANSWERED (451/403) — so the host reached it, and this is the one
+        // reachability verdict we may state as a cause. Clears the debounce counter
+        // and carries the assertive copy rather than the cautious default.
+        state.consecutiveReachFailures = 0;
         checks.push(makeReadinessCheck(reachId, 'fail', {
             detail: opts.venue === 'binance' ? 'HTTP 451' : 'blocked (HTTP 451/403)',
+            fixHint: GEO_BLOCK_FIX_HINT[opts.venue === 'binance' ? 'binance' : 'hyperliquid'],
+            checkedAt: now,
+        }));
+        checks.push(makeReadinessCheck('clock_in_sync', 'unknown', { checkedAt: now }));
+    }
+    else if (probe.outcome === 'stalled') {
+        // ★ Our own process was starved, so the probe proves nothing about the venue
+        // (issue #265). Report 'unknown' — which never turns the banner amber — and
+        // leave the debounce counter untouched: a non-observation is not evidence
+        // either way. host_responsive above carries the signal that IS actionable.
+        const secs = probe.stallMs != null ? (probe.stallMs / 1000).toFixed(1) : '?';
+        checks.push(makeReadinessCheck(reachId, 'unknown', {
+            detail: `not measurable — agent host froze ${secs}s`,
             checkedAt: now,
         }));
         checks.push(makeReadinessCheck('clock_in_sync', 'unknown', { checkedAt: now }));
     }
     else if (probe.outcome === 'unreachable') {
-        // Network/DNS/timeout — could be transient, so warn (amber) rather than
-        // asserting a definitive failure. A persistent problem stays amber across
-        // re-checks; only the geo-block is a hard red.
-        checks.push(makeReadinessCheck(reachId, 'warn', { detail: 'unreachable', checkedAt: now }));
+        // Network/DNS/timeout. Debounced: one 5-min sample is not enough to alarm,
+        // so the first failure reports 'unknown' and only a SECOND consecutive one
+        // goes amber. A persistent problem stays amber across re-checks; only the
+        // geo-block is a hard red.
+        state.consecutiveReachFailures += 1;
+        const confirmed = state.consecutiveReachFailures >= REACH_WARN_AFTER_FAILURES;
+        checks.push(makeReadinessCheck(reachId, confirmed ? 'warn' : 'unknown', {
+            detail: confirmed
+                ? `unreachable (${state.consecutiveReachFailures} consecutive checks)`
+                : 'one failed check — rechecking',
+            checkedAt: now,
+        }));
         checks.push(makeReadinessCheck('clock_in_sync', 'unknown', { checkedAt: now }));
     }
     else {
-        // 'unknown' — the ban/weight gate paused the probe; don't assert anything.
+        // 'unknown' — the ban/weight gate paused the probe; don't assert anything,
+        // and don't let a non-observation move the debounce counter.
         checks.push(makeReadinessCheck(reachId, 'unknown', { checkedAt: now }));
         checks.push(makeReadinessCheck('clock_in_sync', 'unknown', { checkedAt: now }));
     }
@@ -142,9 +215,15 @@ export function startReadinessReporter(opts) {
     const fetchImpl = opts.fetchImpl ?? fetch;
     const intervalMs = resolveIntervalMs(opts.intervalMs);
     const timeoutMs = opts.requestTimeoutMs ?? 10_000;
+    // Start sampling loop delay now so the first cycle measures a real window.
+    // Never throws — an unavailable monitor just reports host_responsive unknown.
+    startEventLoopMonitor();
+    // One state object for the process: the debounce rungs are only meaningful
+    // across cycles.
+    const state = createReadinessCycleState();
     const cycle = async (bootWarmup) => {
         try {
-            const report = await collectReadiness({ venue: opts.venue, publicApi: opts.publicApi, toolCount: opts.toolCount }, bootWarmup);
+            const report = await collectReadiness({ venue: opts.venue, publicApi: opts.publicApi, toolCount: opts.toolCount }, bootWarmup, { state });
             await postReadiness(opts.apiBaseUrl, opts.token, report, fetchImpl, timeoutMs);
             if (report.overall === 'fail') {
                 const failing = report.checks.filter((c) => c.status === 'fail').map((c) => c.id).join(', ');

package/ingest/skill-version-reader.d.ts

@@ -0,0 +1,16 @@
+/** Pure parse — exported for tests. Only the first 4 KB is considered. */
+export declare function parseSkillVersion(content: string): string | undefined;
+/**
+ * Read the running SKILL.md version, cached until the file changes.
+ * Returns undefined when the file is absent, unreadable, or has no parseable
+ * frontmatter version — callers omit the stamp in that case.
+ */
+export declare function getSkillVersionCached(filePath?: string): string | undefined;
+/**
+ * Merge the skill-version stamp into an entry-metadata object.
+ * Key is snake_case (`skill_version`) per the canonical-JSONB-key rule
+ * (CLAUDE.md learning-loop: a camelCase mismatch previously broke matching).
+ * No version → base returned untouched (possibly undefined), so rows never
+ * gain an empty/noise object just for a failed read.
+ */
+export declare function withSkillVersion(meta: Record<string, unknown> | undefined, version: string | undefined): Record<string, unknown> | undefined;

package/ingest/skill-version-reader.js

@@ -0,0 +1,64 @@
+// Best-effort reader for the SKILL.md version the agent is actually running.
+//
+// Purpose: stamp `skill_version` into position_entries.metadata so every
+// doctrine (SKILL.md) release becomes measurable against trade outcomes —
+// capture ratio / scratch rate per version — the same shadow→observe→enforce
+// evidence discipline the repo applies to code gates, applied to the prose.
+// Without this stamp a SKILL.md change is fleet-wide AND unmeasurable: journal
+// rows from before and after the change are indistinguishable.
+//
+// Source of truth: ~/.openclaw/workspace/SKILL.md — the copy the bridge's
+// applySkillUpdate maintains and the agent's OpenClaw loads (same path as
+// skill/src/utils/skill-version.ts SKILL_MD_PATH; duplicated here because
+// plugin and skill are separate deliverables with no shared package).
+//
+// Fail-soft by design: absent/unreadable/unparseable file → undefined → the
+// metadata key is simply omitted. Journal capture must never block or throw
+// on this read (same rule as the rest of the capture path).
+import { readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const DEFAULT_SKILL_MD_PATH = join(homedir(), '.openclaw', 'workspace', 'SKILL.md');
+/** Frontmatter version line, e.g. `version: 2.20.11`. Anchored to the head of
+ *  the file (frontmatter is lines 1-10) so a `version:` string later in the
+ *  body can never shadow it. */
+const VERSION_LINE = /^version:\s*(\d+\.\d+\.\d+)\s*$/m;
+const HEAD_BYTES = 4096;
+/** Pure parse — exported for tests. Only the first 4 KB is considered. */
+export function parseSkillVersion(content) {
+    return VERSION_LINE.exec(content.slice(0, HEAD_BYTES))?.[1];
+}
+/** mtime+size-keyed cache per path. Entries are rare (a handful a day), but a
+ *  cached hit avoids re-reading 110 KB on every fill during a busy burst. */
+const cache = new Map();
+/**
+ * Read the running SKILL.md version, cached until the file changes.
+ * Returns undefined when the file is absent, unreadable, or has no parseable
+ * frontmatter version — callers omit the stamp in that case.
+ */
+export function getSkillVersionCached(filePath = DEFAULT_SKILL_MD_PATH) {
+    try {
+        const st = statSync(filePath);
+        const hit = cache.get(filePath);
+        if (hit && hit.mtimeMs === st.mtimeMs && hit.size === st.size)
+            return hit.v;
+        const v = parseSkillVersion(readFileSync(filePath, 'utf8'));
+        cache.set(filePath, { v, mtimeMs: st.mtimeMs, size: st.size });
+        return v;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Merge the skill-version stamp into an entry-metadata object.
+ * Key is snake_case (`skill_version`) per the canonical-JSONB-key rule
+ * (CLAUDE.md learning-loop: a camelCase mismatch previously broke matching).
+ * No version → base returned untouched (possibly undefined), so rows never
+ * gain an empty/noise object just for a failed read.
+ */
+export function withSkillVersion(meta, version) {
+    if (!version)
+        return meta;
+    return { ...(meta ?? {}), skill_version: version };
+}

package/live/approval-lifecycle.d.ts

@@ -0,0 +1,30 @@
+import type { IExchangeAdapter } from '../exchange-adapter.js';
+/** The slice of ProposalDecisionListener this class needs — injected so the
+ *  lifecycle is testable without gateway credentials. */
+export interface StartableListener {
+    start(): void;
+    stop(): Promise<void>;
+}
+export interface ApprovalLifecycleDeps {
+    /** Re-read config+env — NOT a boot snapshot; a config edit applies on the
+     *  next swap without a restart. */
+    resolveApprovalMode: () => 'off' | 'shadow' | 'per_trade';
+    /** Ingest credentials + proposal manager present? Without them a listener
+     *  cannot claim or report — refuse to start rather than half-run. */
+    hasWiring: () => boolean;
+    /** Build a listener bound to THIS adapter. Called only when starting. */
+    buildListener: (adapter: IExchangeAdapter) => StartableListener;
+}
+export declare class ApprovalListenerLifecycle {
+    private readonly deps;
+    private listener;
+    private chain;
+    constructor(deps: ApprovalLifecycleDeps);
+    get active(): boolean;
+    /** Apply the lifecycle for a freshly published adapter. Serialized. */
+    onAdapterSwapped(adapter: IExchangeAdapter): Promise<void>;
+    /** Terminal stop (shutdown drain) — also serialized behind pending swaps. */
+    stop(): Promise<void>;
+    private apply;
+    private stopCurrent;
+}

package/live/approval-lifecycle.js

@@ -0,0 +1,80 @@
+// Approval-listener lifecycle — follows adapter swaps instead of boot state
+// (audit 2026-07-26 F10).
+//
+// The ProposalDecisionListener used to start ONCE at boot, only when the
+// process booted live with approval.mode='per_trade'. Every real trader
+// onboards in PAPER and goes live later from the dashboard, so on their box
+// the listener never existed — approvals would sit unfired. Worse, the
+// listener held the adapter it was CONSTRUCTED with: a live→PAPER flip left
+// it wired to the orphaned live adapter (an operator approval would fire a
+// real exchange order while the dashboard said PAPER), and a credential swap
+// left it firing through the stopped old adapter.
+//
+// This class owns exactly one listener at a time and is driven by
+// PluginRuntime.onAdapterSwapped (boot calls it once with the boot adapter):
+//   - live adapter + approval.mode='per_trade' (re-read at swap time) → a
+//     fresh listener bound to THAT adapter;
+//   - anything else → no listener (stopping any previous one first, awaiting
+//     its in-flight tick so a fire's result PATCH lands before teardown).
+//
+// Swaps are serialized through a promise chain: a second swap arriving while
+// the first is still draining queues behind it, so two listeners can never
+// run concurrently (the DB fire-claim makes a double-fire impossible anyway —
+// this keeps the process tidy, not the money safe).
+import { logger, formatError } from '../logger.js';
+const TAG = 'approval-lifecycle';
+export class ApprovalListenerLifecycle {
+    deps;
+    listener;
+    chain = Promise.resolve();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    get active() {
+        return this.listener !== undefined;
+    }
+    /** Apply the lifecycle for a freshly published adapter. Serialized. */
+    onAdapterSwapped(adapter) {
+        this.chain = this.chain
+            .then(() => this.apply(adapter))
+            .catch((err) => {
+            logger.error(TAG, `listener swap failed: ${formatError(err)}`);
+        });
+        return this.chain;
+    }
+    /** Terminal stop (shutdown drain) — also serialized behind pending swaps. */
+    stop() {
+        this.chain = this.chain
+            .then(() => this.stopCurrent())
+            .catch((err) => {
+            logger.warn(TAG, `listener stop failed: ${formatError(err)}`);
+        });
+        return this.chain;
+    }
+    async apply(adapter) {
+        // Always tear down the previous listener first — it is bound to the OLD
+        // adapter and must never fire through it again.
+        await this.stopCurrent();
+        if (!adapter.isLive)
+            return;
+        const mode = this.deps.resolveApprovalMode();
+        if (mode !== 'per_trade')
+            return;
+        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;
+        }
+        const fresh = this.deps.buildListener(adapter);
+        fresh.start();
+        this.listener = fresh;
+        logger.info(TAG, 'ProposalDecisionListener started (bound to the current adapter)');
+    }
+    async stopCurrent() {
+        if (!this.listener)
+            return;
+        const old = this.listener;
+        this.listener = undefined;
+        await old.stop();
+        logger.info(TAG, 'ProposalDecisionListener stopped');
+    }
+}

package/live/bracket-types.d.ts

@@ -20,6 +20,15 @@ export interface BracketLedgerEntry {
     symbol: string;
     entrySide: 'buy' | 'sell';
     entryCid: string;
+    /** Additional entry clientOrderIds submitted against this SAME bracket row —
+     *  a scale-in, or a second entry placed while the first is still resting.
+     *  Each order gets a fresh cloid but the row keeps the original `entryCid`,
+     *  so a fill matcher keyed on `entryCid` alone would ignore their fills
+     *  entirely (audit 2026-07-26 F5). HL-only today: Binance legs are
+     *  `closePosition:true` (whole-position, self-resizing), while HL legs are
+     *  FIXED SIZE — an unmatched scale-in fill there means NAKED contracts.
+     *  Bounded; oldest dropped. */
+    extraEntryCids?: string[];
     slCid?: string;
     tpCid?: string;
     stopPrice?: number;

package/live/live-adapter.d.ts

@@ -85,7 +85,6 @@ export declare class LiveAdapter extends EventEmitter implements IExchangeAdapte
     /** Session-start NAV, captured once at initialization. Used for drawdown calculation. */
     getSessionStartNav(): number | null;
     constructor(config: ExchangeConfig, mode: 'MICRO_LIVE' | 'LIVE', microLiveConfig?: {
-        sizeCapPercent?: number;
         maxPositionUSDT?: number;
     }, bracketMode?: BracketMode, userDataStreamMode?: UserDataStreamMode, userDataStreamTunables?: UserDataStreamTunables, 
     /** TRADE_AUDIT_TRAIL_PLAN Phase 1 — optional audit-trail wiring.  Wired

package/live/proposal-decision-listener.d.ts

@@ -35,6 +35,9 @@ export interface ProposalDecisionListenerHealth {
     running: boolean;
     ticksTotal: number;
     ticksWithFires: number;
+    claimsAcquired: number;
+    claimConflicts: number;
+    claimFailures: number;
     firesAttempted: number;
     firesSucceeded: number;
     firesAbandonedDrift: number;
@@ -53,6 +56,21 @@ export declare class ProposalDecisionListener {
      *  that finds ≥1 pending. */
     private currentIntervalMs;
     private health;
+    /** Claim tokens are process-local by design. A new process must never steal
+     *  an old process's durable claim, because it cannot know whether the
+     *  exchange accepted an order just before the crash. */
+    private readonly claimTokens;
+    /** In-memory work queue for claims whose POST or fire-result response was
+     *  lost. The DB poll excludes claimed rows, so only the original process can
+     *  retry its exact token/outcome; a restarted process cannot steal it. */
+    private readonly claimedCandidates;
+    private readonly acquiredClaims;
+    /** Once present, this process must never invoke createOrderTool for the
+     *  proposal again. Any subsequent work is result persistence only. */
+    private readonly mutationsStarted;
+    /** Completed outcomes awaiting a successful fire-result response. Retrying
+     *  this PATCH is safe; retrying the exchange mutation is not. */
+    private readonly pendingResults;
     constructor(options: ProposalDecisionListenerOptions);
     /** Begin the poll loop. Idempotent — subsequent calls are no-ops while
      *  the listener is already running. */
@@ -65,6 +83,8 @@ export declare class ProposalDecisionListener {
     private runTick;
     private tick;
     private fetchPending;
+    private claimPending;
+    private forgetClaim;
     private firePending;
     private patchResult;
 }