Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

docs(ops): tell a floor-held reclaim skip apart from an empty wallet

nirholas8703867bf48d
diff --git a/docs/economy-master.md b/docs/economy-master.md
index 228c35ad8..27afbcbdf 100644
--- a/docs/economy-master.md
+++ b/docs/economy-master.md
@@ -240,6 +240,47 @@ node scripts/sniper-fleet-restore.mjs --apply --yes # top up the fundable arms
Sweeps below `ECONOMY_SWEEPBACK_MIN_SOL` (0.01 SOL) are skipped as dust.
+### A floor skip says whether the wallet is empty or fenced
+
+Both reclaim legs skip a wallet whose balance sits under its keep line (its
+operating floor plus the anti-oscillation buffer). That skip used to print the
+bare string `at_or_below_floor`, which cannot distinguish the two situations an
+operator has to tell apart:
+
+| Situation | What it means | What fixes it |
+| --- | --- | --- |
+| The wallet holds ~0 SOL | The source is genuinely empty | Owner capital to the economy master, nothing else |
+| The wallet holds real SOL under a higher floor | The platform owns the SOL; a configured floor is fencing it | Review that wallet's `minSol` in [`api/_lib/solana-signers.js`](../api/_lib/solana-signers.js), or accept the fence |
+
+They printed identically, so three consecutive triage sessions read the second as
+the first. On 2026-09-09 the x402 ring treasury (`wwwww…ccrU`) held 0.055 SOL
+against a `minSol` of 0.1, and reported the same `at_or_below_floor` as the 110
+genuinely-empty agent wallets beside it, while the ring payer was 0.0012 SOL short
+of the hard floor that had stopped settlement.
+
+A floor skip now carries both numbers, in the `<have><<need>` shape
+`below_swap_rent` already uses, and the run totals the fenced SOL:
+
+```json
+{
+ "name": "pump-x402-launcher",
+ "reason": "at_or_below_floor:0.054994966<0.11",
+ "heldSol": 0.054994966,
+ "floorSol": 0.1,
+ "keepSol": 0.11
+}
+```
+
+- `keepSol` is the number that actually blocked the sweep. Reporting and sizing
+ both read `reclaimKeepLineSol()`, so the message can never explain a refusal the
+ code did not make.
+- `floorHeldSol` on each reclaim result, and `skipped_floor_held_sol` on the
+ ledger's summary row, total the fenced SOL. **Zero is the only state that needs
+ owner money.** Non-zero means the SOL exists on a platform wallet.
+- The ledger's `skipped_reasons` histogram buckets on the class before the colon,
+ so a fleet-wide run still reports `{"at_or_below_floor": 110}` rather than 110
+ buckets of one.
+
To see what a run would do without moving anything:
```bash
diff --git a/docs/ops/production-log-triage.md b/docs/ops/production-log-triage.md
index 21c1949fb..681d4d1a5 100644
--- a/docs/ops/production-log-triage.md
+++ b/docs/ops/production-log-triage.md
@@ -255,7 +255,13 @@ HTTP 502/503 GET|POST /api/x402/*, /api/mcp ua: threews-x402-autonomous/1.0 or
`X402_SPONSOR_SOL_FLOOR_LAMPORTS`. Self-heal territory: run
`POST /api/cron/treasury-topup`; its `reclaimIdleAgentSol` leg refunds the
fee wallet from idle agent SOL (commit `d6a7bf2a4`). No owner money needed
- unless every reclaim source reports `at_or_below_floor`.
+ unless every reclaim source reports `at_or_below_floor` **and the run reports
+ `skipped_floor_held_sol` 0**. A floor skip carries its numbers
+ (`at_or_below_floor:<held><<keep>`), so a non-zero held total means the SOL is
+ sitting on a platform wallet behind a configured floor, not that the fleet is
+ empty; review that wallet's `minSol` before asking for capital. See
+ [economy-master.md](../economy-master.md) "A floor skip says whether the
+ wallet is empty or fenced".
2. `--grep "data_unavailable"` hits = paid endpoints refunding honestly (no
charge) because no market source could answer. Since 2026-07-28
crypto-intel prices bonding-curve pump.fun mints from the pump.fun feed