yunus-0x · zenginamca00 · Mar 23, 2026 · Mar 23, 2026 · Mar 23, 2026 · Mar 23, 2026
diff --git a/.env.example b/.env.example
@@ -20,6 +20,10 @@ LPAGENT_API_KEY=your_lpagent_api_key_here
 # ── Telegram Notifications (optional) ─────────────────────────────────────────
 TELEGRAM_BOT_TOKEN=
 TELEGRAM_CHAT_ID=
+TELEGRAM_ALLOWED_USER_IDS=
+
+# ── Dangerous admin actions (disabled by default) ─────────────────────────────
+ALLOW_SELF_UPDATE=false
 
 # ── Misc ───────────────────────────────────────────────────────────────────────
 DRY_RUN=false

diff --git a/.gitignore b/.gitignore
@@ -5,9 +5,11 @@ node_modules/
 .env
 .env.*
 !.env.example
+.envrypt
 
 # User config (contains RPC URL, wallet key, API keys)
 user-config.json
+gmgn-config.json
 
 # Runtime state (position tracking, lessons — user-specific)
 state.json
@@ -16,6 +18,10 @@ smart-wallets.json
 pool-memory.json
 token-blacklist.json
 strategy-library.json
+decision-log.json
+hivemind-cache.json
+signal-weights.json
+paper-positions.json
 
 # Logs
 logs/
@@ -25,3 +31,7 @@ logs/
 
 # Dev context
 context.md
+docs/
+
+# Test files
+test-*.js
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -112,22 +112,26 @@ Before `deploy_position` executes:
 - Position count must be below `maxPositions` (force-fresh scan, no cache)
 - No duplicate pool allowed (same pool_address)
 - No duplicate base token allowed (same base_mint in another pool)
-- If `amount_x > 0`: strip `amount_y` and `amount_sol` (tokenX-only deploy — no SOL needed)
-- SOL balance must cover `amount_y + gasReserve` (skipped for tokenX-only)
+- Deploy amount must include positive SOL (`amount_y` or `amount_sol`)
+- Range width must be at least the configured safe bins floor (`minBinsBelow`, never below 35)
+- Single-side SOL deploys must keep `bins_above=0`
+- SOL balance must cover `amount_y + gasReserve`
 - `blockedLaunchpads` enforced in `getTopCandidates()` before LLM sees candidates
 
 ---
 
 ## bins_below Calculation (SCREENER)
 
-Linear formula based on pool volatility (set in screener prompt, `index.js`):
+Linear formula based on pool volatility (set in screener prompt, `index.js`). The lower/upper bounds are configurable, with a hard safety floor of 35 bins:
 
 ```
-bins_below = round(35 + (volatility / 5) * 34), clamped to [35, 69]
+bins_below = round(minBinsBelow + (volatility / 5) * (maxBinsBelow - minBinsBelow))
+clamped to [minBinsBelow, maxBinsBelow]
 ```
 
-- Low volatility (0) → 35 bins
-- High volatility (5+) → 69 bins
+- Volatility must be finite and > 0; zero/missing volatility is treated as an unusable feed
+- Low valid volatility → minBinsBelow
+- High volatility (5+) → maxBinsBelow
 - Any value in between is valid (continuous, not tiered)
 
 ---

diff --git a/FINDINGS.md b/FINDINGS.md
@@ -0,0 +1,90 @@
+# Meridian — Findings & Issues (Draft)
+
+_Paper validation run on VPS (`simulator-paper` branch, DRY_RUN). Compiled 2026-06-02._
+_Goal: document issues found while paper-trading so they can be fixed/tested with data, not guesses._
+
+---
+
+## Current data snapshot (evidence)
+
+```
+Sample: 5 closed / 2 open  — Win/Loss: 0 / 5
+Net PnL: -$1.17 · Fees: $0.08 · Avg L: -0.83% · Worst: -1.22%
+Exit breakdown: OOR 3 (avg -0.89%) · STALE 2 (avg -0.72%)
+Open: GACHA-SOL (in-range 0%, 90m) · GACHA-USDC (in-range 0%, 51m)
+```
+
+**Headline:** every position so far has **in-range ~0–9% and ~$0 fees** — including clean/mature pools (three-SOL $3M mcap/182 SOL fees, GACHA 14% bots/91 organic). Losses are small & controlled (exit rules work), but **zero fee capture**.
+
+---
+
+## Issues
+
+| # | Severity | Issue | Status |
+|---|---|---|---|
+| 1 | 🔴 High | Single-sided bid_ask downside → in-range ~0% → $0 fees (root cause of all losses) | Open — needs decision |
+| 2 | 🔴 High | Screening picks non-SOL-quote pools (e.g. GACHA-USDC); deploy assumes SOL | Must-fix before LIVE |
+| 3 | 🟡 Med | Strategy locked to `bid_ask` (curve/spot blocked by prompt + executor) | Open |
+| 4 | 🟡 Med | Bin step screened 80–125; meme guides recommend 250–400 → fast OOR | Open |
+| 5 | 🟡 Med | Thin candidate funnel on `meteora` source (no GMGN key) | Open |
+| 6 | 🟡 Med | Paper bridge dedup is pool-level only (held GACHA-SOL + GACHA-USDC = 2x same base) | Open |
+| 7 | 🟡 Low | Race condition: tickPaperPositions (async) vs bridge openPaperPosition can drop a trade (~1%) | Open |
+| 8 | 🟢 Cosmetic | Duplicate "Deployed" Telegram notifs + report≠paper when bridge skips | Open |
+| 9 | 🟢 Cosmetic | `editMessageText 400: message not modified` (live progress edit) | Open |
+| 10 | 🟢 Cosmetic | "undefined eligible from N screened" (simulator branch lacks main's fix) | Open |
+| 11 | ✅ Resolved | Default model `openrouter/healer-alpha` retired (404) | Fixed → deepseek-v4-flash |
+
+---
+
+## Detail
+
+### 🔴 #1 — Structural: single-sided bid_ask downside earns ~0 fees
+- **What:** Deploy = single-sided SOL, bins below only (`bins_above=0`). Position sits at the TOP edge of its range (upper bound = active bin at deploy). Any upward price move → instantly OOR-up → $0 fees. Only earns when price FALLS into the bins.
+- **Evidence:** 7 positions, all in-range 0–9%, ~$0 fees — even clean/mature pools. Not token-dependent → structural.
+- **Impact:** No fee capture. Strategy behaves as "DCA buy-the-dip", NOT fee-farming. Edge depends on tokens dipping-then-recovering; current tokens pump up / chop.
+- **Proposed (test later):** allow centered shapes (curve/spot, or `bins_above > 0` two-sided) → stay in-range → earn fees. Community proof: Kinji `curve` +8.43%.
+
+### 🔴 #2 — Non-SOL-quote pools selected
+- **What:** `screening.js` checks quote organic/warnings but has NO "quote == SOL" filter. So USDC-quote pools (GACHA-USDC) pass. Deploy uses `amount_y` = quote token; for a USDC pool that means USDC, not SOL — but logic/report assume SOL.
+- **Impact:** Paper = harmless (bridge uses USD). **LIVE = real bug** (deploys wrong token / wallet lacks USDC).
+- **Proposed:** add SOL-quote-only filter to screening before going live.
+
+### 🟡 #3 — Strategy locked to bid_ask
+- Prompt: "strategy = bid_ask, always use this, never change." Executor enforces single-side SOL + `bins_above=0`. Cannot use curve/spot without code/config changes.
+
+### 🟡 #4 — Bin step too narrow for memes
+- Config screens `minBinStep 80 / maxBinStep 125`. Practitioner guides: 250–400 for volatile memes (wider price coverage → stays in range). Narrow bins → fast OOR.
+
+### 🟡 #5 — Thin funnel (meteora source)
+- On `screeningSource: meteora` + Jupiter bot metric (`maxBotHoldersPct 30`). Many trending pools are botty (Magpie 42%) → few candidates. Community uses `screeningSource: gmgn` (different universe + bot metric) for more flow — requires GMGN_API_KEY (not set).
+
+### 🟡 #6 — Bridge dedup is pool-level
+- Bridge skips duplicate POOL, but not duplicate BASE TOKEN. Held GACHA-SOL + GACHA-USDC simultaneously (both base = GACHA). Live executor has base-mint dedup; paper bridge doesn't.
+
+### 🟡 #7 — Race condition (low prob)
+- `tickPaperPositions` holds stale `state` across `await fetchNewCandles`; if bridge `openPaperPosition` saves during that window, tick's save can overwrite it → trade dropped (~1%/deploy). `evaluatePaperExits` is sync (safe).
+
+### 🟢 #8–10 — Cosmetic
+- Dup deploy notifs; editMessageText 400; "undefined eligible" label. None affect behavior/data.
+
+---
+
+## Branch / config notes (confirmed)
+
+- **GMGN screening** (`screeningSource: meteora|gmgn`, `gmgn-config.json`, `tools/gmgn.js`) exists on **experimental + simulator** branches, NOT on `main`. (Meridian Helper bot answers from `main` context → says "no GMGN" — correct for main only.)
+- Experimental extras: `repeatDeployCooldown`, `emergencyPriceDropPct`, `gmgnRequireKol`.
+- Agent names: "Hunter Alpha" (screener) / "Healer Alpha" (manager) = also the retired OpenRouter stealth-model aliases.
+
+## Custom additions on `simulator-paper` (for record)
+- Paper bridge: dry-run deploy → `openPaperPosition` (executor.js) — covers cron/auto/manual
+- `evaluatePaperExits`: SL / TP / trailing / OOR / **STALE dead-money** cull
+- `paper-stats.mjs`: Charonica-style validation gate + live open-position view
+- Provider routing (pin DeepSeek), Telegram topic (thread 1398)
+
+---
+
+## Open questions / next steps
+1. After ~15–20 closed trades: if in-range stays ~0% → confirm structural → decide on curve/spot or two-sided.
+2. Get GMGN_API_KEY → A/B test `gmgn` vs `meteora` source.
+3. Add SOL-quote filter **before any live trading**.
+4. Decide: keep Meridian's "DCA buy-the-dip" thesis, or reshape toward fee-farming (centered ranges).
diff --git a/README.md b/README.md
@@ -2,6 +2,8 @@
 
 **Autonomous Meteora DLMM liquidity management agent for Solana, powered by LLMs.**
 
+**Links:** [Website](https://agentmeridian.xyz) | [Telegram](https://t.me/agentmeridian) | [X](https://x.com/meridian_agent)
+
 ---
 
 ## What it does
@@ -26,6 +28,12 @@ Meridian runs a **ReAct agent loop** — each cycle the LLM reasons over live da
 
 A third **health check** runs hourly to summarize portfolio state.
 
+### Agent harness
+
+Meridian's agent harness is the runtime wrapper around every autonomous cycle. It gives both **main** and **experimental** agents the same control loop: load live state, inject relevant memory, expose only role-appropriate tools, execute tool calls, and return a readable cycle report.
+
+The harness also keeps a structured decision log in `decision-log.json` for deployments, closes, skips, and no-deploy outcomes. Each entry records the actor, pool or position, summary, reason, key risks, metrics, and rejected alternatives. Recent decisions are injected back into the system prompt and are available through `get_recent_decisions`, so the agent can answer "why did you deploy?", "why did you close?", or "why did you skip?" without guessing after the fact.
+
 **Data sources used by the agents:**
 - `@meteora-ag/dlmm` SDK — on-chain position data, active bin, deploy/close transactions
 - Meteora DLMM PnL API — position yield, fee accrual, PnL
@@ -73,6 +81,16 @@ DRY_RUN=true                           # set false for live trading
 
 > **RPC**: defaults to `https://pump.helius-rpc.com` (no key needed). Override with `RPC_URL=` in `.env`.
 
+Optional encrypted `.env` flow:
+
+```bash
+cp .env .env.raw
+printf "replace-with-a-long-local-key\n" > .envrypt
+npm run env:encrypt
+```
+
+Meridian loads envrypt-style encrypted values automatically. Keep `.env.raw` and `.envrypt` local; both are gitignored.
+
 **4. Copy the example config**
 
 ```bash
@@ -88,6 +106,32 @@ npm start      # live mode
 
 On startup Meridian fetches your wallet balance, open positions, and the top pool candidates, then begins autonomous cycles immediately.
 
+### Run with PM2
+
+PM2 is supported and is the recommended way to keep Telegram control online on a VPS:
+
+```bash
+npm install
+npm run pm2:start
+pm2 save
+```
+
+To update an existing PM2 install:
+
+```bash
+git pull
+npm install
+npm run pm2:restart
+```
+
+If the process restarts repeatedly after an update, inspect the app error first:
+
+```bash
+npm run pm2:logs
+```
+
+Most post-update PM2 crashes are app startup errors, commonly from skipping `npm install` after `package-lock.json` changed, starting PM2 from the wrong directory, or missing `.env` / `user-config.json` values. Avoid `nohup`; it runs outside PM2 and can leave Telegram polling in a duplicate unmanaged process.
+
 ---
 
 ## Config reference
@@ -101,7 +145,7 @@ All fields are optional — defaults shown. Edit `user-config.json`.
 | `dryRun` | `true` | Simulate all transactions without submitting |
 | `deployAmountSol` | `0.5` | SOL to deploy per new position |
 | `maxPositions` | `3` | Maximum concurrent open positions |
-| `minSolToOpen` | `0.07` | Minimum wallet SOL balance before opening a new position |
+| `minSolToOpen` | `0.55` | Minimum wallet SOL balance before opening a new position |
 | `managementIntervalMin` | `10` | How often the management agent runs (minutes) |
 | `screeningIntervalMin` | `30` | How often the screening agent runs (minutes) |
 | `managementModel` | `openrouter/healer-alpha` | LLM model for position management |
@@ -114,7 +158,7 @@ All fields are optional — defaults shown. Edit `user-config.json`.
 | `minHolders` | `500` | Minimum token holder count |
 | `timeframe` | `5m` | Candle timeframe used in screening |
 | `category` | `trending` | Pool category filter for screening |
-| `takeProfitFeePct` | `5` | Close position when unclaimed fees reach this % of deployed capital |
+| `takeProfitPct` | `5` | Close position when PnL reaches this % threshold |
 | `outOfRangeWaitMinutes` | `30` | Minutes a position can be out of range before alerting / acting |
 
 ---
@@ -152,9 +196,20 @@ Free-form chat persists session history (last 10 exchanges), so you can have a c
 
 1. Create a bot via [@BotFather](https://t.me/BotFather) and copy the token
 2. Add `TELEGRAM_BOT_TOKEN=<token>` to your `.env`
-3. Start the agent, then send **any message** to your bot
+3. Set the exact Telegram chat and allowed controller user IDs in `.env`
+
+Meridian no longer auto-registers the first chat for safety. You must set:
+
+```env
+TELEGRAM_BOT_TOKEN=<token>
+TELEGRAM_CHAT_ID=<target chat id>
+TELEGRAM_ALLOWED_USER_IDS=<comma-separated Telegram user ids allowed to control the bot>
+```
 
-On first message, the agent auto-registers your chat ID and begins sending notifications. No manual chat ID configuration needed.
+Security notes:
+- If `TELEGRAM_CHAT_ID` is not set, inbound Telegram control is ignored.
+- If the target chat is a group/supergroup and `TELEGRAM_ALLOWED_USER_IDS` is empty, inbound control is ignored.
+- Notifications still go to the configured chat, but command/control is limited to the allowed user IDs.
 
 **Notifications sent:**
 - After every management cycle: full agent report (reasoning + decisions)
@@ -163,7 +218,7 @@ On first message, the agent auto-registers your chat ID and begins sending notif
 - On deploy: pair, amount, position address, tx hash
 - On close: pair and PnL
 
-You can also chat with the agent via Telegram using the same free-form interface as the REPL: `"check wallet 7tB8..."`, `"who are the top LPers in pool ABC..."`, `"close all positions"`, etc.
+You can also chat with the agent via Telegram using the same free-form interface as the REPL: `"check wallet 7tB8..."`, `"who are the top LPers in pool ABC..."`, `"close all positions"`, etc. Only explicitly allowed Telegram user IDs can issue commands.
 
 ---
 
@@ -185,53 +240,45 @@ Use `/thresholds` to see current values alongside performance stats.
 
 ---
 
-## Hive Mind (optional)
+## HiveMind
 
-Meridian includes an **opt-in** collective intelligence system called **Hive Mind**. When enabled, your agent anonymously shares what it learns (lessons, deploy outcomes, screening thresholds) with other meridian agents and receives crowd wisdom in return.
+Meridian includes a collective intelligence layer called **HiveMind**. By default it uses Agent Meridian at `https://api.agentmeridian.xyz` with the built-in public key, so agents can register, pull shared lessons/presets, and push learning events without a separate registration flow.
 
 **What you get:**
-- Pool consensus from other agents — "8 agents deployed here, 72% win rate"
-- Strategy rankings — which strategies actually work across all agents
-- Pattern consensus — what works at different volatility levels
-- Threshold medians — what screening settings other agents have evolved to
+- Shared lessons from other Meridian agents
+- Strategy presets and crowd performance context
+- Role-aware lessons injected into future screener/manager prompts when `hiveMindPullMode` is `auto`
 
 **What you share:**
 - Lessons from `lessons.json`
-- Deploy outcomes from `pool-memory.json` (pool address, strategy, PnL, hold time)
-- Screening thresholds from `user-config.json`
-- **NO wallet addresses, private keys, or SOL balances are ever sent**
+- Closed-position performance events: pool, pool name, base mint, strategy, close reason, PnL, fees, and hold time
+- Agent heartbeat metadata: agent ID, version, timestamp, and basic capability flags
+- **Private keys and wallet balances are never sent**
 
-**Impact:** 1 non-blocking API call per screening cycle (~200ms), 1 fire-and-forget POST on position close. If the hive is down, your agent doesn't notice.
+HiveMind failures are non-blocking. If Agent Meridian is unavailable, the agent logs a warning and keeps running.
 
 ### Setup
 
-**1. Get the registration token** from the private Telegram discussion.
+No manual HiveMind registration command is required for the shared Agent Meridian setup. `agentId` is generated automatically on startup if it is missing.
 
-**2. Register your agent**
+To use a private HiveMind API key, check the Telegram announcement channel and set it as `hiveMindApiKey`.
 
-```bash
-node -e "import('./hive-mind.js').then(m => m.register('https://meridian-hive-api-production.up.railway.app', 'YOUR_TOKEN'))"
-```
-
-Replace `YOUR_TOKEN` with the registration token from Telegram.
-
-This automatically saves your credentials to `user-config.json`. **Save the API key printed in the terminal** — it will not be shown again.
-
-**3. Done.** No restart needed. Your agent will sync on every position close and query the hive during screening.
+Relevant config fields:
 
-### Disable
-
-Clear both fields in `user-config.json`:
 ```json
 {
+  "agentId": "",
   "hiveMindUrl": "",
-  "hiveMindApiKey": ""
+  "hiveMindApiKey": "",
+  "hiveMindPullMode": "auto"
 }
 ```
 
-### Self-hosting
+Blank `hiveMindUrl` and `hiveMindApiKey` values intentionally fall back to the Agent Meridian defaults. Set `hiveMindPullMode` to `manual` if you do not want shared lessons and presets pulled automatically.
+
+### Disable
 
-You can run your own hive server instead of using the public one. See [meridian-hive](https://github.com/fciaf420/meridian-hive) for the server source code.
+There is currently no empty-string disable path for HiveMind; blank values fall back to the built-in Agent Meridian defaults. A true off switch should be implemented as an explicit config flag before documenting HiveMind as disabled by clearing fields.
 
 ---