@reefclaw/openclaw-plugin 0.1.13 → 0.1.15

package/ingest/event-loop-monitor.js

@@ -0,0 +1,190 @@
+// 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 { readFileSync } from 'node:fs';
+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;
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Runqueue wait — the measurement that says WHO froze the loop.
+//
+// ★ Event-loop delay is a symptom with two very different causes: the host
+// descheduled us (co-tenant load, an oversubscribed VPS) or we blocked our own
+// loop (a synchronous burst — on a ReefClaw box, an LLM turn, which runs
+// EMBEDDED in this same process alongside order handling). The histogram above
+// cannot tell them apart, so the check used to assert the first and tell the
+// operator to buy more CPU. Verified wrong on prod 2026-07-29: a "froze 5.9s"
+// warn on a box at 0.05 load, 0 steal, 0 swap, whose cumulative runqueue wait
+// was 1.95s across the whole process lifetime. Resizing would have done nothing.
+//
+// /proc/self/schedstat field 2 is the kernel's own count of nanoseconds this
+// thread spent RUNNABLE but waiting for a CPU. It is exactly the discriminator:
+// large ⇒ the host really is starving us; ~0 while the loop froze ⇒ the freeze
+// came from inside. `/proc/self` is the thread-group leader = the main thread,
+// which is where the event loop runs, so this is the right thread to ask.
+//
+// Same evidence rule as everything else on this path (issue #265): unavailable
+// ⇒ null ⇒ 'unknown' attribution and the cautious copy — never a fabricated
+// zero, which would read as "definitely self-inflicted" and is the same
+// false-confidence bug pointed the other way.
+const SCHEDSTAT_PATH = '/proc/self/schedstat';
+/** Cumulative ns at the previous sample; null until the first read establishes
+ *  a baseline. A delta needs two points — the first call can only arm. */
+let lastRunqueueWaitNs = null;
+/** Latched after the first failed read: not Linux, or a kernel built without
+ *  CONFIG_SCHEDSTATS. Stops us re-reading a file that will never exist. */
+let schedstatUnavailable = false;
+/** Read the cumulative runqueue-wait counter (ns). Null when unreadable or
+ *  malformed — never a guess. */
+function readRunqueueWaitNs() {
+    if (schedstatUnavailable)
+        return null;
+    try {
+        // Three space-separated numbers: cpu_time_ns, runqueue_wait_ns, timeslices.
+        const parts = readFileSync(SCHEDSTAT_PATH, 'utf8').trim().split(/\s+/);
+        const ns = Number(parts[1]);
+        if (!Number.isFinite(ns) || ns < 0) {
+            schedstatUnavailable = true;
+            return null;
+        }
+        return ns;
+    }
+    catch {
+        schedstatUnavailable = true;
+        logger.info(TAG, 'runqueue-wait unavailable (not Linux, or kernel without CONFIG_SCHEDSTATS) — host-stall attribution will report unknown');
+        return null;
+    }
+}
+/** Time (ms) this process spent waiting for a CPU since the previous call, then
+ *  re-baselines — so consecutive calls partition the timeline into the SAME
+ *  non-overlapping windows as `sampleEventLoopDelayMs`, and the two readings of
+ *  one cycle describe one window.
+ *
+ *  ★ Call this EVERY cycle, not only when a stall was observed: the counter is
+ *  cumulative since process start, so a first read taken at the moment of a
+ *  freeze would report hours of ordinary scheduling as if it were the freeze.
+ *
+ *  Returns null when unavailable or on the first (baseline-establishing) call. */
+export function sampleRunqueueWaitMs() {
+    const ns = readRunqueueWaitNs();
+    if (ns == null)
+        return null;
+    const prev = lastRunqueueWaitNs;
+    lastRunqueueWaitNs = ns;
+    if (prev == null)
+        return null;
+    // Counters only climb; a decrease means we are not reading what we think we
+    // are (or it wrapped). Report unknown rather than a negative/garbage window.
+    if (ns < prev)
+        return null;
+    return (ns - prev) / 1e6;
+}
+/** 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;
+    lastRunqueueWaitNs = null;
+    schedstatUnavailable = 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,23 @@
-import { type ReadinessReport, type VenueId } from '@reefclaw/shared';
+import { type ReadinessReport, type VenueId, type VenueReachabilityResult } from '@reefclaw/shared';
+/** Who froze the loop. 'unknown' when the kernel counter is unreadable (not
+ *  Linux / no CONFIG_SCHEDSTATS / first cycle) — attribution is evidence, and
+ *  absent evidence stays absent rather than defaulting to a blame. */
+export type StallAttribution = 'host' | 'self' | 'unknown';
+/** Compare the freeze against the CPU the host actually denied us. Exported for
+ *  unit tests — this is the whole discrimination rule in one place. */
+export declare function attributeStall(stallMs: number, runqueueWaitMs: number | null): StallAttribution;
 /** 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 +46,16 @@ 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;
+    /** Injected for tests; production reads /proc/self/schedstat. */
+    sampleRunqueueWaitMs?: () => 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,44 @@
 // 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, HOST_STALL_FIX_HINT, } from '@reefclaw/shared';
 import { logger, formatError } from '../logger.js';
+import { startEventLoopMonitor, sampleEventLoopDelayMs, sampleRunqueueWaitMs, } 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;
+/** How much of a freeze the kernel must attribute to runqueue wait before we
+ *  blame the HOST for it. Half is deliberately generous to the host-starved
+ *  reading: a host that froze us for N seconds necessarily made us wait most of
+ *  those N seconds, while a self-blocked loop accrues ~nothing (prod: 1.95s
+ *  across an entire process lifetime, against a 5.9s freeze in one cycle). */
+const HOST_WAIT_SHARE_OF_STALL = 0.5;
+/** Absolute floor under the share test. Sub-second waiting is ordinary
+ *  scheduling on any box and must never read as starvation, however short the
+ *  freeze it is compared against. */
+const HOST_WAIT_FLOOR_MS = 1_000;
+/** Compare the freeze against the CPU the host actually denied us. Exported for
+ *  unit tests — this is the whole discrimination rule in one place. */
+export function attributeStall(stallMs, runqueueWaitMs) {
+    if (runqueueWaitMs == null)
+        return 'unknown';
+    const hostThreshold = Math.max(HOST_WAIT_FLOOR_MS, stallMs * HOST_WAIT_SHARE_OF_STALL);
+    return runqueueWaitMs >= hostThreshold ? 'host' : 'self';
+}
+export function createReadinessCycleState() {
+    return { consecutiveReachFailures: 0 };
+}
 function resolveIntervalMs(explicit) {
     if (explicit && explicit > 0)
         return Math.max(MIN_INTERVAL_MS, explicit);
@@ -34,9 +65,12 @@ 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;
+    const sampleWait = deps.sampleRunqueueWaitMs ?? sampleRunqueueWaitMs;
     // 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 +84,71 @@ 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);
+    // ★ Sampled unconditionally, even on a passing cycle: the counter behind it is
+    // cumulative, so it must be re-baselined every cycle for its window to line up
+    // with the freeze window. Reading it only when a stall appeared would charge
+    // that one freeze with every millisecond of ordinary scheduling since boot and
+    // score a self-blocked loop as a starved host.
+    const runqueueWaitMs = sampleWait();
+    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;
+        // WHO froze it — computed only for a real freeze, since the whole question
+        // is what to tell the operator to go fix.
+        const attribution = rawStatus === 'pass' ? 'unknown' : attributeStall(stallMs, runqueueWaitMs);
+        const frozeSecs = (stallMs / 1000).toFixed(1);
+        const waitedSecs = runqueueWaitMs != null ? (runqueueWaitMs / 1000).toFixed(1) : null;
+        // The detail line carries the evidence, not just the verdict: an operator
+        // who disagrees with the attribution can see the number it rests on.
+        const stallDetail = attribution === 'host'
+            ? `froze ${frozeSecs}s (waited ${waitedSecs}s for CPU)`
+            : attribution === 'self'
+                ? `froze ${frozeSecs}s (host had CPU free — blocked inside the agent process)`
+                : `froze ${frozeSecs}s`;
+        checks.push(makeReadinessCheck('host_responsive', status, {
+            detail: rawStatus === 'pass'
+                ? `max loop delay ${Math.round(stallMs)}ms`
+                : bootWarmup
+                    ? `froze ${frozeSecs}s (boot warm-up — rechecking)`
+                    : stallDetail,
+            // Only an attributed stall may name its cause; 'unknown' falls through to
+            // the cautious default in the copy map (issue #265 rule).
+            ...(attribution === 'host'
+                ? { fixHint: HOST_STALL_FIX_HINT.host_starved }
+                : attribution === 'self'
+                    ? { fixHint: HOST_STALL_FIX_HINT.self_inflicted }
+                    : {}),
+            checkedAt: now,
+        }));
+        if (rawStatus !== 'pass' && !bootWarmup) {
+            const cause = attribution === 'host'
+                ? `host starved: waited ${waitedSecs}s for CPU`
+                : attribution === 'self'
+                    ? `blocked inside this process (host had CPU free — waited only ${waitedSecs}s)`
+                    : 'cause unattributable (runqueue wait unreadable)';
+            logger.warn(TAG, `event loop froze ${frozeSecs}s this cycle — order handling and bracket resync can lag by that much; ${cause}`);
+        }
+    }
+    // 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 +170,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 +264,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;
+}