@reefclaw/connect 0.1.20 → 0.1.22

package/assets/shared/readiness.js

@@ -5,22 +5,30 @@
 // renders generically without duplicating the copy. Advisory only: readiness
 // explains failures, it never blocks trading or the safety floor.
 // See docs/AGENT_READINESS_GATE_PLAN.md.
+/** A failed probe is read as a venue failure only while it finished within
+ *  this multiple of its own timeout budget; past it, the clock says the
+ *  process — not the network — is what broke. 2× leaves generous room for
+ *  ordinary scheduling jitter and TLS/DNS slack while sitting far below the
+ *  8×-and-worse overshoots a real freeze produces. */
+export const REACHABILITY_STALL_FACTOR = 2;
 /** The canonical connect-phase checks + their plain-English fixes. Single source
  *  of copy; the plugin inlines these into each report so the webapp stays dumb. */
 export const READINESS_CHECK_COPY = {
+    // ★ The DEFAULT reachability copy must describe possible causes, never assert
+    // one: this hint is attached to the debounced 'unreachable' warn, where all we
+    // know is that two probes did not complete. Asserting DNS/firewall/region sent
+    // an operator hunting a firewall that did not exist (issue #265) — the actual
+    // cause was the agent's own host being starved. A CONFIRMED geo-block (the
+    // server answered 451/403) gets the assertive copy below, passed explicitly.
     binance_reachable: {
         label: 'Binance reachable',
         phase: 'connect',
-        fixHint: 'Your agent host is geo-blocked by Binance (HTTP 451). Run OpenClaw from a Binance-permitted region — most EU / several Asia VPS regions work.',
+        fixHint: 'Your agent host did not reach the Binance API on two consecutive checks. Possible causes: outbound HTTPS/DNS blocked, a transient Binance outage, or the host itself being starved of CPU/memory (check "Agent host responsive"). If it persists, verify connectivity and that the host region is Binance-permitted.',
     },
-    // Dormant until the Hyperliquid venue ships (docs/HYPERLIQUID_INTEGRATION_PLAN.md
-    // Phase 1): the reporter probes only the CONFIGURED venue, so this id is never
-    // emitted while venue='binance'. Landed early so older webapps render it via the
-    // string-widened ReadinessCheck.id the moment a newer plugin starts sending it.
     hyperliquid_reachable: {
         label: 'Hyperliquid reachable',
         phase: 'connect',
-        fixHint: 'Your agent host cannot reach the Hyperliquid API (api.hyperliquid.xyz). Check outbound HTTPS/DNS/firewall; if the host region is restricted, run OpenClaw from a permitted region.',
+        fixHint: 'Your agent host did not reach the Hyperliquid API (api.hyperliquid.xyz) on two consecutive checks. Possible causes: outbound HTTPS/DNS blocked, a transient Hyperliquid outage, or the host itself being starved of CPU/memory (check "Agent host responsive"). If it persists, verify connectivity and that the host region is permitted.',
     },
     clock_in_sync: {
         label: 'Host clock in sync',
@@ -37,9 +45,53 @@ export const READINESS_CHECK_COPY = {
         phase: 'connect',
         fixHint: 'No trading tools are registered. Ensure tools.alsoAllow includes "group:plugins", then restart the gateway.',
     },
+    // The signal that actually matters on a trading rig, and the one that was
+    // invisible while a starved host masqueraded as an unreachable venue
+    // (issue #265): the agent process stopped running for seconds at a time. Fed
+    // by the event-loop delay the plugin samples locally.
+    //
+    // ★ This DEFAULT must not name a cause. Event-loop delay is a symptom of two
+    // opposite problems — the host starving the process, or the process blocking
+    // its own loop — and it alone cannot distinguish them. Asserting "your host is
+    // starved, give it more CPU/RAM" sent an operator toward a resize on a box
+    // measured at 0.05 load with 1.95s of lifetime runqueue wait (2026-07-29);
+    // the freeze was an in-process LLM turn. When the plugin CAN discriminate (it
+    // reads /proc/self/schedstat) it passes one of HOST_STALL_FIX_HINT below;
+    // this cautious copy is what an unattributable freeze gets. Same rule the
+    // reachability hints already follow.
+    host_responsive: {
+        label: 'Agent host responsive',
+        phase: 'connect',
+        fixHint: 'The agent process froze for seconds at a time, so order handling, stop attachment and bracket resync can be delayed by that much. Two things cause this and we could not tell them apart on this host: the host being short of CPU/memory (other containers, agents or a leaking process competing for the box), or something inside the agent process blocking it — note the AI agent itself runs in this same process. Check host load first; if it is idle, the freeze came from inside.',
+    },
+};
+/** Assertive copy for a stall we COULD attribute, passed explicitly as the
+ *  `fixHint` override — the same "only name a cause you measured" rule that
+ *  governs GEO_BLOCK_FIX_HINT. The discriminator is the kernel's own runqueue
+ *  wait for this process (/proc/self/schedstat): time spent runnable but denied
+ *  a CPU. Large ⇒ the host really is the problem; ~0 across a multi-second
+ *  freeze ⇒ the process blocked itself and no amount of extra hardware helps. */
+export const HOST_STALL_FIX_HINT = {
+    host_starved: 'Your agent host is starved of CPU/memory — the agent process was ready to run but the host kept it waiting, so order handling, stop attachment and bracket resync can be delayed by that much. Give the host more CPU/RAM, or reduce what else runs on it (other containers, agents or a leaking process competing for the same box).',
+    self_inflicted: 'The agent process froze for seconds at a time, but the host was NOT short of CPU — it barely waited for one. Something inside the agent process blocked it, and the usual cause is an AI turn: the agent runs in the same process as order handling, so assembling a large turn (long session transcript, big memory database, large injected files) stops trading work while it runs. More CPU/RAM will not fix this. Trim what each turn loads, or reduce turn frequency.',
+};
+/** Assertive copy for a CONFIRMED geo-block, passed explicitly as the `fixHint`
+ *  override. This is the one case where naming the cause is honest: the server
+ *  answered 451/403, so we are reporting what it told us — not an inference from
+ *  a request that never completed. */
+export const GEO_BLOCK_FIX_HINT = {
+    binance: 'Your agent host is geo-blocked by Binance (HTTP 451) — Binance itself refused the request. Run OpenClaw from a Binance-permitted region; most EU / several Asia VPS regions work.',
+    hyperliquid: 'Your agent host is blocked by Hyperliquid (api.hyperliquid.xyz answered HTTP 451/403) — the API itself refused the request, so this is a region/policy block rather than a network fault. Run OpenClaw from a permitted region.',
 };
 /** Build a self-describing check, pulling label/phase/fixHint from the copy map.
- *  fixHint is attached only when there is something to fix (warn/fail). */
+ *  fixHint is attached only when there is something to fix (warn/fail).
+ *
+ *  `fixHint` in opts OVERRIDES the copy-map default. The static copy asserts one
+ *  cause per check id, which is right for a definitive signal (a 451 IS a geo
+ *  block) but wrong when the same id fires on an inference: a reachability warn
+ *  sent the operator hunting a firewall that was never the problem (issue #265).
+ *  Callers that know the status was inferred pass a hint that describes the
+ *  possibilities instead of asserting one. */
 export function makeReadinessCheck(id, status, opts = {}) {
     const copy = READINESS_CHECK_COPY[id];
     const needsFix = status === 'warn' || status === 'fail';
@@ -49,7 +101,7 @@ export function makeReadinessCheck(id, status, opts = {}) {
         phase: copy.phase,
         status,
         ...(opts.detail !== undefined ? { detail: opts.detail } : {}),
-        ...(needsFix ? { fixHint: copy.fixHint } : {}),
+        ...(needsFix ? { fixHint: opts.fixHint ?? copy.fixHint } : {}),
         checkedAt: opts.checkedAt ?? Date.now(),
     };
 }

package/assets/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: reefclaw
-version: 0.0.6
+version: 0.0.7
 description: ReefClaw trading control room — bootstrap (connects your agent; full trading instructions arrive automatically after first connect)
 author: ReefClaw
 homepage: https://reefclaw.com
@@ -24,18 +24,13 @@ config:
     description: ReefClaw relay WebSocket URL. Defaults to the production relay when omitted.
 ---
 
-<!-- BOOTSTRAP SKILL.md — this is the thin installer copy shipped in the
-     @reefclaw/connect npm package. It carries ONLY the config schema and the
-     connect instructions. The FULL trading instructions (versioned 2.x.y) are
-     delivered automatically by the ReefClaw connector minutes after the first
-     successful connect, over the authenticated update channel — they replace
-     this file in place (a 0.0.x version always loses the semver comparison).
-     The "Connecting (first run)" section below MUST stay in sync with the
-     same section in skill/SKILL.md. -->
-
 # ReefClaw — Connect Your Agent (Bootstrap)
 
-You are being connected to **ReefClaw**, a supervised trading control room. Your operator watches everything you do on the ReefClaw dashboard. This bootstrap file only covers **connecting**; your full trading instructions arrive automatically a few minutes after the connection succeeds.
+## About this file
+
+This is the thin BOOTSTRAP copy shipped in the `@reefclaw/connect` npm package. It covers **installing the ReefClaw plugin and connecting to the user's ReefClaw account** — nothing else. The FULL trading instructions (versioned 2.x.y) are delivered automatically by the ReefClaw connector minutes after the first successful connect, over the authenticated update channel — they replace this file in place (a 0.0.x version always loses the semver comparison). Maintainers: the "Connecting (first run)" section below MUST stay in sync with the same section in `skill/SKILL.md`.
+
+You are being connected to **ReefClaw**, a supervised trading control room. Your operator watches everything you do on the ReefClaw dashboard. Some steps below change host configuration or install software; they exist solely to complete the setup **the user initiated by pasting their connect message**. Tell the user what each step changes before you do it, do it only for that user, and revert any temporary permission (like elevated exec) as soon as the install completes.
 
 **Do not attempt to trade before the full instructions arrive.** If trading tools are visible but this file is still a bootstrap version (0.0.x), the connection has not completed — finish connecting first.
 

package/dist/cli.js

@@ -89,6 +89,9 @@ function wireConfig(pre) {
         info('This is required for OpenClaw v2026.4.2+ to keep operator scopes on the WS connection; keep the gateway bound to localhost.');
     }
     const merged = mergeReefClawConfig(base);
+    // Explicit disclosure: the connect message's rc_ token is persisted locally
+    // so the connector can authenticate to the user's relay room across restarts.
+    info('Saving your ReefClaw connection settings (including the rc_ token) to ~/.openclaw/openclaw.json — owner-only file permissions (0600).');
     writeConfig(merged);
     ok('sandbox allowlist (group:plugins) + gateway scope + reefclaw entry ensured');
     return merged;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reefclaw/connect",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "description": "One-command installer that connects your OpenClaw agent to ReefClaw (paper trading, no exchange keys).",
   "type": "module",
   "bin": {