@oracle-agent/oracle 0.24.1 → 0.24.2

package/dist/assets/skills/setup/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: setup
+description: "Use when the user types /setup or wants to connect telegram, discord, slack, or another messaging platform to oracle."
+version: 1.0.0
+disable-model-invocation: true
+---
+
+> Oracle native tools: `oracle_cli` (read/prepare), `vault_status`, `signer_status`, `signer_execute` (needs human confirmationNonce), `skill_load`. No generic shell. No fleet SSH.
+
+
+# /setup
+
+Configure messaging for the oracle profile. Secrets stay local.
+
+```bash
+# menu + status (never prints tokens)
+oracle setup status
+
+# open full hermes wizard
+oracle setup messaging
+
+# platform shortcuts
+oracle setup telegram
+oracle setup discord
+oracle setup slack
+oracle setup whatsapp
+
+# gateway control
+oracle setup gateway status
+oracle setup gateway restart
+```
+
+If the user passed args after `/setup`, forward them:
+
+```bash
+oracle setup {{arg1}} {{arg2}} {{arg3}}
+```
+
+If no args, show `oracle setup status`.
+Never echo bot tokens, app tokens, or passwords back into chat.

package/dist/assets/skills/stable-launch-ops/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: stable-launch-ops
+description: "Use for Stable Launch chain 988 deploy or testnet asks."
+version: 1.0.0
+---
+
+> Oracle native tools: `oracle_cli` (read/prepare), `vault_status`, `signer_status`, `signer_execute` (needs human confirmationNonce), `skill_load`. No generic shell. No fleet SSH.
+
+
+# Stable Launch ops (chain 988)
+
+Repos: `~/projects/stable-launch` (contracts) · `stable-launch-web` · `stable-launch-indexer` · `stable-agent` (personal signals, never bundled into public web).
+
+Board: Obsidian `Projects/Stable Launch Board.md` · preview `https://stablelaunch.demi.la`
+
+## Chain fact (do not invent a testnet)
+
+- Product chain is **Stable Mainnet chainId 988** only in this stack.
+- Addresses file: `stable-launch/addresses/988.json` (null until factory GO).
+- Public RPC: `https://rpc.stable.xyz` (pruned ~156k blocks — indexer needs **archive** paid RPC for first backfill).
+- There is **no** separate Stable public testnet config in-repo. INTERFACE.md "testnet first" means **anvil-988 fork rehearsal**, not a second public network.
+
+When DEMI asks **"should we deploy on testnet to test?"**:
+
+| Path | Do it? | Why |
+|---|---|---|
+| Traffic stack (paid RPC + indexer host + CF secrets/DNS) | **Yes** | Proves launch-day read path; no factory GO |
+| Frontend edge cutover off demi-poly | **Yes** | demi-poly is forbidden for launch frontend/indexer |
+| Physical wallet QA on 988 | **Yes** | Cannot verify headlessly |
+| Persistent **anvil fork of 988** + point web/indexer at it | **Yes** | Full E2E, zero mainnet spend |
+| Factory `forge script --broadcast` on live 988 | **No** without explicit GO | Real USDT0 gas + irreversible keeper wiring |
+| Invented external "Stable testnet" deploy | **No** | Not in config; fork already covers contract risk |
+
+## Already proven (do not re-litigate)
+
+- Foundry suite green; dual red-team APPROVE (Opus + Sol)
+- Full lifecycle on live-RPC anvil-988 fork: deploy→launch→buy→graduate→v3 LP→swap→buyback/burn
+- Deploy without code-bearing `STABLE_KEEPER` reverts as designed
+- LI.FI bridge Base USDC→USDT0 on 988 quoted live
+- Indexer-first radar path + k6 load scripts exist
+
+## Hard GO gates before live factory
+
+From board / `docs/MAINNET_GO_RUNBOOK.md`:
+
+1. Recoverable **Safe** as `STABLE_KEEPER` on 988 (`cast codesize` > 0) — not an EOA
+2. Funded **dedicated** deployer key (USDT0 gas) — never the chat/hot wallet
+3. Paid `STABLE_RPC_PRIMARY` / `FAILOVER` (archive primary)
+4. Indexer host on Fly/Railway/Render — **never demi-poly**
+5. DNS / CF custom-domain bind for `stablelaunch.demi.la` (see DNS trap)
+6. Explicit DEMI **GO** for broadcast
+
+### CF / edge (do not re-mint tokens blindly)
+
+- Same CF **account** as HL Media (users see hostnames only).
+- Web repo already has CF secrets + green deploys (2026-07-25).
+- Live: `https://stable-launch-web.christophergervais92.workers.dev` (account-derived sub — never guess `demi-hl`).
+- Still need: `STABLE_RPC_*`, `INDEXER_URL`, factory `NEXT_PUBLIC_*` after GO.
+- Vault "cfat_ expired" may be stale after green CI.
+
+### Indexer Fly prep
+
+- `fly.toml` in `stable-launch-indexer` (lax, volume `/data`). Empty factory → `live:false` radar OK.
+- See indexer README + `docs/PRE_LIVE_OPS.md`.
+
+### DNS trap — never blind-CNAME to workers.dev
+
+`stablelaunch.demi.la` A→demi-poly works. CNAME to workers.dev **without** CF zone + Worker domain bind → **403** on custom Host (probed). Keep VPS A + edge-QA on workers.dev, or CF zone audit → NS → bind. Recipe: `references/dns-cf-workers-trap-2026-07-25.md`. GoDaddy API 401 → mint fresh key before API DNS edits.
+
+## Forbidden
+
+- Launch frontend, indexer, or RPC proxy on demi-poly
+- Bundling `stable-agent` into public `stable-launch-web`
+- Mainnet broadcast "just to test" when fork rehearsal already passed
+- Deploy from the Oracle chat hot wallet
+
+## Safe next steps (default recommendation order)
+
+1. Confirm CF green; set archive RPC secrets; Fly indexer empty-factory + `INDEXER_URL`
+2. Wallet physical QA on preview and/or workers.dev
+3. Keeper Safe + dedicated deployer
+4. CF zone path for custom domain (or leave VPS A)
+5. Only then: `docs/MAINNET_GO_RUNBOOK.md`
+
+## Pointers
+
+- Status: `stable-launch/STATUS.md`
+- Runbooks: `docs/MAINNET_GO_RUNBOOK.md`, `docs/KEEPER_RUNBOOK.md`, `docs/LAUNCH_TRAFFIC.md`, `docs/PRE_LIVE_OPS.md`
+- Notes: `references/testnet-decision-2026-07-25.md`, `references/dns-cf-workers-trap-2026-07-25.md`

package/dist/assets/skills/trade-loop-circuit-breaker/SKILL.md

@@ -0,0 +1,441 @@
+---
+name: trade-loop-circuit-breaker
+description: Apply mandatory guardrails to any autonomous or agentic live-money trading loop. Use before touching the Polymarket bot, building a new scanner/execution dashboard, enabling wallet/CEX orders, responding to a drawdown, or resuming after a halt. Makes the "anything touching real capital is surgical, backed-up, verified, and GO-gated" invariant executable.
+---
+
+> Oracle native tools: `oracle_cli` (read/prepare), `vault_status`, `signer_status`, `signer_execute` (needs human confirmationNonce), `skill_load`. No generic shell. No fleet SSH.
+
+
+# Trade-Loop Circuit Breaker
+
+Any runaway loop or unverified execution path is existential when it can move real capital. This skill gates Polymarket operations and new agentic trading products. It does NOT change strategy; it controls when execution is allowed.
+
+## Context
+- Live sports arb bot. VPS `demi-poly`, path `/root/polymarket-arbitrage-bot`.
+- Has a daily loss limit that HALTS the bot (has fired before — 14.2% daily loss → manual reset needed).
+- pm2-managed process map; extensive cron pipeline (reconcile, clv, snapshots, retrain, shadow, rf-advisory).
+- See vault: Polymarket Bot Operational Reference, Demi Revert Runbook, Demi Bot Architecture.
+
+## Before ANY change to the live loop
+1. **Back up first.** Snapshot the file(s) and the relevant DB/state before editing. Note the exact revert command (see Demi Revert Runbook).
+2. **Surgical only.** Touch exactly what the task requires. No "while I'm here" cleanup in the money path.
+3. **GO-gate.** Hard-to-reverse actions (deploy to live loop, reset after halt, change position sizing, drop/alter state) require explicit DEMI confirmation. Do not self-approve.
+
+## Circuit breakers on any autonomous trading/execution loop
+- **Retry ceiling:** max 3 attempts on a failing external call (Polymarket API, RPC). Then stop, don't hammer.
+- **Spend/exposure cap:** respect the daily loss limit; never code around a halt. A halt is a signal, not an obstacle.
+- **Backoff + jitter** on API timeouts — cascading timeouts are a known cost/failure path.
+- **Kill-switch check** before resume: verify why it halted before clearing it. Reset ≠ diagnosis.
+- **Signer separation:** automatic execution may use only a separate capped hot wallet/session key/smart wallet. Never DEMI's main seed/private key.
+- **Two-step deploy boundary:** shipping executor code and securely installing a dedicated signer are not the same as enabling broadcasts. A signer may be installed root-only in an unfunded, execution-off state after explicit installation approval so its derived address and status path can be verified. Keep `agent:execute` blocked, capital at zero, and asset allowlists empty until a separate explicit DEMI GO enables the capped signer. Never expose or print the key during either stage.
+- **Policy proof:** after every deploy, pull the live policy and state `execution.enabled`, `backendSigner`, `liveExecute`, and whether `agent:execute` is blocked before claiming auto-exec status.
+
+## Resume-after-halt sequence
+1. Read the halt reason (loss limit? API? reconcile mismatch?). Don't clear blindly.
+2. Reconcile positions (`reconcile_positions.py --apply`) — confirm on-chain vs recorded state matches.
+3. Confirm the condition that tripped it has actually cleared.
+4. GO-gate the resume with DEMI. Report the halt reason + current exposure in the ask.
+5. Resume, then watch the first cycle before walking away.
+
+## Escalation message format
+When a breaker trips or a halt needs a human: state the trigger, current exposure/PnL, what you've verified, and the specific decision needed — one message, no burying the ask.
+
+## Evaluating a NEW venue / market before wiring it into the bot (HIP-4 pattern)
+When DEMI says "make the bot also trade <new venue/market> (e.g. HIP-4)", the
+change is a NEW EDGE that shares infra — NOT the existing edge pointed at a new
+venue. Pressure-test the premise before writing a line.
+
+**STEP 0 (do this BEFORE proposing any build): inventory what already exists in
+the repo.** A prior session — or DEMI — may have already built most of the venue
+stack, gated off. One grep saves a duplicate build: `git log --oneline | grep -i
+<venue>`, `ls strategies/ lib/ | grep -i <venue>`, `grep -rn "<VENUE>\|exec-client"
+.env server/api.js`, and `pm2 logs demi-server --lines 300 --nostream | grep -i
+<venue>` (is it FIRING right now?). This exact miss happened with HIP-4: the FULL
+stack (exec client, divergence monitor, strategy, TP guard, per-user creds path)
+was already committed and live-trading for one pilot wallet — nearly rebuilt a
+duplicate. Also re-scope "for others": if the bot is already a MULTI-USER
+per-wallet system, "trade X for everyone" = per-user opt-in (own wallet/key/
+settings), NOT DEMI custodying others' funds — don't reflexively push back on
+custody grounds before checking the architecture. Full worked example (what
+existed, the pilot-gate→per-user conversion, deploy discipline, open GO-gates):
+`references/hip4-already-built-per-user-conversion.md`.
+
+If the venue is genuinely greenfield, THEN pressure-test as below:
+1. **Pull real liquidity first, argue from numbers not vibes.** Get the actual
+   book depth on the new venue (for HIP-4: `outcomeMeta` + `l2Book "#<encoding>"`,
+   see the `hyperliquid` skill). Thin/favorite-concentrated books cap strategy
+   size to the top handful of markets — model that before proposing trades.
+2. **Cross-venue arb hinges on RESOLUTION-SOURCE PARITY.** If the new venue's
+   oracle can resolve an event differently than the leg you're hedging against
+   (e.g. HL HIP-4 oracle vs Polymarket UMA), the "arb" is a naked directional bet
+   with BOTH legs able to lose. Verify identical resolution criteria before ever
+   calling it an arb.
+3. **Separate the two builds and push back on the risky one.** "Trade X for
+   others" is ambiguous: (a) extend our own trading to a new venue = engineering;
+   (b) trade other people's capital = custody + trust + reg surface → push back
+   hard, do not wire third-party capital through our signer on day one.
+4. **Shadow/paper FIRST, always.** A new edge goes through this circuit breaker:
+   build a read module + a shadow-mode spread scanner that LOGS would-be trades
+   without executing, collect a few days of data to prove the edge is real and
+   capturable, THEN GO-gate live with capital caps. Never hot-wire directional
+   trades on a new venue into the live money loop on introduction day.
+5. Confirm the live bot's current state (pm2 status + halt-file check) before
+   proposing any change, so the new-venue work doesn't collide with a halt.
+
+Worked example (HIP-4 outcome markets: endpoint probe, coin encoding, WC-2026
+liquidity table, both-vs-illiquid analysis): `references/hip4-venue-evaluation.md`.
+
+## Converting a pilot-gated venue strategy to FULL per-user (the "trade X for everyone" ask)
+When DEMI says "make HIP-4 trade for others / everyone, like the PM bot," and STEP 0 finds
+the venue stack already exists but gated to ONE pilot wallet (`HIP4_MANUAL_WALLETS`), the
+work is a GATE CONVERSION, not a build. The PM bot is already multi-user per-wallet, and the
+HIP-4 exec path was built per-user-ready — verify these before promising a rewrite:
+- **The exec client already takes a key as a PARAMETER**, not a hardcoded wallet
+  (`createClient({ agentPrivateKey })`). The `_clients` map is `wallet -> client`. Per-user
+  creds already decrypt per-wallet (`auth.decryptCredentials(wallet, 'hl-credentials.json')`).
+  The onboarding endpoint (`POST /api/hip4/credentials`) + the encrypted-file whitelist in
+  `server/auth.js` already exist. So "per-user" is mostly ALREADY THERE.
+- **What actually blocks it = two gate sites**, both single lines: (1) the strategy's
+  `pilotWallets().includes(wallet)` check in `execute()`, (2) the API's `requireHip4Pilot`
+  middleware on `/hip4/order` + `/hip4/cancel`. Convert BOTH to `optedIn || isPilot` where
+  `optedIn = bot.settings.trading.hip4Enabled === true` (mirror PM's `settings.trading.mode==='live'`
+  opt-in). Keep the pilot allowlist as a backward-compat OR so the pilot keeps trading.
+- **Per-user sizing/caps**: global env `STAKE`/`MAX_POSITIONS` become per-user reads from
+  `bot.settings.trading.positionSizing.maxPerTradeUsd` + `settings.risk.maxConcurrentPositions`,
+  with the env value as fallback. Clamp stake to the HL 10.1 USDC min-notional floor.
+- **A UI toggle is required for real parity** — the API accepts the setting but the dashboard
+  page (`src/pages/HIP4.jsx`) needs a control writing `settings.trading.hip4Enabled` via
+  `/api/settings` (copy the Settings.jsx save pattern). Without it, opt-in is a manual JSON flip.
+- **THE FUNDING FACT (state it every time — it's the #1 user question):** HIP-4 outcome markets
+  settle in **USDC on the user's HYPERLIQUID SPOT wallet** — NOT Polymarket USDC, NOT an HL perps
+  balance. `getSpotState(wallet)` reads the spot `USDC` balance; the strategy skips if `usdcFree < stake`.
+  So a user needs: funded HL spot USDC + their own HL agent/API-wallet key stored + the toggle on.
+  PM's Polygon-USDC-on-the-CLOB and HIP-4's HL-native-spot-USDC are two SEPARATE funding pools;
+  a user can trade HIP-4 with zero Polymarket balance.
+- **Merging is DORMANT — "won't trade unless they sign" is TRUE.** After merge, the gate ladder in
+  `execute()` is: `HIP4_ARB_LIVE=1` (global, already on) -> opted-in-OR-pilot -> **hl-credentials.json
+  exists with agentPrivateKey (the "sign" — hard stop if missing)** -> USDC>=stake -> position room ->
+  fresh-edge recheck. A user who does nothing stays invisible; only their explicit toggle+key opens
+  execution. State this to reassure DEMI a merge doesn't auto-expose anyone. (The pilot wallet keeps
+  trading regardless of merge — merge only ADDS the opt-in path.)
+- **RISK-PROFILE GAP to flag before scaling capital:** the TP guard rests a GTC sell at 0.90 (env
+  `HIP4_TAKE_PROFIT_PRICE`) on a 60s poll — that is a take-profit-or-bust exit, NOT risk management.
+  There is NO stop-loss, NO mid-range/partial TP, NO time exit. Each position is ~all-or-nothing to
+  match resolution with an early cash-out ramp at 0.90. Fine at $10 pilot size; the single biggest
+  gap vs PM's risk discipline before bigger stakes or other users' capital.
+
+Full worked conversion (exact edits, the CRLF-diff footgun that inflates a 15-line change to
+9600 lines, the sell-direction notifier-label bug, deploy discipline, PnL-before-scale gate):
+`references/hip4-already-built-per-user-conversion.md`.
+
+## Adding an independent per-venue START/STOP toggle (the "let users run PM-only / HIP-4-only / both / neither" ask)
+When DEMI says "give Polymarket and HIP-4 separate start/stop" / "different bot
+trigger so people can run either or both," the architecture reality is usually:
+ONE master start/stop loop scans ALL strategies each cycle (PM's `sports-odds` +
+HIP-4's `hip4-arb` in the same `registry.scanAll`), so it's NOT two bots — it's one
+loop with per-venue CONTENT switches. Build them as **OFF-only gates that default ON**:
+- **Gate site = right after the strategy scan, before execution**, in the loop's
+  `_runScan` (`lib/trading-loop.js`, just after `setStrategyOpportunities`). Filter the
+  opportunity array by the venue tag: HIP-4 opps carry `venue:'hyperliquid'`, PM opps
+  don't. `polymarketEnabled===false` → keep only `venue==='hyperliquid'`;
+  `hip4Enabled===false` → drop `venue==='hyperliquid'`.
+- **OFF-only, default ON is the safest class of money-path edit** — read the flag as
+  `!== false` (undefined = on) so behavior is byte-identical unless a user EXPLICITLY
+  disables a venue. The gate can only ever DROP opportunities, never create one, so it
+  cannot cause a trade — only prevent one. This is why it's shippable without a shadow
+  cycle (unlike a NEW edge, which must paper-first). Keep the asymmetry deliberate: PM
+  defaults ON (preserves every existing user), HIP-4 defaults OFF (still needs key + opt-in).
+- **No restart needed** — `bot.settings` hot-reloads via an `fs.watch` on the user's
+  `settings.json` (debounced), so a dashboard toggle takes effect NEXT scan. Mirror the
+  existing per-venue opt-in read (`bot.settings.trading.hip4Enabled`) rather than baking
+  a value into the loop constructor.
+- **UI = a second card, not a second power button.** Keep the master Start/Stop as the
+  engine power; add a "Venue Controls" card of two independent ON/OFF toggles under it,
+  each writing `settings.trading.{polymarketEnabled,hip4Enabled}` via the page's existing
+  `/api/settings` save pattern. Add both flags to the frontend `DEFAULT_SETTINGS.trading`
+  (PM:true, HIP-4:false).
+- **VERIFY BY EXTRACTING THE FILTER INTO A UNIT TEST, not by trusting the default path.**
+  Copy the exact gate function into a throwaway `node` script and assert all four states
+  (both / PM-only / HIP-4-only / neither) plus the `undefined=on` case against a fixture
+  opp array. Default-on means the live log shows NO drop message on a normal deploy (correct,
+  not a failure) — so the standalone test is the real proof the OFF paths work, since prod
+  won't exercise them until a user flips a switch. Then confirm the loop is still scanning
+  live post-restart.
+Full worked recipe (exact gate code, the venue-tag fact, the 6-case unit test, the master-loop-
+vs-venue-content design decision, the "each venue as its own standalone bot" bigger-change note):
+`references/per-venue-enable-toggle.md`.
+
+## Wiring a NEW strategy into the SHARED learning loop (the "both bots self-learn" ask)
+When DEMI says "wire X into learning / both strategies should self-learn / have the
+agent take the trades so it self-learns," separate the two ideas he's fusing —
+they point OPPOSITE directions:
+- **"Agent takes the trades" = NO.** An LLM/agent in the hot execution path is wrong
+  for a deterministic arb: (1) latency — an arb edge lives seconds, an LLM round-trip
+  is 1-10s, so by the time it "decides" the edge is gone; (2) the edge is arithmetic
+  (book price vs consensus, a subtraction), nothing to reason about, a model only adds
+  hallucination + jitter; (3) money-path invariant — a non-deterministic process with
+  signing authority violates the circuit breaker. Execution stays deterministic and fast.
+- **"It self-learns" = YES, but as the COLD layer beside the loop, not inside it.**
+  The right shape: Execution (hot, deterministic, ms) writes closed-trade outcomes →
+  Learning (cold, async, minutes) digests them → Params (thresholds, sizing, market
+  whitelist) the loop reads next scan. The agent's job is tuning PARAMETERS from the
+  feedback, never placing ORDERS.
+- **The real gap is usually plumbing, not intelligence.** The PM bot already has the
+  full learning loop (`lib/trade-feedback.js` scores closed trades → LLM filter gets
+  more selective; `bayesian-updater.js`, `edge-scorer.js`, `clv-cutoff.js`). Grep the
+  learning modules for the new strategy/venue name — if it's ZERO, the new strategy
+  feeds nothing back and "it self-learns" is simply false for it. Wiring it in ≠ adding
+  an agent; it's connecting the recorder.
+- **The hard part for an on-chain venue (HIP-4): positions VANISH on close.** HIP-4
+  positions are on-chain spot coins (`+N` balances) that disappear from state when they
+  TP or settle — nothing writes a closed-trade record, so `trade-feedback` (which globs
+  `data/users/*/portfolio*.json` for records with `realizedPnl`) sees zero history. The
+  fix is a small RECORDER + RECONCILER, mirroring PM's own `backfillRealizedPnl`
+  (sell-fills matched against buys): (1) `recordEntry` at fill time into a
+  `portfolio-hip4.json` in the EXACT shape trade-feedback already reads (`strategy`,
+  `realizedPnl:null` while open, `entryCost`, `edgePercent`, `question`, timestamps) —
+  no reader-side wiring needed, the glob picks it up; (2) a read-only `reconcile` (pulls
+  `userFills` + `spotState`, NO signing) that books `realizedPnl = sellProceeds − entryCost`
+  when the coin's balance is gone, and `−entryCost` for coins that settled worthless with
+  no sell fill; (3) call reconcile on an existing per-wallet poll you already run (the TP
+  guard's 60s loop is ideal — it already iterates the same wallets).
+- **Never let the ledger block the fill.** Wrap `recordEntry`/`reconcile` in try/catch —
+  a learning-ledger write failure must NEVER fail an executed trade or halt the guard.
+- **VERIFY with a real end-to-end unit test against the actual modules**, mocking only the
+  network reads. Record a winner + a loser, mock a TP sell-fill + a worthless-settle, run
+  reconcile, then call `trade-feedback.getStrategyFeedback()` and assert the new strategy
+  bucket now shows wins/losses/totalPnl (exact arithmetic). Then confirm the live read
+  endpoint (`userFills`) is real against a funded wallet — a mock passing proves logic,
+  the live call proves the endpoint + fill shape (`dir:'Buy'/'Sell'`, `side:'B'/'A'`).
+- **Set the honest expectation:** the ledger only captures fills AFTER deploy, and can't
+  learn until positions round-trip. If the venue has zero realized PnL, the plumbing is
+  correct-but-empty — build it BEFORE trades close (capture in place) but don't claim it's
+  "learning" until real closed trades exist.
+Full worked recipe (the 4-file wiring, the ledger module, getUserFills read-only method,
+the on-chain-position reconciliation math, the agent-cold-layer-not-hot-path decision, the
+end-to-end test): `references/shared-learning-loop-wiring.md`.
+
+### The bot alerts ITSELF on round-trips — not Hermes (DEMI preference, corrected)
+When the reconciler detects a close and DEMI wants to be pinged, the alert must come from
+**the bot's own Notifier**, not a Hermes cron/watch. DEMI's exact steer: "telegram bot should
+be able to alert not you." The mechanics fall out naturally because the reconcile runs INSIDE
+the TP guard, which already holds a `notifier`:
+- **Make `reconcile` RETURN the closed trades** (`{ closed, stillOpen, closedTrades }`), then the
+  guard (which owns the notifier) fires one `notifier.sendTelegram(...)` per round-trip. Same
+  channel as the fill/TP alerts — same infra DEMI already reads. No new watcher, no Hermes in the loop.
+- **Wrap the alert send in try/catch** — a Telegram failure must never fail the guard cycle
+  (same non-blocking rule as the ledger writes).
+- **Sign-before-`$` formatting:** a negative PnL rendered as `${pnl>=0?'+':''}$${pnl}` prints the
+  ugly `$-10.00`. Use `const sign = pnl>=0?'+':'-'` then `${sign}$${Math.abs(pnl).toFixed(2)}` →
+  `-$10.00`. Caught this only because the end-to-end test asserted the exact rendered string —
+  format bugs are invisible until you assert the literal output.
+- The notifier auto-silences on staging (`STAGING==='1'` chokepoint), so a shadow deploy won't spam.
+
+## When a new venue "won't fire" — the SHARED-GUARD cross-venue mismatch (the "shouldn't it be trading like my main wallet?" ask)
+After wiring a new venue (HIP-4) into the shared loop, DEMI will ask "shouldn't it
+be firing?" and the honest answer is often **it's a real bug, not "waiting"** — the
+new venue's opportunities are being BLOCKED by the shared safety guard applying the
+WRONG venue's rules. Diagnose from the live log FIRST, then fix venue-aware:
+- **Read the block reasons before theorizing.** `pm2 logs demi-server --lines 300
+  --nostream | grep -iE 'guard blocked <venue>|<strat>.*skip'` then pipe through
+  `sed`/`sort`/`uniq -c` to rank reasons. Separate the CORRECT skips (strategy's own
+  rules — e.g. HIP-4's `already holding a side of outcome NNN (one position per
+  outcome)`, or `not opted in`) from the WRONG blocks (the shared PM guard).
+- **The mismatch class: the shared `safety-guard.js checkTrade()` judges the new
+  venue by Polymarket's bankroll + market rules.** HIP-4 opps carry
+  `sport:'soccer'` + `liquidity:$8-14` (real HL book depth) and get slammed by FIVE
+  PM-specific gates that measure the wrong thing: (1) position-size cap sized off PM
+  equity (`Position $10.5 > max $1.47` — tiny + fluctuating because the PM portfolio
+  read is near-empty / stale from a dead RPC), (2) total-exposure %, (3) 20% cash
+  reserve, (4) the sport whitelist (`mlb,nba,nhl,ufc,esports` — soccer isn't in it,
+  so `Sport not whitelisted: 'soccer'` blocks EVERY WC outcome even after fixing
+  size/liquidity), (5) the `soccer:2000` dead-market liquidity floor (thin HIP-4
+  books can't clear it, and the `clobDepth>=size*1.5` bypass fails on $8 depth).
+- **Fix = make the guard venue-aware; bypass ONLY the PM-portfolio/PM-market gates
+  for `opportunity.venue==='hyperliquid'`.** Define `const isHyperliquid =
+  opportunity.venue === 'hyperliquid'` once at the top of the size-cap block, then
+  wrap each of the 5 gates with `if (!isHyperliquid && <original condition>)`. The
+  new venue is already gated correctly by its OWN `execute()`-time checks against
+  ITS bankroll (per-user stake, `usdcFree>=stake`, live `ask*askSz>=stake` depth,
+  `PHANTOM_CAP` edge ceiling, fresh-edge recheck, per-outcome maxPositions) — the PM
+  floor is redundant AND wrong. **KEEP the account-level, venue-agnostic gates
+  applied to both** (halt, daily-loss, hourly/daily rate limits,
+  `LIVE_TRADING_CONFIRMED` file). Don't blanket-skip the whole guard.
+- **This is loosening a live safety gate → circuit-breaker discipline applies.**
+  GO-gate it. But note it's LOW-risk to ship direct once you've proven the strategy's
+  own depth/phantom/fresh-edge gates are STRICTER than the PM floor being removed —
+  the bypass can only let a HIP-4 opp reach ITS OWN gates, not skip them.
+- **The counterintuitive answer to "will it trade LESS?": no, MORE.** Removing the
+  wrong blocks UNBLOCKS firing. What still (correctly) caps volume is structural and
+  stays: one-position-per-outcome + hold-to-resolution. So the venue is episodic by
+  design — it fires on a NEW un-held divergence or when a held position closes, not
+  high-frequency. If every current opp maps to an already-held outcome, "not firing
+  right now" is the per-outcome rule working, NOT a block.
+- **VERIFY the guard change with a unit test against the REAL safety-guard module:**
+  a HL opp must PASS all 5 gates; a PM opp with the same params must STILL be blocked
+  by each (proves you didn't punch a hole in the Polymarket path). Assert the exact
+  block reasons (`Position $X > max`, `Sport not whitelisted`, `Illiquid`). Then
+  restart and confirm the `guard blocked <venue>` lines are GONE from the live log.
+- **Ground-truth the pilot state before declaring "working":** pull `getSpotState`
+  for the pilot — free USDC (has capital?), held outcome coins (`+N` balances), and
+  compare held-outcome-IDs vs the live outcome universe (`outcomeMeta`). That tells
+  you definitively whether "not firing" = blocked (bug) vs = every opp is an
+  already-held outcome (correct) vs = no un-held divergence exists right now.
+Full worked recipe (the 5 gates + exact wrap edits, the venue-tag routing, the
+real-module PM-still-blocked unit test, the pilot ground-truth probe):
+`references/venue-aware-safety-guard.md`.
+
+## PR hygiene when another agent is active on the same trading repo
+When a live trading PR was assembled while another agent pushed to `origin/main`, treat
+"mergeable" as necessary but not sufficient. Clean the PR branch before asking DEMI or
+the peer agent to review it:
+- Strip accidental backup/scratch files from broad `git add -A` commits (`*.bak*`,
+  timestamped recovery files, unreferenced analysis scripts, generated build dirt).
+- Fix CRLF/LF phantom rewrites before push: restore the file from `origin/main`, reapply
+  only the real code changes, and verify the **normal** diff is reviewable (not just
+  `git diff -w`). A `server/api.js` `+4855/-4800` phantom diff hid a real `+57/-2` endpoint
+  change — do not leave that for reviewers.
+- Re-run syntax, focused money-path probes, and frontend build on the CLEANED branch;
+  reset build artifacts after the build.
+- Push a PR branch and comment with exactly what hygiene changed + verification results;
+  don't push directly to `main` while a peer agent is live unless DEMI explicitly chooses it.
+Full cleanup recipe and HIP-4 PR #222 example: `references/pr-hygiene-active-peer-merge.md`.
+
+## Deploying a strategy-file change to the LIVE bot (pm2, not deploy.sh)
+- Prod runs under **pm2 `demi-server`** (not the docker `deploy.sh`). A strategy/API change needs
+  a `pm2 restart demi-server --update-env` to load; a dashboard change needs `npm run build`
+  (rebuilds `dist/`, no restart). The restart briefly interrupts the sports loop (~seconds; it
+  resumes on boot — routine, dozens of prior restarts) and reloads code from disk.
+- **Staging is a SEPARATE checkout** (`/root/polymarket-arbitrage-bot-staging`, `SHADOW_GATES=1`,
+  NO signing keys → physically cannot move money) and can lag prod by many commits — it may not even
+  have the venue code yet. To shadow-test on staging, `git fetch <prod-path> main` + checkout the
+  feature branch there first. A shadow gate test can prove new gate LOGIC fires (opted-in wallet
+  passes, non-opted skips) even with no keys — the execute() path stops at the creds check, which is
+  exactly the "past the gate" proof you want.
+- **CRLF footgun:** the repo's JS files are CRLF; a python string-writer normalizes to LF and git
+  then shows EVERY line changed (a 15-line edit -> 9600-line phantom diff). Detect with
+  `git diff -w --stat` (real change size) and restore endings with a python
+  `.replace(b'\r\n',b'\n').replace(b'\n',b'\r\n')` pass before committing, so `git blame`/review stay clean.
+- **REMOTE-PATCH MECHANICS — prefer pull-local → fuzzy `patch` tool → scp-back over remote string-writers.**
+  Editing VPS files by `scp`ing a python string-writer script (or worse, a `ssh ... python3 << 'PYEOF'`
+  heredoc) is brittle and burned two attempts this session: (1) a `raw.replace()` anchor silently
+  no-ops when the on-disk text differs by a whitespace/CRLF hair from your assumed string, and the
+  script's own `assert count==1` then throws AFTER a partial edit — leaving you unsure what changed;
+  (2) template-literal backticks + `${...}` + emoji `\u` escapes inside a remote heredoc get mangled
+  by the shell before python ever sees them (`unexpected EOF while looking for matching quote`). The
+  reliable path: `scp demi-poly:<path> /tmp/f.local.js`, apply the `patch` tool (fuzzy match tolerates
+  minor whitespace drift, auto-lints, returns a real diff), then `scp` it back and `node -c` on the VPS.
+  Idempotency-guard any string-writer you DO keep with an early `if MARKER in raw: skip` so a re-run
+  can't double-apply. And when a unit test embeds a REPLICA of the code under test (an inline
+  `buildAlert`), fixing the real file leaves the replica stale → the test fails on format you already
+  fixed; point the test at the real module, or assert against the deployed source text, so it can't drift.
+- **Protect uncommitted prod hotfixes:** prod's working tree often carries live-edited tracked files
+  not on any branch (e.g. `gpu-client.js`, `trading-loop.js`, `loop-manager.js`). Snapshot them
+  before any branch op, stage ONLY your files, and prefer `git branch -f main <feature>` (ref update,
+  worktree untouched) over a checkout that could clobber them.
+- **Verify the deploy from the LIVE log, not the restart exit code:** after restart, grep
+  `demi-server-out.log` for the NEW gate message (e.g. the per-user skip reason) to prove the new
+  code path is the one running — a green pm2 status only means the process booted.
+- **MERGING when ANOTHER AGENT is active in the same repo (the "the other agent already pushed to
+  main" situation).** DEMI runs a dual-machine + multi-agent setup, so `origin/main` can move under
+  you mid-session. Deploy discipline here shipped by moving the LOCAL `main` ref (`git branch -f`) on
+  the prod worktree WITHOUT pushing — so local `main` and `origin/main` DIVERGE (local ahead with your
+  N commits, origin ahead with the peer's push). Reconcile safely:
+  1. **`git fetch origin` and read the divergence BEFORE touching anything:** `git rev-list
+     --left-right --count origin/main...main` (are you ahead/behind/both?), `git diff --name-only main
+     origin/main` (conflict surface — overlapping files = real risk, not a clean FF). NEVER force-push
+     over a branch a peer just pushed to.
+  2. **Merge in an ISOLATED `git worktree`, never the running prod checkout:** `git worktree add -f
+     /root/_merge <yourtip>` then `git merge origin/main` there. Prod's checkout + its uncommitted
+     hotfixes stay untouched. Symlink `node_modules` from prod so the build works.
+  3. **"Clean auto-merge" ≠ correct — re-verify on the MERGED tree.** git's ort strategy resolves
+     non-overlapping regions of the same file silently; that's conflict-free, not proven-correct. Re-run
+     the money-path unit tests (venue-guard: HL passes / PM still blocked), rebuild the frontend, and
+     `node -c` the money-path files ON the merged worktree before trusting it.
+  4. **Confirm it's a true fast-forward (peer's work preserved as a parent, no history rewrite):**
+     `git merge-base --is-ancestor origin/main <mergetip>` → if origin/main is an ancestor, the push is
+     a clean FF and the peer's commit survives as a merge parent. If NOT an ancestor, you'd need a force
+     — STOP and reconsider.
+  5. **DEMI's preference under an active peer: PR, don't push straight to main.** Even when the git is a
+     clean FF and everything's verified, when a SECOND agent is actively working the repo DEMI chose
+     "open a PR so the other agent can review before it lands" over "push to main now." Push your merge
+     to a feature branch, open the PR into main (call out the commits that OVERLAP the peer's domain in
+     the PR body), and leave the merge to human/peer approval. Rationale: force-landing onto a branch a
+     peer just touched clobbers their mental model even when the bytes reconcile. Offer the choice
+     (PR / push-direct / hold) rather than auto-deciding — but lead with PR when a peer is live.
+  6. **DEMI-DELIVERY / TELEGRAM: send a real message to prove a claim, don't just format it.** When the
+     deliverable is "the bot texts him," the not-yet-verified piece is DELIVERY, not formatting. Construct
+     the actual Notifier and do ONE real labeled `sendTelegram` test (assert `ok===true`) — a unit test
+     of the string proves layout, only a live send proves the channel works. (`dotenv`/`node_modules`
+     resolve from the REPO dir, so run the probe from inside the repo, not `/tmp`.)
+
+## Diagnosing "why isn't the bot trading?" — DON'T THEORIZE, QUERY GROUND TRUTH (the five-wrong-turns lesson)
+When DEMI asks "why haven't we been trading" / "shouldn't it be on" / "did the money go
+back to X", the failure mode is answering from CONFIG or INFERENCE and being wrong. One
+session produced FIVE consecutive wrong conclusions on a live-money bot, each corrected only
+by pulling actual live state: (halted→wrong) → (capital-starved→wrong, wallet had funds) →
+(zombie loop→wrong, loop had 16k scans) → (session-state stopped→wrong, marked running) →
+(finally: the strategy evaluates the WRONG wallet). Every wrong turn was a guess from a file;
+every correction came from a live query. The rule: **for any "why isn't it doing X" on the
+bot, the FIRST move is a ground-truth pull, not a hypothesis.** State confidence honestly and
+walk back cleanly when the data contradicts you — do NOT defend a prior guess.
+
+The ground-truth checklist, run these BEFORE proposing any cause:
+- **Live venue balance, not the config or the vault claim.** HL spot USDC via the HL info API
+  (`spotClearinghouseState` for spot USDC + held `+N` outcome coins; `clearinghouseState` for
+  perps/withdrawable). Polymarket via the proxy wallet on-chain. The vault's P0 line and the
+  bot's cached portfolio can BOTH be a month stale — I asserted "capital starved" when the
+  wallet had $173 free because I inferred drawdown from losing trades instead of querying.
+- **Which wallet is the strategy actually evaluating?** `pm2 logs demi-server --lines 300
+  --nostream | grep -iE '<strat>' | grep -oE 'wallet 0x[a-f0-9]{6}' | sort | uniq -c`. The
+  loop scans opps globally then each running wallet-loop tries to EXECUTE them with its OWN
+  address. If the wallet with the key/funds/allowlist entry isn't in that list, it's never
+  evaluated — and the OTHER wallets correctly skip ("not opted in and not a pilot"). This was
+  the actual root cause and it was invisible until I counted wallets in the log.
+- **Is the loop even instantiated for that wallet?** `data/user-session-state.json`: a wallet
+  needs `startedAt && !stoppedAt` to auto-resume on restart. But "marked running" ≠ "actually
+  scanning" — cross-check against real scan activity in the log. `POST /api/bot/start` (auth via
+  a minted `lo_` API key, see below) reinstantiates a dead loop; its response reveals `scanCount`
+  + `lastScanAt` which tells you if the loop was live all along.
+- **What is it skipping on, RIGHT NOW?** The skip lines are the answer, read them literally:
+  `ask depth $8.00 < stake $10.5` (thin book, untradeable at min stake — NOT a bug),
+  `already holding a side of outcome NNN` (per-outcome cap working), `edgeThreshold 0.03` floor
+  (a 2.2% edge is below the gate, correct). Most "it's dead" is the safety gates + thin liquidity
+  working as designed, not a fault. Distinguish "correctly quiet" from "wrongly blocked."
+
+Minting an API key to hit an authed bot endpoint from the VPS (no browser): keys are stored as
+SHA-256 hashes in `data/api-keys.json` so you can't recover one, but `lib/api-auth.js`'s
+`generateKey(wallet)` mints a fresh one (auto-revokes the wallet's prior key, clean + reversible):
+`KEY=$(node -e "console.log(require('./lib/api-auth').generateKey('0xWALLET'))")` then
+`curl -s -X POST http://localhost:<port>/api/bot/start -H "X-API-Key: $KEY"`. Note the `/api`
+prefix (bare `/bot/start` 404s). Get the port from `ss -tlnp | grep node`, not a guess.
+
+The "money moved from HL back to Polygon" class of question is usually a FALSE PREMISE: HL spot
+USDC and Polymarket Polygon USDC are SEPARATE pools that never auto-transfer. "It went back" is
+almost always "the HL pile was traded down / is separate and untouched," not a sweep. Pull both
+balances and the HL trade ledger (`portfolio-hip4.json`) before accepting the premise.
+
+Fix "always be trading" the RIGHT way: it's rarely a flag flip. If capital + key + allowlist are
+present and it's still quiet, the cause is structural (wrong-wallet routing, thin books, per-outcome
+cap, edge floor) — and "loosen the gates to force fills" makes it trade WORSE (slippage into $2-8
+books = the exact losing pattern). Recommend the surgical routing/visibility fix, not gate-loosening,
+and GO-gate anything that re-arms live execution. Full worked investigation (the five wrong turns,
+every query that corrected them, the HL API calls, the wallet-routing root cause):
+`references/why-isnt-the-bot-trading.md`.
+
+## Building a public scanner + wallet/CEX execution product
+
+A scanner dashboard that can buy, sell, place exits, or delegate authority to agents is a NEW live-money loop, even when its default mode is paper. Load and follow `references/agentic-scanner-execution-gate.md` before implementation. It covers canonical onchain discovery vs promoted feeds, Rabby as signer rather than router, unsupported honeypot-chain semantics, fail-closed slippage, authenticated preview binding, real kill switches, honest exit-policy states, persistent shadow-agent rollout, third-party chart embed boundaries, draggable TP/SL architecture, and DEMI's required Fable → Sol → Sonnet → Opus build/review sequence.
+
+**UI truthfulness gate for Quick Buy, APE, TP, and SL:** Quick Buy and APE may only select a market and preset size; they do not bypass quote freshness, route verification, round-trip/sell simulation, policy limits, or wallet confirmation. An APE button is an aggressive preset, not permission for blind broadcast. TP/SL controls may be called active or automated only after a durable background executor has been verified to monitor prices and submit protected exits. If the backend only stores policies, label the UI and API response `DRAFT`, return `executable:false`, and state that every sell still needs a fresh quote, simulation, and wallet signature. A polished control that implies nonexistent automation is a money-path defect.
+
+When the product moves from scanner/paper mode to public self-custodial wallet swaps or NFT mints, also load `references/public-self-custodial-scanner-execution.md`. It defines public-wallet vs operator/admin authority, wallet-connect prominence, the honest execution ladder, verified-ABI mint simulation, unsupported-chain coverage labels, action-first trading UI hierarchy, and the mandatory post-integration security gate covering process-isolated signers, principal-relative round-trip loss, enforceable mint freshness or simulation-only fallback, per-user watchlist isolation, complete-vs-partial portfolio valuation, and fail-closed data labels.
+
+## Pitfalls
+- Treating wallet signature verification as account authorization → any stranger can create a wallet and become an operator; bind signed addresses to a server-owned operator allowlist/enrollment and separate admin authority.
+- Treating `CONTROLS_READY=1` or `LIVE_ENABLED=0` as a security boundary → flags do not implement holdings/PnL/exposure controls and can be flipped; compile live submission out of incomplete preview builds.
+- Treating a halt as a bug to work around → it's a capital-protection feature. Never bypass.
+- Answering "why isn't it trading" from config/vault/inference instead of a live ground-truth pull → you WILL be wrong; five times in one session. Query first, theorize never.
+- Resetting without reconciling → you can resume into a wrong-state position.
+- Editing the live loop without a backup + revert command in hand → violates the core invariant.
+- Assuming pm2 "online" means healthy → check heartbeat + recent trade/reconcile logs.

package/dist/assets/skills/venue-capability-boundaries/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: venue-capability-boundaries
+description: Check what each venue supports before routing user requests.
+category: trading
+---
+
+> Oracle native tools: `oracle_cli` (read/prepare), `vault_status`, `signer_status`, `signer_execute` (needs human confirmationNonce), `skill_load`. No generic shell. No fleet SSH.
+
+
+# Venue capability boundaries
+
+Users ask for things venues don't support. Cross-reference before routing.
+
+## Hyperliquid HIP-4
+
+BTC daily binaries only (2026-08). No geopolitical/event markets on mainnet.
+→ Event bets → Polymarket, not HL.
+
+## Hyperliquid HIP-3 builder dexs
+
+Perps only. No spot equities. `xyz:NVDA` is a perp.
+→ "spot NVDA on TradeXYZ" must clarify: HIP-3 has no spot.
+
+## TradeXYZ (xyz)
+
+96+ assets on HL, all perps: `xyz:NVDA`, `xyz:TSLA`, `xyz:AAPL`, `xyz:SPX`.
+
+## Oracle fees
+
+Swaps: 10 bps. Bridges: +10 bps. HL builder codes: cap 10 bps perp / 1% spot.
+
+Live HL builder dex data + HIP-4 docs: `references/hip4-and-builder-limits.md`.