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.

fix(economy): stop the reclaim dry run from advertising SOL sealed behind a retired key

nirholasafd3497903db
diff --git a/CHANGELOG.md b/CHANGELOG.md
index af5d6a2a4..d9593b19b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,12 @@
Public history for [three.ws](https://three.ws), newest first. New pages come from `added` dates in data/pages.json; everything else is curated in data/changelog.json. Also available as [JSON](https://three.ws/changelog.json) and [RSS](https://three.ws/changelog.xml), live at [three.ws/changelog](https://three.ws/changelog).
+## 2026-09-02
+
+- **Every showcased agent now has its own page**: Agent Spotlight entries got somewhere to live. Each one now has its own page with the agent standing in 3D, the full write-up instead of three clamped lines, a facts panel read live off the agent (skills, conversations, on-chain actions, upvotes), share buttons, and a rail of related entries in the same category. Sharing one finally works too: paste a link anywhere and it unfurls with that entry's headline and the agent's own card rather than the generic showcase image. If you submitted an entry, you can now edit or remove it, which you could not do before: an Edit link on your card opens the write-up ready to change, and removing takes two clicks so it cannot happen by accident. Ranking got fairer as well, with a stable order for entries published at the same moment instead of a shuffle between page loads. (`/spotlight`) `[improvement, feature]`
+- **Examples gains a voice, an AI's eye on 3D, and a filter**: Three more runnable examples and a way to find them. The avatar can now speak a line you type: the free text-to-speech lane synthesizes it and a new speakAudio() method routes the audio through the same analyser the built-in voice uses, so the mouth follows the real waveform instead of miming. A second example calls the look_at_model tool on the public MCP server and shows exactly what an AI assistant sees when it inspects a mesh: four rendered angles plus a plain-language read on the geometry, which is how an agent judges its own output and decides to try again. A third reads the live tool list off that same server, so the page can never advertise a tool that was renamed or dropped. With seventeen examples the page also gets a filter: type to search names, descriptions and tags, or narrow by tag, and the lanes fold away as they empty. A deep link always wins over an active filter. (`/examples`) `[feature, improvement, sdk]`
+- **The treasury's self-heal plan now only promises SOL it can actually move**: When the payment rail runs short of the SOL it needs to settle, the platform first tries to heal itself: it looks across its own agent wallets for idle funds and pulls them back to the wallet that pays fees. The preview of that plan was counting wallets it could never open. Eight custodial wallets were encrypted under a key retired during the 2026-07 move to Google Cloud, so the preview kept advertising their balance as available while every real run failed on them, and the plan looked the same the next time anyone checked. The preview now opens each wallet's key before listing it, exactly as a real run does, and reports the ones it cannot open separately with the reason. A plan that reads as capital on hand when the capital is unreachable is worse than no plan at all, and it cost two separate investigations. The health check's settlement hint was corrected to match: it no longer says owner funds are needed only once every wallet reports being at its floor, because a sealed wallet never reports that. `[fix, infra]`
+
## 2026-09-01
- **3D Drops** (`/drops`): Launch a supply-capped collection of AI-forged 3D characters. Pick a style, define weighted trait layers, and three.ws rolls the whole supply from a published seed: verifiable rarity, rigged animation-ready art, forged on reveal.
diff --git a/api/_lib/economy-sweepback.js b/api/_lib/economy-sweepback.js
index a0280b325..455ebb31c 100644
--- a/api/_lib/economy-sweepback.js
+++ b/api/_lib/economy-sweepback.js
@@ -655,38 +655,58 @@ export async function reclaimIdleAgentSol({ connection, network = 'mainnet', dry
// Biggest balances first: the run cap should spend its budget where the SOL is.
candidates.sort((a, b) => b.sol - a.sol);
- const { plan, skipped, totalSol } = planAgentReclaim(candidates, { maxWallets });
- if (dryRun) {
- return { master, reclaimedSol: totalSol, moves: plan.map((p) => ({ ...p, dryRun: true })), skipped, failed, readErrors };
- }
+ const { plan, skipped } = planAgentReclaim(candidates, { maxWallets });
const secrets = new Map(candidates.map((c) => [c.agentId, c.secret]));
const { recoverSolanaAgentKeypair } = await import('./agent-wallet.js');
- for (const p of plan) {
- // Recovery and broadcast are reported SEPARATELY on purpose. Sharing one
- // catch made an undecryptable wallet secret surface as a failed send, and
- // the alert then read "N failed send(s): The operation failed for an
- // operation-specific reason": a WebCrypto AES-GCM OperationError wearing
- // a Solana costume. That sent operators after RPC health and funding for a
- // key problem no amount of either could fix.
+
+ // Recovery and broadcast are reported SEPARATELY on purpose. Sharing one
+ // catch made an undecryptable wallet secret surface as a failed send, and
+ // the alert then read "N failed send(s): The operation failed for an
+ // operation-specific reason": a WebCrypto AES-GCM OperationError wearing
+ // a Solana costume. That sent operators after RPC health and funding for a
+ // key problem no amount of either could fix.
+ //
+ // The DRY run runs this same gate, which is the whole point of it being a
+ // function. It used to return the raw plan without ever touching a key, so a
+ // wallet whose secret is sealed under a retired WALLET_ENCRYPTION_KEY was
+ // advertised as reclaimable forever: `?dry=1` promised 0.12 SOL the real leg
+ // could never move, and two separate sessions read that plan and concluded
+ // the treasury cron would self-heal. A plan nothing can execute is worse than
+ // no plan, because it reads as capital on hand.
+ const openReclaimWallet = async (p, { audit }) => {
let keypair;
try {
- keypair = await recoverSolanaAgentKeypair(secrets.get(p.agentId), {
- agentId: p.agentId,
- reason: 'economy_reclaim',
- meta: { to: master, sol: p.sol },
- });
+ // A plan-only read passes NO audit context: the real leg's decrypt is a
+ // custody event worth a row, a dry run every scheduler minute is not.
+ keypair = await recoverSolanaAgentKeypair(
+ secrets.get(p.agentId),
+ audit ? { agentId: p.agentId, reason: 'economy_reclaim', meta: { to: master, sol: p.sol } } : null,
+ );
} catch (e) {
failed.push({
name: p.name, address: p.address, sol: p.sol, stage: 'recover',
reason: `secret_undecryptable: ${e?.message || 'unknown'}`,
});
- continue;
+ return null;
}
if (keypair.publicKey.toBase58() !== p.address) {
failed.push({ name: p.name, address: p.address, sol: p.sol, stage: 'recover', reason: 'keypair_address_mismatch' });
- continue;
+ return null;
}
+ return keypair;
+ };
+
+ if (dryRun) {
+ for (const p of plan) {
+ if (await openReclaimWallet(p, { audit: false })) moves.push({ ...p, dryRun: true });
+ }
+ return { master, reclaimedSol: round(moves.reduce((s, m) => s + m.sol, 0)), moves, skipped, failed, readErrors };
+ }
+
+ for (const p of plan) {
+ const keypair = await openReclaimWallet(p, { audit: true });
+ if (!keypair) continue;
try {
const signature = await sendSol({
connection,
diff --git a/api/_lib/ops/x402-settle-health.js b/api/_lib/ops/x402-settle-health.js
index 0ed06e0ae..c01a7205b 100644
--- a/api/_lib/ops/x402-settle-health.js
+++ b/api/_lib/ops/x402-settle-health.js
@@ -157,8 +157,11 @@ export function diagnoseSettleDrop({ noSolanaAccept, floorSignals, governorSkips
'X402_SPONSOR_SOL_FLOOR_LAMPORTS, so the ring has nothing payable and settlements stop. ' +
'Do NOT start at the facilitator. Check the sponsor balance, then let the free self-heal run: ' +
'POST /api/cron/treasury-topup?dry=1 (Bearer CRON_SECRET) to see the plan, then without ?dry=1 ' +
- 'to apply. Owner SOL is needed only when every reclaim source reports at_or_below_floor. ' +
- 'See docs/ops/production-log-triage.md.',
+ 'to apply. READ agent_reclaim.failed in that plan before you trust its total: a wallet whose ' +
+ 'secret does not decrypt is reported at stage `recover` and its SOL is unreachable until ' +
+ 'WALLET_ENCRYPTION_KEY (or WALLET_ENCRYPTION_KEY_PREVIOUS) can open it, so no cron run and no ' +
+ 'RPC tier will ever move it. Owner SOL is needed when every reclaim source reports ' +
+ 'at_or_below_floor or secret_undecryptable. See docs/ops/production-log-triage.md.',
};
}
// Nothing failed and nothing was withdrawn: we are refusing our own settles to
diff --git a/data/changelog.json b/data/changelog.json
index 772df63ff..7c28c48fc 100644
--- a/data/changelog.json
+++ b/data/changelog.json
@@ -1,6 +1,16 @@
{
"$comment": "Curated changelog entries for three.ws, the editorial layer of the public changelog. New PAGE launches are tracked automatically via the `added` field in data/pages.json; this file is for everything else holders care about: improvements, fixes, SDK releases, trading/payments capabilities, security work. scripts/build-page-index.mjs merges both sources into CHANGELOG.md, public/changelog.json, and public/changelog.xml. Newest first. Allowed tags: feature, improvement, fix, sdk, infra, docs, security. `link` is optional and must be a live three.ws path.",
"entries": [
+ {
+ "date": "2026-09-02",
+ "title": "Every showcased agent now has its own page",
+ "summary": "Agent Spotlight entries got somewhere to live. Each one now has its own page with the agent standing in 3D, the full write-up instead of three clamped lines, a facts panel read live off the agent (skills, conversations, on-chain actions, upvotes), share buttons, and a rail of related entries in the same category. Sharing one finally works too: paste a link anywhere and it unfurls with that entry's headline and the agent's own card rather than the generic showcase image. If you submitted an entry, you can now edit or remove it, which you could not do before: an Edit link on your card opens the write-up ready to change, and removing takes two clicks so it cannot happen by accident. Ranking got fairer as well, with a stable order for entries published at the same moment instead of a shuffle between page loads.",
+ "tags": [
+ "improvement",
+ "feature"
+ ],
+ "link": "/spotlight"
+ },
{
"date": "2026-09-01",
"title": "The community showcase is open",
@@ -25580,6 +25590,26 @@
"fix"
],
"link": "/examples"
+ },
+ {
+ "date": "2026-09-02",
+ "title": "Examples gains a voice, an AI's eye on 3D, and a filter",
+ "summary": "Three more runnable examples and a way to find them. The avatar can now speak a line you type: the free text-to-speech lane synthesizes it and a new speakAudio() method routes the audio through the same analyser the built-in voice uses, so the mouth follows the real waveform instead of miming. A second example calls the look_at_model tool on the public MCP server and shows exactly what an AI assistant sees when it inspects a mesh: four rendered angles plus a plain-language read on the geometry, which is how an agent judges its own output and decides to try again. A third reads the live tool list off that same server, so the page can never advertise a tool that was renamed or dropped. With seventeen examples the page also gets a filter: type to search names, descriptions and tags, or narrow by tag, and the lanes fold away as they empty. A deep link always wins over an active filter.",
+ "tags": [
+ "feature",
+ "improvement",
+ "sdk"
+ ],
+ "link": "/examples"
+ },
+ {
+ "date": "2026-09-02",
+ "title": "The treasury's self-heal plan now only promises SOL it can actually move",
+ "summary": "When the payment rail runs short of the SOL it needs to settle, the platform first tries to heal itself: it looks across its own agent wallets for idle funds and pulls them back to the wallet that pays fees. The preview of that plan was counting wallets it could never open. Eight custodial wallets were encrypted under a key retired during the 2026-07 move to Google Cloud, so the preview kept advertising their balance as available while every real run failed on them, and the plan looked the same the next time anyone checked. The preview now opens each wallet's key before listing it, exactly as a real run does, and reports the ones it cannot open separately with the reason. A plan that reads as capital on hand when the capital is unreachable is worse than no plan at all, and it cost two separate investigations. The health check's settlement hint was corrected to match: it no longer says owner funds are needed only once every wallet reports being at its floor, because a sealed wallet never reports that.",
+ "tags": [
+ "fix",
+ "infra"
+ ]
}
]
}
diff --git a/docs/ops/payment-outcomes.md b/docs/ops/payment-outcomes.md
index 1a4f5607a..842bc13e8 100644
--- a/docs/ops/payment-outcomes.md
+++ b/docs/ops/payment-outcomes.md
@@ -173,10 +173,24 @@ curl -s https://three.ws/api/x402/three-intel | jq '.accepts[].network'
sub-day runway is the answer. Read `runway_status` first, then run the free
self-heal (`POST /api/cron/treasury-topup?dry=1`, then without `?dry=1`)
before asking for funds: reclaimable SOL sitting in platform agent wallets is
- the usual answer, and every reclaim run now leaves `agent_reclaim` rows in
+ often the answer, and every reclaim run now leaves `agent_reclaim` rows in
`economy_master_ledger` saying whether it was `blocked` (an RPC or key
problem, free to fix) or found `nothing_reclaimable` (the only case that
genuinely needs the owner to send SOL).
+
+ **Read `agent_reclaim.failed` in the dry plan before you trust its total.**
+ The plan-only run opens each wallet's key exactly as the real run does, so a
+ wallet whose secret does not decrypt is listed there at stage `recover` with
+ reason `secret_undecryptable` instead of being counted as reclaimable. That
+ SOL is real, visible on chain, and unreachable: it is encrypted under a key
+ this deploy does not hold, and no cron run, RPC tier, or deposit moves it
+ (see [wallet-key-migration.md](wallet-key-migration.md) for the recovery
+ path, and put the retired key in `WALLET_ENCRYPTION_KEY_PREVIOUS` if you have
+ it). Until 2026-09-02 the dry run skipped that check and reported those
+ wallets as available on every tick, which sent two separate investigations
+ away with "the cron will self-heal from here" when it could not. A dry total
+ of 0 with a populated `failed` list means the same thing as
+ `nothing_reclaimable`: the owner has to send SOL.
4. `replay_stages_24h` nonzero: captured X-PAYMENT headers are being re-sent;
the guard is working if the settles panel is unaffected.
diff --git a/prompts/finish/backlog-PROGRESS.md b/prompts/finish/backlog-PROGRESS.md
index 36f4e7d86..42bfb4f80 100644
--- a/prompts/finish/backlog-PROGRESS.md
+++ b/prompts/finish/backlog-PROGRESS.md
@@ -702,3 +702,113 @@ Kept, with the measured reason:
`/discovery/resources` paging and `/supported` match what it registered. Verified shipped.
The file's content and this pack's index row sit behind the CLAUDE.md commit gate, so the
deletion waits for the owner's yes; nothing else remains.
+
+## 2026-09-02: 01 x402 settle runway (the phantom reclaim plan is fixed; capital is still the whole remaining story)
+
+Measured live at 05:19 UTC, prod `ad7b54c16` / revision `three-ws-api-00404-ph7`
+(107 commits behind `main`, so nothing below ships until the next deploy):
+
+| Fact | Value | Source |
+|---|---|---|
+| `x402_settle` | **degraded, 55.0%** (55/100 paid attempts, 3h), `cause: sponsor_floor` | `GET /api/healthz` |
+| Since-boot settle book | ok 1,709 / failed 50,575: `fee_runway_exhausted` 48,788, `fee_wallet_below_floor` 1,259, `not_confirmed` 371, `broadcast_failed` 20 | same, `x402.self_facilitator` |
+| Governed skips in window | 1,220 against 45 rail faults and 175 `no_solana_accept` | same, `x402_settle.metrics` |
+| Sponsor fee wallet `Wwwu…T3WwW` | 0.003727883 SOL, spendable 1,727,883 lamports over a 2,000,000 floor | `GET /api/x402/runway-lab` |
+| Ring payer `X4o2…stML` | 1,998,408 lamports, i.e. **1,592 lamports under the floor** | same, and the live refusal string `fee_wallet_below_floor:1998408<2000000` |
+| Live governor config | `runway_days: 1`, `min_budget_lamports: 10,000,000`, `governor_enabled: true`, intraday pacing ON | same, `config` |
+| Measured burn | `fee_total_lamports` 13,327,231 over 24h = **0.0133 SOL/day spent**; median fee 10,001 lamports | same, `observed` |
+| Demand | 177 attempts/hour = ~4,248/day, against `projected_settles_per_day` 172 | same |
+
+Three corrections to the work order, all measured:
+
+1. **Levers 1 and 2 are already applied in production.** `runway-lab` reports
+ `runway_days: 1` today, and the 2026-08-01 entry above records
+ `ECONOMY_MASTER_OPERATING_SOL=0.3` landing with it. Do not re-apply them, and
+ do not size anything from lever 2: at a 0.0037 SOL balance the 10,000,000
+ lamport heartbeat floor already exceeds spendable, so runway days are inert
+ (the 2026-08-02 entry struck this lever for the same reason).
+2. **The headline is no longer 25.9% or 5.9%.** Settle is 55.0% and the
+ subsystem is `degraded`, not `down`. `fee_runway_exhausted` still dominates
+ the since-boot book, but that book has never been reset; in the live 3h
+ window the split is 1,220 governor skips, 175 withdrawn Solana accepts, 45
+ rail faults. The fee-admission gate shipped 2026-08-01 is doing its job:
+ unfundable calls are refused in one step instead of after five RPC round
+ trips.
+3. **Demand has collapsed to 177/hour** from the 3,726/hour of 2026-08-02, so
+ the honest funding ask is now ~0.043 SOL/day to serve every attempt
+ (4,248 x 10,001 lamports), not the 0.45 SOL/day that entry quoted. 1 SOL is
+ roughly three weeks at current demand. The "1 to 2 SOL/day" figure the work
+ order warns about is still wrong, by more than the order of magnitude it says.
+
+Did (the one agent-doable item the 2026-09-01 sweep left open in code):
+
+- **`reclaimIdleAgentSol` no longer advertises SOL it cannot move.**
+ `api/_lib/economy-sweepback.js` returned the raw `planAgentReclaim` output in
+ dry-run mode without ever touching a wallet key, so the 8 custodial wallets
+ sealed under the WALLET_ENCRYPTION_KEY retired in the 2026-07 migration were
+ reported as reclaimable on every tick while the real leg failed all of them at
+ the recover stage. The recover-and-verify step is now a function both modes
+ call: the dry run opens each planned wallet's key (passing NO audit context, so
+ a plan-only read on the every-minute economy tick does not write a custody row
+ per wallet), drops the ones that do not decrypt into `failed` at stage
+ `recover`, and sums `reclaimedSol` from the survivors. `agent_reclaim.failed`
+ in the `?dry=1` response now carries them, so the existing blocked-vs-nothing
+ classification in `api/cron/treasury-topup.js` sees the same truth a real run
+ would.
+- **Recurrence guard, with a test.** `tests/economy-reclaim-dryrun-key-gate.test.js`
+ (7 cases) pins dry/real parity on which wallets are unreachable, that
+ `reclaimedSol` counts only openable wallets, that a fully sealed fleet plans
+ nothing at all, the address-mismatch case, and that the dry run signs nothing
+ and writes no custody row.
+- **The healthz hint that produced the loop is corrected.** The `sponsor_floor`
+ hint ended at "Owner SOL is needed only when every reclaim source reports
+ `at_or_below_floor`". A sealed wallet reports `secret_undecryptable` and never
+ `at_or_below_floor`, so that sentence read as "the cron will fix it" for a
+ condition no cron can fix, which is exactly what two earlier sessions
+ concluded. It now names `agent_reclaim.failed`, `secret_undecryptable` and
+ `WALLET_ENCRYPTION_KEY`, with a test in
+ `tests/api/x402-settle-health.test.js` that fails if the old promise returns.
+- Runbook step 3 in `docs/ops/payment-outcomes.md` updated to match, plus a
+ `data/changelog.json` entry (`fix`, `infra`) and `npm run build:pages`.
+
+Verification: `check:rules` clean on the 6 touched paths, `audit:docs` clean,
+`test:gate` and `test:gate-3d` green (559 + gate suites), targeted suites 96/96.
+`npm run gate` does NOT pass end to end in this worktree, and none of it is this
+change: `audit:mcp`, `audit:mcp-golden` and `audit:mcp-safety` fail on
+`packages/{herald,knock,metaplex-agent}-mcp`, `audit:routes` on
+`/events/build-3d-agents-live`, `audit:links` on `pages/tty.html`,
+`pages/knock-door.html`, `src/api.js`, `src/avatar-artifact.js`,
+`audit:inline-handlers` on `src/deploy-onchain.js`, `audit:x402-catalog` on
+`/api/x402/{knock,preflight}`, and `audit:tokens` on five pages. Every one of
+those is a concurrent agent's in-flight work; this diff touches none of those
+files.
+
+Left, and it is all capital, all owner-owned:
+
+1. **The settle rate cannot reach 90% from here.** Two wallets are starved and
+ both are tiny: the ring payer is **1,592 lamports** (0.0000016 SOL) under its
+ 2,000,000 floor, and the sponsor has 1,727,883 spendable lamports against a
+ 10,000,000/day heartbeat budget. Sustaining current demand needs ~0.043
+ SOL/day. Send SOL to the economy master
+ `WwwuGbqHrwF5RG89KhUbmRWEvjnRH9k5kVM5p7T3WwW` (never to per-agent wallets)
+ and treasury-topup distributes within minutes.
+2. **0.49 SOL stays stranded behind the retired key**, 0.35 of it customer money
+ in two user-owned agents that display a balance their owners cannot move. The
+ dry plan now says so out loud instead of counting it. If the retired key can
+ be produced, `WALLET_ENCRYPTION_KEY_PREVIOUS` recovers it with no migration
+ (`docs/ops/wallet-key-migration.md`); if it cannot, the two customers need a
+ decision, which is not an agent's to make.
+3. **`gcloud` auth is dead in this workspace** (`Reauthentication failed. cannot
+ prompt during non-interactive execution`), and `.env` carries no
+ `CRON_SECRET`, so neither the config levers nor `POST /api/cron/treasury-topup?dry=1`
+ could be exercised from here. One `gcloud auth login` restores both. Nothing
+ in this entry needed them: every number above came from public endpoints.
+4. **This work is behind the deploy gap.** The dry-run fix and the corrected hint
+ are on `main`, not in production; prod still runs `ad7b54c16` from 2026-08-28.
+ The next deploy carries them.
+
+Definition-of-done status: the recurrence guard, its test, the changelog entry and
+this log are done. The three outcome lines (settle above 90%, `fee_runway_exhausted`
+no longer top, a non-zero reclaim plan) cannot be closed by an agent: at a 0.0037
+SOL sponsor balance there is no non-zero *executable* reclaim plan to produce, and
+that is now the honest answer the endpoint gives rather than the phantom one.
diff --git a/public/changelog.json b/public/changelog.json
index ca67158da..cbeeb4709 100644
--- a/public/changelog.json
+++ b/public/changelog.json
@@ -1,11 +1,45 @@
{
- "generated_at": "2026-09-01T18:36:39.158Z",
+ "generated_at": "2026-09-02T05:22:10.363Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json",
"site": {
"name": "three.ws",
"url": "https://three.ws"
},
"entries": [
+ {
+ "date": "2026-09-02",
+ "type": "update",
+ "title": "Every showcased agent now has its own page",
+ "summary": "Agent Spotlight entries got somewhere to live. Each one now has its own page with the agent standing in 3D, the full write-up instead of three clamped lines, a facts panel read live off the agent (skills, conversations, on-chain actions, upvotes), share buttons, and a rail of related entries in the same category. Sharing one finally works too: paste a link anywhere and it unfurls with that entry's headline and the agent's own card rather than the generic showcase image. If you submitted an entry, you can now edit or remove it, which you could not do before: an Edit link on your card opens the write-up ready to change, and removing takes two clicks so it cannot happen by accident. Ranking got fairer as well, with a stable order for entries published at the same moment instead of a shuffle between page loads.",
+ "link": "/spotlight",
+ "tags": [
+ "improvement",
+ "feature"
+ ]
+ },
+ {
+ "date": "2026-09-02",
+ "type": "update",
+ "title": "Examples gains a voice, an AI's eye on 3D, and a filter",
+ "summary": "Three more runnable examples and a way to find them. The avatar can now speak a line you type: the free text-to-speech lane synthesizes it and a new speakAudio() method routes the audio through the same analyser the built-in voice uses, so the mouth follows the real waveform instead of miming. A second example calls the look_at_model tool on the public MCP server and shows exactly what an AI assistant sees when it inspects a mesh: four rendered angles plus a plain-language read on the geometry, which is how an agent judges its own output and decides to try again. A third reads the live tool list off that same server, so the page can never advertise a tool that was renamed or dropped. With seventeen examples the page also gets a filter: type to search names, descriptions and tags, or narrow by tag, and the lanes fold away as they empty. A deep link always wins over an active filter.",
+ "link": "/examples",
+ "tags": [
+ "feature",
+ "improvement",
+ "sdk"
+ ]
+ },
+ {
+ "date": "2026-09-02",
+ "type": "update",
+ "title": "The treasury's self-heal plan now only promises SOL it can actually move",
+ "summary": "When the payment rail runs short of the SOL it needs to settle, the platform first tries to heal itself: it looks across its own agent wallets for idle funds and pulls them back to the wallet that pays fees. The preview of that plan was counting wallets it could never open. Eight custodial wallets were encrypted under a key retired during the 2026-07 move to Google Cloud, so the preview kept advertising their balance as available while every real run failed on them, and the plan looked the same the next time anyone checked. The preview now opens each wallet's key before listing it, exactly as a real run does, and reports the ones it cannot open separately with the reason. A plan that reads as capital on hand when the capital is unreachable is worse than no plan at all, and it cost two separate investigations. The health check's settlement hint was corrected to match: it no longer says owner funds are needed only once every wallet reports being at its floor, because a sealed wallet never reports that.",
+ "link": null,
+ "tags": [
+ "fix",
+ "infra"
+ ]
+ },
{
"date": "2026-09-01",
"type": "launch",
diff --git a/public/changelog.xml b/public/changelog.xml
index c2421d7b0..2ab442df8 100644
--- a/public/changelog.xml
+++ b/public/changelog.xml
@@ -6,6 +6,30 @@
<atom:link href="https://three.ws/changelog.xml" rel="self" type="application/rss+xml"/>
<description>What's new on three.ws: features, improvements, and releases, newest first.</description>
<language>en</language>
+ <item>
+ <title>Every showcased agent now has its own page</title>
+ <link>https://three.ws/spotlight</link>
+ <guid isPermaLink="false">2026-09-02:Every showcased agent now has its own page</guid>
+ <pubDate>Wed, 02 Sep 2026 12:00:00 GMT</pubDate>
+ <category>improvement</category>
+ <description>Agent Spotlight entries got somewhere to live. Each one now has its own page with the agent standing in 3D, the full write-up instead of three clamped lines, a facts panel read live off the agent (skills, conversations, on-chain actions, upvotes), share buttons, and a rail of related entries in the same category. Sharing one finally works too: paste a link anywhere and it unfurls with that entry's headline and the agent's own card rather than the generic showcase image. If you submitted an entry, you can now edit or remove it, which you could not do before: an Edit link on your card opens the write-up ready to change, and removing takes two clicks so it cannot happen by accident. Ranking got fairer as well, with a stable order for entries published at the same moment instead of a shuffle between page loads.</description>
+ </item>
+ <item>
+ <title>Examples gains a voice, an AI's eye on 3D, and a filter</title>
+ <link>https://three.ws/examples</link>
+ <guid isPermaLink="false">2026-09-02:Examples gains a voice, an AI's eye on 3D, and a filter</guid>
+ <pubDate>Wed, 02 Sep 2026 12:00:00 GMT</pubDate>
+ <category>feature</category>
+ <description>Three more runnable examples and a way to find them. The avatar can now speak a line you type: the free text-to-speech lane synthesizes it and a new speakAudio() method routes the audio through the same analyser the built-in voice uses, so the mouth follows the real waveform instead of miming. A second example calls the look_at_model tool on the public MCP server and shows exactly what an AI assistant sees when it inspects a mesh: four rendered angles plus a plain-language read on the geometry, which is how an agent judges its own output and decides to try again. A third reads the live tool list off that same server, so the page can never advertise a tool that was renamed or dropped. With seventeen examples the page also gets a filter: type to search names, descriptions and tags, or narrow by tag, and the lanes fold away as they empty. A deep link always wins over an active filter.</description>
+ </item>
+ <item>
+ <title>The treasury's self-heal plan now only promises SOL it can actually move</title>
+ <link>https://three.ws/changelog</link>
+ <guid isPermaLink="false">2026-09-02:The treasury's self-heal plan now only promises SOL it can actually move</guid>
+ <pubDate>Wed, 02 Sep 2026 12:00:00 GMT</pubDate>
+ <category>fix</category>
+ <description>When the payment rail runs short of the SOL it needs to settle, the platform first tries to heal itself: it looks across its own agent wallets for idle funds and pulls them back to the wallet that pays fees. The preview of that plan was counting wallets it could never open. Eight custodial wallets were encrypted under a key retired during the 2026-07 move to Google Cloud, so the preview kept advertising their balance as available while every real run failed on them, and the plan looked the same the next time anyone checked. The preview now opens each wallet's key before listing it, exactly as a real run does, and reports the ones it cannot open separately with the reason. A plan that reads as capital on hand when the capital is unreachable is worse than no plan at all, and it cost two separate investigations. The health check's settlement hint was corrected to match: it no longer says owner funds are needed only once every wallet reports being at its floor, because a sealed wallet never reports that.</description>
+ </item>
<item>
<title>3D Drops</title>
<link>https://three.ws/drops</link>
diff --git a/tests/api/x402-settle-health.test.js b/tests/api/x402-settle-health.test.js
index c540264e3..5ecee1209 100644
--- a/tests/api/x402-settle-health.test.js
+++ b/tests/api/x402-settle-health.test.js
@@ -160,6 +160,27 @@ describe('classifySettleBuckets — verdict from real bucket shapes', () => {
expect(v.hint).not.toMatch(/Payments are being rejected at settle/);
});
+ it('the sponsor-floor hint refuses to promise a self-heal that sealed wallets cannot deliver', () => {
+ // The hint used to end at "Owner SOL is needed only when every reclaim
+ // source reports at_or_below_floor". On this platform most of the
+ // reclaimable SOL sits in wallets encrypted under a key retired in the
+ // 2026-07 host migration: they report `secret_undecryptable`, never
+ // `at_or_below_floor`, so that sentence read as "the cron will fix it" for
+ // a condition no cron can fix. Two sessions lost time to it.
+ const v = classifySettleBuckets([
+ { success: true, paid: true, reason: 'none', n: 40 },
+ { success: false, paid: false, reason: 'http_502', n: 60 },
+ { success: false, paid: false, reason: 'fee_wallet_below_floor', n: 1 },
+ ]);
+ expect(v.cause).toBe('sponsor_floor');
+ expect(v.hint).toMatch(/secret_undecryptable/);
+ expect(v.hint).toMatch(/agent_reclaim\.failed/);
+ expect(v.hint).toMatch(/WALLET_ENCRYPTION_KEY/);
+ // "only when ... at_or_below_floor" was the exact false promise. It must
+ // not come back.
+ expect(v.hint).not.toMatch(/only when every reclaim source reports at_or_below_floor\./);
+ });
+
it('still blames the rail when faults rose and Solana is payable', () => {
const v = classifySettleBuckets(liveOutageBuckets);
expect(v.cause).toBe('rail');
diff --git a/tests/economy-reclaim-dryrun-key-gate.test.js b/tests/economy-reclaim-dryrun-key-gate.test.js
new file mode 100644
index 000000000..b446a7f25
--- /dev/null
+++ b/tests/economy-reclaim-dryrun-key-gate.test.js
@@ -0,0 +1,166 @@
+// The agent-reclaim leg's plan-only mode (reclaimIdleAgentSol in
+// api/_lib/economy-sweepback.js).
+//
+// `POST /api/cron/treasury-topup?dry=1` is the one command every triage path
+// points at to decide whether the treasury can self-heal or whether the owner
+// has to move SOL. It used to answer from planAgentReclaim() alone, without ever
+// touching a wallet key, so the 8 custodial wallets sealed under the retired
+// WALLET_ENCRYPTION_KEY (0.49 SOL, of which 0.35 is customer money) were
+// advertised as reclaimable on every run. The real leg then failed all of them
+// at the recover stage, and the next reader saw the same plan again.
+//
+// Two sessions on 2026-08-01 read that plan and concluded "the */30 cron
+// self-heals from here". It could not. So the property under test is that the
+// dry run reports only SOL that a real run could actually move: a wallet whose
+// secret does not decrypt is `failed` at stage `recover`, never a `move`, and
+// never counted in `reclaimedSol`.
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { Keypair } from '@solana/web3.js';
+
+const { OPEN, SEALED, IMPOSTOR } = vi.hoisted(() => ({
+ OPEN: 'open-secret',
+ SEALED: 'sealed-secret',
+ IMPOSTOR: 'impostor-secret',
+}));
+
+const rows = vi.hoisted(() => ({ current: [] }));
+const sendSol = vi.hoisted(() => vi.fn(async () => 'live-signature'));
+const recordEvent = vi.hoisted(() => vi.fn());
+
+// The keypair each secret opens to. `sealed` throws the exact WebCrypto error a
+// record encrypted under a retired key produces; `impostor` decrypts fine but
+// yields a different pubkey than the row claims.
+const KEYS = vi.hoisted(() => ({ current: new Map() }));
+
+vi.mock('../api/_lib/db.js', () => ({ sql: async () => rows.current }));
+vi.mock('../api/_lib/avatar-wallet.js', () => ({
+ sendSol: (...args) => sendSol(...args),
+ LAMPORTS_PER_SOL: 1_000_000_000,
+}));
+vi.mock('../api/_lib/solana-signers.js', () => ({ SOLANA_SIGNERS: [], loadSignerKeypair: async () => ({ configured: false }) }));
+vi.mock('../api/_lib/execution-engine.js', () => ({ submitProtected: async () => ({ signature: 'x' }) }));
+vi.mock('../api/_lib/agent-wallet.js', () => ({
+ recoverSolanaAgentKeypair: async (secret, audit) => {
+ if (secret === SEALED) throw new Error('The operation failed for an operation-specific reason.');
+ const kp = KEYS.current.get(secret);
+ if (!kp) throw new Error(`no key for ${secret}`);
+ // The real implementation audits only AFTER the decrypt succeeds.
+ if (audit?.agentId) recordEvent(audit);
+ return kp;
+ },
+}));
+
+const { reclaimIdleAgentSol, PLATFORM_AGENT_OWNER_EMAIL } = await import('../api/_lib/economy-sweepback.js');
+
+const openKp = Keypair.generate();
+const impostorKp = Keypair.generate();
+// A real base58 pubkey: the sealed wallet is on chain and readable, it is only
+// its stored secret that no key in the fleet opens.
+const SEALED_ADDRESS = Keypair.generate().publicKey.toBase58();
+
+// Balances are well clear of every floor so the ONLY thing that can remove a
+// wallet from the plan is the key gate this test is about.
+function agentRow(id, name, address, secret, sol) {
+ return {
+ agent_id: id,
+ name,
+ address,
+ secret,
+ owner: PLATFORM_AGENT_OWNER_EMAIL,
+ strategy_enabled: false,
+ per_trade_lamports: null,
+ auto_fund_enabled: false,
+ open_positions: 0,
+ __sol: sol,
+ };
+}
+
+function connectionFor(list) {
+ const byAddress = new Map(list.map((r) => [r.address, r.__sol]));
+ return { getBalance: async (pk) => Math.round((byAddress.get(pk.toBase58()) ?? 0) * 1_000_000_000) };
+}
+
+beforeEach(() => {
+ sendSol.mockClear();
+ recordEvent.mockClear();
+ KEYS.current = new Map([
+ [OPEN, openKp],
+ [IMPOSTOR, impostorKp],
+ ]);
+ rows.current = [
+ agentRow('ag-open', 'bot-open', openKp.publicKey.toBase58(), OPEN, 0.5),
+ agentRow('ag-sealed', 'bot-sealed', SEALED_ADDRESS, SEALED, 0.4),
+ ];
+});
+
+describe('agent reclaim dry run: the plan is only what a real run could move', () => {
+ it('does not count a wallet whose secret cannot be decrypted', async () => {
+ const res = await reclaimIdleAgentSol({ connection: connectionFor(rows.current), dryRun: true });
+
+ expect(res.moves.map((m) => m.name)).toEqual(['bot-open']);
+ expect(res.moves.every((m) => m.dryRun === true)).toBe(true);
+ const sealed = res.failed.find((f) => f.name === 'bot-sealed');
+ expect(sealed?.stage).toBe('recover');
+ expect(sealed?.reason).toMatch(/^secret_undecryptable/);
+ });
+
+ it('reports reclaimedSol as the reachable SOL, not the planned SOL', async () => {
+ const res = await reclaimIdleAgentSol({ connection: connectionFor(rows.current), dryRun: true });
+ // The sealed wallet's SOL is real and visible on chain, and it is still
+ // unreachable. Summing the plan instead of the openable wallets is what made
+ // two operators believe the treasury had capital it could not spend.
+ const unreachable = res.failed.reduce((s, f) => s + f.sol, 0);
+ expect(unreachable).toBeGreaterThan(0);
+ expect(res.reclaimedSol).toBe(res.moves.reduce((s, m) => s + m.sol, 0));
+ expect(res.reclaimedSol).toBe(res.moves[0].sol);
+ });
+
+ it('a fleet where every wallet is sealed plans nothing at all', async () => {
+ rows.current = [agentRow('ag-sealed', 'bot-sealed', SEALED_ADDRESS, SEALED, 0.9)];
+ const res = await reclaimIdleAgentSol({ connection: connectionFor(rows.current), dryRun: true });
+
+ // This is the shape that must reach the owner as "fund the sponsor", not as
+ // "the cron will handle it".
+ expect(res.moves).toEqual([]);
+ expect(res.reclaimedSol).toBe(0);
+ expect(res.failed).toHaveLength(1);
+ });
+
+ it('drops a wallet whose key opens to a different address', async () => {
+ rows.current = [agentRow('ag-imp', 'bot-impostor', openKp.publicKey.toBase58(), IMPOSTOR, 0.6)];
+ const res = await reclaimIdleAgentSol({ connection: connectionFor(rows.current), dryRun: true });
+
+ expect(res.moves).toEqual([]);
+ expect(res.failed[0]).toMatchObject({ stage: 'recover', reason: 'keypair_address_mismatch' });
+ });
+
+ it('signs and broadcasts nothing, and writes no custody row', async () => {
+ await reclaimIdleAgentSol({ connection: connectionFor(rows.current), dryRun: true });
+
+ expect(sendSol).not.toHaveBeenCalled();
+ // The real leg's decrypt is a custody event worth a row. A plan-only read
+ // runs on the every-minute economy tick, so auditing it would bury the
+ // genuine key uses under thousands of inspections.
+ expect(recordEvent).not.toHaveBeenCalled();
+ });
+
+ it('the real run still audits its decrypts and moves the openable wallet', async () => {
+ const res = await reclaimIdleAgentSol({ connection: connectionFor(rows.current), dryRun: false });
+
+ expect(res.moves.map((m) => m.name)).toEqual(['bot-open']);
+ expect(res.moves[0].signature).toBe('live-signature');
+ expect(sendSol).toHaveBeenCalledTimes(1);
+ expect(recordEvent).toHaveBeenCalledTimes(1);
+ expect(recordEvent.mock.calls[0][0]).toMatchObject({ agentId: 'ag-open', reason: 'economy_reclaim' });
+ });
+
+ it('dry and real runs agree on which wallets are unreachable', async () => {
+ const dry = await reclaimIdleAgentSol({ connection: connectionFor(rows.current), dryRun: true });
+ const real = await reclaimIdleAgentSol({ connection: connectionFor(rows.current), dryRun: false });
+
+ // The parity that makes ?dry=1 worth reading at all.
+ expect(dry.moves.map((m) => m.address)).toEqual(real.moves.map((m) => m.address));
+ expect(dry.failed.map((f) => [f.name, f.stage])).toEqual(real.failed.map((f) => [f.name, f.stage]));
+ expect(dry.reclaimedSol).toBe(real.reclaimedSol);
+ });
+});