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(finish): add orders 405 and 406 for a live outage and a dependency drift

nirholas30db9563a43f
diff --git a/prompts/finish/405-auto-bonding-curve-no-fallback-outage.md b/prompts/finish/405-auto-bonding-curve-no-fallback-outage.md
new file mode 100644
index 000000000..95415a130
--- /dev/null
+++ b/prompts/finish/405-auto-bonding-curve-no-fallback-outage.md
@@ -0,0 +1,88 @@
+# 405. `/api/crypto/bonding` is in total outage: port the already-proven last-known-good cache into `pump-bonding.js`
+
+How to run: paste this file's repo path into a fresh Claude Code chat in this repository and say "run this work order." Runnable now, no gate. Written by the evolve scout lane on 2026-10-23 from a live measurement against production.
+
+## Operating clause (binding)
+
+- Read CLAUDE.md first. CLAUDE.md overrides everything, including this file.
+- Finish 100% in this session. Never end the turn with a question, an option list, or an unexecuted plan. A judgment call goes in one line of the final report; it never becomes a question that halts work.
+- The only permitted stops are the CLAUDE.md stop-and-ask gates: spending real funds or any irreversible on-chain write, git push or a production deploy, posting to an external channel, committing content that names a crypto project other than $THREE, and destroying unrecoverable data. This order touches none of them: it edits one library file, ports an existing pattern already shipped elsewhere in this repo, and adds tests.
+- No mocks, no fake data, no unfinished-work markers, no commented-out code. Every claim gets verified against the live endpoint, not assumed from the code.
+- Bug fixes are test-first (CLAUDE.md): write a test that reproduces the gap (upstream failure with no cache returns a hard error with no fallback), confirm it fails for that reason, then fix, then confirm it passes. Commit the test with the fix.
+- The em-dash and en-dash characters are banned in everything you write.
+- Concurrent agents share this worktree: stage explicit paths only (never `git add -A` or `git add .`), re-check `git status` and `git diff --staged` before committing.
+- Before committing, run `npm run check:rules -- --paths <files you touched>`. It must exit 0.
+
+## Why this matters (measured 2026-10-23, production, `main` at `9b32c1ea3`)
+
+`GET https://three.ws/api/crypto/bonding?mint=<any mint>` is in **complete, sustained outage**. Three consecutive live calls against a real mint (`$THREE`'s own CA) each returned `503`:
+
+```
+$ curl -s -o /dev/null -w "%{http_code}\n" "https://three.ws/api/crypto/bonding?mint=FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump"
+503
+503
+503
+```
+
+This is a free, keyless, Solana-native endpoint (CLAUDE.md: Solana first) that any agent or frontend surface can call to check a pump.fun bonding-curve's progress and migration status. It currently fails for every caller, every time.
+
+**Root cause, read end to end:**
+
+1. `api/crypto/bonding.js` (handler) calls `getBondingStatus(mint)` from `api/_lib/pump-bonding.js`. On `result.kind === 'upstream_down'` it returns a hard `503 upstream_unavailable` with `retry_after: 15` and no fallback of any kind.
+2. `api/_lib/pump-bonding.js`'s `fetchOnce(url)` makes exactly one raw `fetch()` with a 6000ms timeout and **no retry**. Any non-OK response, including pump.fun's Cloudflare anti-bot challenge, becomes `{kind:'upstream_down'}` immediately.
+3. `fetchPumpCoin(mint)` tries `coins-v2/<mint>` then `coins/<mint>` against `PUMP_FRONTEND_BASE` (`https://frontend-api-v3.pump.fun`), both direct fetches with **no caching whatsoever**, so there is nothing to fall back to even when a prior successful fetch exists.
+4. pump.fun's upstream is confirmed, independent of this bug, to intermittently serve a Cloudflare "Just a moment..." challenge (HTTP 403) or a rate limit (429/1015) regardless of request shape. This is a known, already-solved failure class elsewhere in this exact codebase:
+ - `api/_lib/pump-feed-fetch.js` exports `pumpFetchJson(url, {timeoutMs, retries})`, a bounded retry that honors `Retry-After` on 429/5xx and never throws, plus a shared `readThroughFeed({key, ttlSeconds, lkgKey, lkgTtlSeconds, fetchRows})` helper: live cache first, then a much longer last-known-good (LKG) cache, served stale with an `x-pump-stale: 1` header rather than hard-failing.
+ - `api/pump/[action].js`'s `handleCoin()` (the sibling `/api/pump/coin` endpoint, which fetches the exact same pump.fun coin object this order's endpoint needs) already ships this: an in-memory `COIN_CACHE` (30s TTL), a 24-hour Redis-backed LKG keyed `pump:coin:lkg:<mint>`, and `serveStaleCoin(res, mint, status, code, message)` which serves the LKG copy with `x-pump-stale: 1` on live failure, only returning a real `Retry-After: 15` error when there is no LKG at all.
+
+`pump-bonding.js` is the one module in this family that never got this treatment. The fix is mechanical: port the proven pattern, not invent a new one.
+
+## Step 0: re-derive the current state
+
+```bash
+git log --oneline -1
+for i in 1 2 3; do curl -s -o /dev/null -w "%{http_code}\n" "https://three.ws/api/crypto/bonding?mint=FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump"; done
+curl -s "https://three.ws/api/crypto/bonding?mint=FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump" | head -c 500; echo
+cat api/_lib/pump-bonding.js
+sed -n '1,220p' api/_lib/pump-feed-fetch.js
+grep -n "COIN_CACHE\|COIN_LKG_TTL_S\|coinLkgKey\|serveStaleCoin\|function handleCoin" api/pump/\[action\].js
+```
+
+If the endpoint already returns `200` reliably across 10 consecutive calls, another agent or a pump.fun-side recovery already fixed the symptom; still read `pump-bonding.js` and confirm it has a real cache/LKG path (not just a transient upstream recovery that will regress), add the missing resilience if it is still absent, and report that the live symptom had already cleared.
+
+## Tasks
+
+1. **Add caching to `api/_lib/pump-bonding.js`.** Import `cacheGet`/`cacheSet` from `api/_lib/cache.js` (the same module `api/pump/[action].js` uses). Add a short live-cache TTL (follow the sibling convention, e.g. 20-30s) keyed per mint, e.g. `pump:bonding:live:<mint>`, and a long LKG TTL (follow the sibling convention, e.g. 1800-3600s) keyed `pump:bonding:lkg:<mint>`.
+2. **Replace the single-shot `fetchOnce` with a retrying fetch.** Either import and reuse `pumpFetchJson` from `api/_lib/pump-feed-fetch.js` directly (preferred: one fewer retry implementation to maintain), or if `fetchPumpCoin`'s two-URL-shape fallback (`coins-v2` then `coins`) doesn't fit `pumpFetchJson`'s single-URL signature cleanly, wrap each of the two attempts in `pumpFetchJson` calls. Either way, upstream failures must now retry with backoff honoring `Retry-After` before being treated as down, matching the sibling modules' behavior.
+3. **Wire the LKG fallback into `getBondingStatus(mint)`.** On successful fetch: write through to both the live cache and the LKG cache. On fetch failure: check the live cache first (serve if fresh), then the LKG cache (serve if present, flagging staleness), and only return `{kind:'upstream_down'}` when neither exists, mirroring `readThroughFeed`'s three-way contract (fresh / stale-but-present / truly nothing).
+4. **Surface staleness in the handler.** In `api/crypto/bonding.js`, when `getBondingStatus` returns a stale/LKG result, set the `x-pump-stale: 1` response header (matching the sibling endpoint's convention) and return `200` with the stale data rather than `503`, so callers get a usable answer instead of a hard failure whenever any successful fetch has ever happened for that mint. Only return `503 upstream_unavailable` with `retry_after: 15` when there is truly no cached data of any kind (e.g. a mint queried for the first time during an upstream outage).
+5. **Tests.** Add or extend a test file beside the existing pump-bonding tests (check for `tests/pump-bonding*.test.js`; create one at that path if it does not exist) covering: (a) a reproduction of today's bug: upstream fetch fails and there is no LKG, asserting the current `{kind:'upstream_down'}` / `503` behavior is what happens when there is truly nothing cached (this is the correct behavior for that case, so this test documents the contract rather than proving a regression, but write it test-first by confirming it against the pre-fix code path for the *stale-fallback* case below, which does fail pre-fix); (b) the actual bug reproduction: seed the LKG cache with a prior successful result, force the live fetch to fail, assert the fix now returns the LKG data with staleness indicated instead of a `503` (this must fail against the current code since no LKG path exists at all, then pass after the fix); (c) a successful fetch writes through to both caches.
+6. **Re-verify against production behavior.** You cannot deploy from this session (CLAUDE.md gate), so verify locally: run the handler against a mocked/forced-failing upstream in the test suite (already covered by task 5) and confirm `npm run test:core -- pump-bonding` (or the exact path of the new/extended test file) passes.
+
+## Definition of done
+
+- [ ] `api/_lib/pump-bonding.js` imports `cacheGet`/`cacheSet` from `api/_lib/cache.js` and uses a retrying fetch (`pumpFetchJson` or equivalent bounded-retry wrapper), not a single raw `fetch()`.
+- [ ] `getBondingStatus(mint)` returns cached/LKG data with a staleness flag when the live fetch fails and prior data exists; only returns `upstream_down` when no cached data exists at all for that mint.
+- [ ] `api/crypto/bonding.js` sets `x-pump-stale: 1` and returns `200` on a stale-but-present result; only returns `503` when there is truly nothing cached.
+- [ ] A new or extended test file reproduces the bug (fails before the fix, for the stated reason: no LKG fallback path exists) and passes after the fix.
+- [ ] `npx vitest run <the exact test file path>` exits 0.
+- [ ] `npm run test:core` shows no new failures introduced by this change versus the Step 0 baseline (the suite may already be red for unrelated reasons tracked in order 401; compare only files this order touches).
+- [ ] `npm run check:rules -- --paths api/_lib/pump-bonding.js api/crypto/bonding.js <the test file path>` exits 0.
+- [ ] Committed as one topical commit (code + test together, per the bug-fix-is-test-first rule), with an honest message naming the fix.
+- [ ] `git status --short` shows nothing left uncommitted from this order.
+
+## Never blocked
+
+| Blocker | Resolution (act, do not ask) |
+|---|---|
+| pump.fun's upstream happens to be healthy while you work, so you cannot observe a live `503` | The bug is in the code path (no cache exists at all), not a transient upstream state; write the test with a forced-failing fetch mock as task 5 describes, you do not need a live outage to prove the gap. |
+| `api/_lib/cache.js`'s `cacheGet`/`cacheSet` require Redis credentials not present locally | Check `.env.local` first (used throughout this order's own research); if genuinely absent, the `self-unblock-playbook` skill's credential row covers it. The cache module may also have an in-memory fallback mode, check its own source before assuming a hard block. |
+| `pumpFetchJson`'s signature doesn't fit `fetchPumpCoin`'s two-URL-shape retry cleanly | Wrap each of the two attempts (`coins-v2` then `coins`) in its own `pumpFetchJson` call rather than forcing a shared signature; correctness matters more than code reuse purity here. |
+| `npm run test:core` is red for unrelated reasons (tracked in orders 401/406) | Compare only the files this order touches; do not attempt to fix unrelated red tests here. |
+
+## Report format
+
+1. Before/after: the three live `curl` status codes from Step 0, and (if you can reproduce an upstream failure locally) the handler's response before and after the fix.
+2. The diff to `pump-bonding.js` and `crypto/bonding.js`, inline or by commit SHA.
+3. The new/extended test file's path and its pass/fail transition (fails before fix with the stated reason, passes after).
+4. Anything parked (e.g. a cache-infra limitation discovered mid-task).
diff --git a/prompts/finish/406-auto-sync-node-modules-x402-svm.md b/prompts/finish/406-auto-sync-node-modules-x402-svm.md
new file mode 100644
index 000000000..8f1d89b40
--- /dev/null
+++ b/prompts/finish/406-auto-sync-node-modules-x402-svm.md
@@ -0,0 +1,105 @@
+# 406. `node_modules` is stale against `package.json`: `@x402/svm` is pinned at 2.14.0 while 2.28.0 is required, failing at least 17 test files
+
+How to run: paste this file's repo path into a fresh Claude Code chat in this repository and say "run this work order." Runnable now, no gate. Written by the evolve scout lane on 2026-10-23 from a live measurement of this worktree.
+
+## Operating clause (binding)
+
+- Read CLAUDE.md first. CLAUDE.md overrides everything, including this file.
+- Finish 100% in this session. Never end the turn with a question, an option list, or an unexecuted plan. A judgment call goes in one line of the final report; it never becomes a question that halts work.
+- The only permitted stops are the CLAUDE.md stop-and-ask gates: spending real funds or any irreversible on-chain write, git push or a production deploy, posting to an external channel, committing content that names a crypto project other than $THREE, and destroying unrecoverable data. This order touches none of them: it is a local dependency install and a handful of test files; nothing here reaches production (production's Cloud Run container is built fresh from its own build pipeline, not from this worktree's `node_modules`).
+- No mocks, no fake data, no unfinished-work markers, no commented-out code, no silently loosening a test's assertions to make it pass. Every claim gets verified by re-running the real test suite, not assumed from the code.
+- This is a dependency-install task, not a single code bug, so the test-first bug-fix rule does not apply verbatim; instead, the Definition of Done requires a real before/after `npm run test:core` comparison as the proof.
+- The em-dash and en-dash characters are banned in everything you write.
+- Concurrent agents share this worktree: stage explicit paths only (never `git add -A` or `git add .`), re-check `git status` and `git diff --staged` before committing. This order touches `node_modules`, which is gitignored and never staged; only `package-lock.json` (if it changes meaningfully) and any test files you touch get committed.
+- Before committing, run `npm run check:rules -- --paths <files you touched>`. It must exit 0.
+- This order sits inside the scope of the existing broad order `prompts/finish/401-auto-restore-green-vitest.md` (restore a fully green `npm run test:core`). It is written separately because it is a single, narrow, mechanical root cause confirmed to account for a specific named slice of that order's failures, the same way order 403 carved the `history not on node` class out of the broader `agent_index` problem. Running this order first should shrink 401's remaining scope; it does not replace 401.
+
+## Why this matters (measured 2026-10-23, this worktree, `main` at `9b32c1ea3`)
+
+```
+$ npm run test:core
+ Test Files 178 failed | 2300 passed | 10 skipped (2488)
+ Tests 398 failed | 34866 passed | 429 skipped (35693)
+```
+
+Order 401 was written on 2026-10-08 against a baseline of 37 failed files / 74 failed tests. The suite has regressed roughly 5x in file-failure count since then. A single, specific, mechanical root cause is confirmed to account for at least 17 of the 178 failing files:
+
+```
+$ node -e "console.log(require('./node_modules/@x402/svm/package.json').version)"
+2.14.0
+$ grep -n '"@x402/svm"' package.json
+673: "@x402/svm": "^2.28.0",
+```
+
+`package.json` has required `@x402/svm@^2.28.0` since the dependency-bump commit that raised it (the version appears in the committed `package.json`), but the version physically installed in this worktree's `node_modules` is still `2.14.0`. Reading `node_modules/@x402/svm/package.json`'s `exports` map at the installed version shows only `.`, `./v1`, `./exact/client`, `./exact/server`, `./exact/facilitator`, `./exact/v1/client`, `./exact/v1/facilitator`, with **no `./upto/*` subpaths at all**. Multiple test files and library modules import an `./upto/...` subpath that exists in 2.28.0's public API but not in 2.14.0's, so every one of them throws at import time with an `exports`-resolution error (Node's `ERR_PACKAGE_PATH_NOT_EXPORTED`, surfaced as "is not exported under the conditions..."). At least these 17 files fail for exactly this reason (confirmed by grepping the test run's own output for that error signature immediately preceding each failure):
+
+```
+tests/agent-wallet-bridge-accept.test.js
+tests/api/all-modules-load.test.js
+tests/api/mcp-3d-challenge.test.js
+tests/api/pump.test.js
+tests/api/x402-discovery-parity.test.js
+tests/api/x402-facilitator-log-durable.test.js
+tests/api/x402-multi-asset-select.test.js
+tests/api/x402-paid-endpoint-siwx.test.js
+tests/api/x402-pay-feed-degraded.test.js
+tests/api/x402-pay-routing.test.js
+tests/api/x402-pipeline-stages.test.js
+tests/api/x402-pump-agent-audit-list.test.js
+tests/api/x402-security-fixes.test.js
+tests/api/x402-spec.test.js
+tests/x402-floor-degradation.test.js
+tests/x402-settlement-pending-resource.test.js
+tests/x402-upto.test.js
+```
+
+`tests/api/all-modules-load.test.js` loads every handler in `api/` to catch exactly this class of import-time break; its failure here is itself evidence that any production handler importing the missing subpath would fail the same way at cold start, which is why this is more than a test-suite nuisance. This is a classic "the lockfile/dependency bump landed in git but `node_modules` was never actually reinstalled" drift, the same class of bug the "Env-var trap" and "known traps" sections of CLAUDE.md warn about for other subsystems. The root `package-lock.json` in this worktree is also suspect: it is a 592-byte stub containing only 2 package entries and `"name": "shadow"`, nothing resembling this monorepo's real 200+-entry dependency graph, so `npm ci` against it would not help; a plain `npm install` that lets npm resolve and write a correct lockfile from `package.json` is the right tool here, not `npm ci`.
+
+## Step 0: re-derive the current state
+
+```bash
+git log --oneline -1
+node -e "console.log(require('./node_modules/@x402/svm/package.json').version)"
+grep -n '"@x402/svm"' package.json
+ls -la package-lock.json && node -e "const p=require('./package-lock.json'); console.log(p.name, p.version, Object.keys(p.packages||{}).length)"
+npm run test:core 2>&1 | tail -10
+```
+
+If `@x402/svm`'s installed version already satisfies `^2.28.0`, another agent already fixed this; instead verify none of the 17 listed files still fail for the `is not exported under the conditions` reason, and if they are all clear, skip straight to Definition of Done and report the pre-existing fix. If the installed version or the failing-file list differs from what is recorded above, trust what you measure now.
+
+## Tasks
+
+1. **Install the correct dependency tree.** Run `npm install` at the repo root (not `npm ci`, since the committed lockfile is the unrelated 592-byte stub described above; `npm install` will resolve from `package.json` and rewrite the lockfile correctly). Confirm afterward: `node -e "console.log(require('./node_modules/@x402/svm/package.json').version)"` now prints a version satisfying `^2.28.0`.
+2. **Check what else moved.** `npm install` may update other packages too (this worktree's `node_modules` could be behind on more than just `@x402/svm`). Run `git diff --stat package-lock.json` (or `package.json` if npm rewrites anything there, which it should not for a plain install) to see the blast radius. This is expected and fine: the goal is a `node_modules` that actually matches the committed `package.json`, not a single-package patch.
+3. **Re-run the full suite.** `npm run test:core`. Compare the new failed-file/failed-test counts against today's 178/398 baseline above. Confirm specifically that all 17 files listed above now pass (or fail for a genuinely different, unrelated reason, if so note which and why, do not force them green by weakening assertions).
+4. **Investigate any newly-surfaced failures.** If `npm install` upgrades a transitive dependency and that breaks something that was passing before (a real version-incompatibility, not an environment artifact), that is new information this order did not anticipate: fix it if it is small and mechanical (an API rename, a changed default), or if it is a substantial new problem, leave it and describe it precisely in the report rather than silently reverting the install (reverting would just restore today's 178-failure baseline).
+5. **Decide the lockfile's fate.** If `npm install` produces a large, real `package-lock.json` (hundreds of entries) replacing the 592-byte stub, that is very likely the correct, intended lockfile this repo should have, so commit it. If something about the stub turns out to be deliberate (check `.gitignore`, check `git log -- package-lock.json` for why it was reduced to a stub, check `scripts/setup-git-hooks.mjs` and any postinstall scripts for a reason this repo intentionally avoids a full root lockfile, e.g. if each sub-package under `packages/` or a worker directory manages its own install independently), report what you found either way and make the call; do not leave `node_modules` fixed but the lockfile mismatched with it.
+
+## Definition of done
+
+- [ ] `node -e "console.log(require('./node_modules/@x402/svm/package.json').version)"` prints a version satisfying `^2.28.0`.
+- [ ] All 17 files listed in "Why this matters" pass, or any that still fail do so for a documented, unrelated reason (quoted in the report).
+- [ ] `npm run test:core`'s failed-file and failed-test counts are reported before and after, and after is materially lower than 178/398.
+- [ ] No test that passed in the Step 0 baseline is now failing, unless explicitly documented in the report as a genuine, newly-surfaced version incompatibility (not silently papered over).
+- [ ] A decision on `package-lock.json` is made and acted on (committed as the real lockfile, or left as-is with a documented reason), not left in an inconsistent state relative to the installed `node_modules`.
+- [ ] `npm run check:rules -- --paths package-lock.json` (if changed) exits 0.
+- [ ] Committed with explicit paths (`package-lock.json` if it changed; nothing under `node_modules`, which stays gitignored) and an honest message naming the version bump and the failure-count delta.
+- [ ] `git status --short` shows nothing left uncommitted from this order.
+
+## Never blocked
+
+| Blocker | Resolution (act, do not ask) |
+|---|---|
+| `npm install` wants to touch thousands of files and takes a long time | Expected for a drifted `node_modules`; let it finish, it is a local, reversible operation (nothing is deployed or pushed). Use a background shell if it risks the foreground timeout. |
+| `npm install` fails outright (network, registry auth, disk) | Check disk first (`df -h .`, confirmed 295G free as of this writing, so unlikely); if a specific package genuinely cannot resolve (private registry, yanked version), isolate it, report the exact package and error, and install everything else so the bulk of the fix still lands. |
+| `npm install` surfaces a real, non-trivial breaking change in some other dependency | Do not revert the whole install to dodge it; fix the small ones, document the non-trivial one precisely (package, old vs new behavior, which test exposed it) in the report, and leave a note in `ISSUES.md` only if it is a genuinely new owner-relevant tracked issue, not a routine version bump. |
+| The 17-file list has already shrunk or grown by the time you run this (other agents committing concurrently) | Trust your own fresh Step 0 measurement over the number written here; the point is the root cause and the fix, not the exact count. |
+| `npm run test:core` is still red by a wide margin after this fix for unrelated reasons | Expected; order 401 covers the rest. Report your delta honestly rather than claiming full-suite green. |
+
+## Report format
+
+1. Before/after `npm run test:core` summary line, verbatim, both runs.
+2. The `@x402/svm` version before and after.
+3. Confirmation (pass/fail) for each of the 17 named files.
+4. The lockfile decision and why.
+5. Anything parked (a real breaking change found and not fixed, with package name and reason).