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.

chore(prompts): retire order 426, walk-sdk GLB load coalescing shipped

nirholas4924b79a9b6b
diff --git a/prompts/finish/426-auto-walk-companion-unhandled-fetch-rejection.md b/prompts/finish/426-auto-walk-companion-unhandled-fetch-rejection.md
deleted file mode 100644
index 66fd5b0e7..000000000
--- a/prompts/finish/426-auto-walk-companion-unhandled-fetch-rejection.md
+++ /dev/null
@@ -1,76 +0,0 @@
-# 426. Find and fix the unhandled "Failed to fetch" rejection firing from the three-addons chunk site-wide
-
-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, no owner action required.
-
-## 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.
-- This order's root cause is narrowed but not pinned to an exact line yet (see "What is already ruled out" below). That is not a reason to stop: Step 0 gives a fast, mechanical way to pin it exactly (enable sourcemaps, resolve the stack trace). Finish the investigation, then fix, in this same session.
-- Bug fixes are test-first: reproduce with a failing test before touching the fix, confirm it fails for the stated reason, then fix, then confirm green. Commit the test with the fix.
-- The only permitted stops are the CLAUDE.md stop-and-ask gates (spend/on-chain writes, push/deploy, posting externally, committing content referencing a crypto project other than `$THREE`, destroying unrecoverable data). This order touches none of them.
-- 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.
-- The em-dash and en-dash characters are banned in everything you write.
-
-## Step 0: re-derive the current state
-
-Confirm the alert is still live and measure its current volume:
-
- gcloud logging read 'resource.type="cloud_run_revision" resource.labels.service_name="three-ws-api" textPayload:"three-addons" textPayload:"Failed to fetch"' --freshness=24h --format='value(textPayload)' --project=aerial-vehicle-466722-p5 | wc -l
- gcloud logging read 'resource.type="cloud_run_revision" resource.labels.service_name="three-ws-api" textPayload:"three-addons" textPayload:"Failed to fetch"' --freshness=30d --format='value(textPayload)' --project=aerial-vehicle-466722-p5 | wc -l
- gcloud logging read 'resource.type="cloud_run_revision" resource.labels.service_name="three-ws-api" textPayload:"three-addons" textPayload:"Failed to fetch"' --freshness=24h --format='value(textPayload)' --project=aerial-vehicle-466722-p5 | head -3
-
-As measured 2026-10-24: **9 occurrences in 24h, 109 in 7d, 952 in 30d**, all a client-reported `unhandledrejection` with `name: "TypeError"`, `message: "Failed to fetch"`, and the SAME stack every time: `at https://three.ws/assets/three-addons-CXp-0JmD.js:4325:98926` (the hashed filename will differ after any rebuild; match on the `three-addons-` prefix and the "Failed to fetch" message instead of the exact hash). It fires across real, diverse page types in the same 30-day window, not one page: `https://three.ws/` (homepage), `/airdrops`, `/markets/digest`, and dozens of distinct `/markets/news/<date>/<slug>` article pages. Most (not all) samples carry a `HeadlessChrome` UA from Microsoft/Bing crawler IP ranges (`40.77.x.x`, `65.55.x.x`, `199.30.25.x`), but at least one real non-bot UA (`SEBot-WA`) also hit it on the bare homepage, so this is not purely a bot-traffic artifact.
-
-Pin the exact source line with a sourcemap instead of guessing from grep (this is the fast path; do this first):
-
- grep -n "sourcemap" vite.config.js || echo "confirmed: no sourcemap config, production build emits none today"
-
-Temporarily set `build.sourcemap: true` in `vite.config.js` (`build:` block, alongside `reportCompressedSize: false` around line 595), run `npm run build`, then locate the emitted `dist/assets/three-addons-*.js.map` (or wherever `vite.config.js`'s `build.outDir` points) and resolve line 4325, column 98926 to a real source file and line using Node's `source-map` package (already a transitive dependency via Vite/Rollup) or any installed source-map CLI. Revert the `build.sourcemap` line before committing (this order's diff must not permanently turn on sourcemaps as a side effect, unless you decide to propose that separately and justify it, which is out of scope here).
-
-## What is already ruled out (do not re-walk this ground)
-
-The obvious suspect is the site-wide "Walk Companion" first-visit auto-summon in `public/nav.js` (`initCompanionAutoStart()` around line 937, gated by `WALK_AUTO_SKIP` which excludes `/play`, `/walk`, `/club`, `/tour`, `/world`, `/scan`, `/arena`, `/pose`, `/splat`, `/capture`, `/timeline`, `/create/selfie`, `/create/video`, none of which match the failing pages): it auto-injects `/walk-companion.js` (built from `src/walk-companion.js`) for any first-time visitor (no `walk:companion:enabled` key in `localStorage`) after the page goes quiet, which matches a bot crawling with fresh storage on every page and a real first-time human visitor on `/`. That module imports `createWalkCompanion` from `walk-sdk/src/companion.js`, which loads an avatar GLB via `GLTFLoader` (`walk-sdk/src/internal/load-avatar.js`), the exact kind of code that bundles into the `three-addons` manualChunk (`vite.config.js` around line 625).
-
-Already read and confirmed properly wrapped, so do NOT assume these are the leak without new evidence:
-- `walk-sdk/src/internal/load-avatar.js`'s `loadWalkAvatar()`: both `loader.loadAsync()` calls (primary and fallback entry) are inside a `try/catch` (lines ~96-109), and `buildSharedController()`'s animation-manifest `fetch()` is inside its own `try/catch` (lines ~340-369).
-- `walk-sdk/src/companion.js`'s two call sites of `loadWalkAvatar()`: `mount()` wraps `await this._buildScene()` (which calls `_loadInto()` which calls `loadWalkAvatar()`) in `try/catch` (lines ~186-193); `setAvatar()` wraps its own call in `try/catch` (lines ~383-416).
-- `walk-sdk/src/internal/load-avatar.js`'s `makeLoader()` (lines ~64-75): its `await getMeshoptDecoder()` has no local `try/catch`, but a rejection here still propagates up through `loadWalkAvatar()` into the SAME `_buildScene()` try block `mount()` already catches, so this path is also covered.
-
-So the unhandled rejection is NOT the straightforward "avatar GLB failed to load" path. It is either (a) a different file bundled into the same `three-addons` chunk by `manualChunks` (OrbitControls, DecalGeometry, RoomEnvironment, HDRLoader, GLTFExporter, SkeletonUtils, WebGL capabilities, KTX2Loader, used by completely unrelated features like `agent-trade.js`, `assembly.js`, `walk-trails.js`, `animations-live-preview.js`, `app.js`), or (b) a page-navigation/teardown race (crawler tears down the page while a fetch this code starts is still in flight, and the specific promise that rejects is not the one any `.catch` is actually attached to, e.g. a detached timer callback or an event listener closure that re-enters after `unmount()` already ran). The sourcemap resolution in Step 0 settles which.
-
-## Task
-
-1. Resolve the exact source file and line via the sourcemap technique in Step 0.
-2. Read that file's surrounding code and identify the unguarded promise (a `fetch()`, `.load()`/`loadAsync()`, or `import()` whose rejection has no attached `.catch()` and whose caller's `await` is not inside a `try/catch`).
-3. Add a test-first regression that exercises this exact call path and asserts the rejection is caught (not left to propagate). Match the existing test style in `tests/` for whichever module this turns out to be (if it is anywhere under `walk-sdk/`, check `walk-sdk/src/**/*.test.js` or `walk-sdk/tests/` for its own test convention instead). Run it and confirm it fails against today's code for the identified reason.
-4. Fix the gap: wrap the call in `try/catch` (or attach `.catch()`), following the same recovery pattern already used elsewhere in the same file (log a warning via the existing `log.warn`/`log.debug` helper if one is imported, degrade gracefully, never let the exception reach the window as an unhandled rejection). Do not change behavior for the success path.
-5. Re-run the new test and confirm it passes. Run the full test suite for whatever module/package was touched (e.g. `npx vitest run` scoped to the relevant file(s), plus `walk-sdk`'s own test command if it has one, check its `package.json`) and confirm no regression.
-6. Revert the temporary `build.sourcemap: true` edit in `vite.config.js` if you made one for Step 0, confirming `git diff vite.config.js` is empty before committing (unless resolving the trace genuinely required a permanent change there, which is not expected).
-7. Run `npm run check:rules -- --paths <files touched>` and fix anything it flags.
-
-## Done when
-
-- The sourcemap-resolved source file and line are named in the report.
-- A regression test for that exact call path exists, failed before the fix for the stated reason, and passes after.
-- The fix wraps the previously-unguarded promise so its rejection can never reach `window`'s `unhandledrejection` handler; it degrades the same way sibling failure paths in the same file already do.
-- `vite.config.js` carries no leftover sourcemap change.
-- No regression in the touched module's existing test suite.
-- `npm run check:rules` passes on the touched paths.
-- `git diff` reviewed; every changed line is accounted for by this fix and its test.
-- The fix and its test are committed together on `evolve` with an explicit-path commit.
-- This file is removed, with a dated entry added to `prompts/finish/_context/production-100-PROGRESS.md` citing the fix commit SHA and today's measured 952-occurrences/30-day baseline so a future sweep can confirm the count stops climbing after deploy.
-
-## Never blocked
-
-| Looks like a blocker | It is not | Do this |
-|---|---|---|
-| The exact source line is still unclear after reading this file's "already ruled out" section | The sourcemap technique in Step 0 resolves it mechanically in minutes; grepping the minified bundle by hand (what produced the "already ruled out" list above) is the slow path, not the only path | Do the `build.sourcemap: true` + rebuild + resolve step before falling back to manual grepping |
-| The failure correlates heavily with `HeadlessChrome`/bot UAs, making it feel like a non-issue (bots don't matter) | At least one real non-bot UA (`SEBot-WA`) hit it on the bare homepage, and a crawler that can't execute three.ws's JS cleanly is itself an SEO/indexing risk worth fixing regardless of the end-user share | Fix it as a real defect; do not deprioritize on the assumption it is bot-only noise |
-| The root cause turns out to be in a shared Three.js addon file used by many unrelated features (not the walk companion at all) | That is an expected possible outcome per the "already ruled out" section; the fix is still narrowly scoped to that one file's call site | Fix only the identified unguarded call; do not refactor the broader `three-addons` chunk or change `manualChunks` as part of this order |
-| The root cause looks like a page-navigation/teardown race rather than a plain missing catch | Still fixable: guard against acting on a stale/detached instance (check an `this.mounted`-style flag, or an `AbortController` tied to the component's lifecycle, before the promise resolves/rejects) rather than declaring it unfixable | Add the same kind of mounted-check guard this codebase already uses elsewhere (e.g. `if (!this.mounted) return;` appears in `walk-sdk/src/companion.js`'s `setAvatar()`) around the resolved/rejected continuation |
-| No test convention exists yet for the exact file the bug lives in | `walk-sdk/` and `tests/` both have other precedent to follow; picking the closer one and matching its mocking style is enough | Do not invent a new testing framework or pattern; copy the nearest existing file's approach |
-
-## Report format
-
-State: the Step-0 log counts and sample, the sourcemap-resolved file/line, the diff, the failing-test confirmation before the fix and the passing-test output after, confirmation `vite.config.js` has no leftover diff, and the commit SHA.
diff --git a/prompts/finish/_context/production-100-PROGRESS.md b/prompts/finish/_context/production-100-PROGRESS.md
index 55aede518..8ef540f5f 100644
--- a/prompts/finish/_context/production-100-PROGRESS.md
+++ b/prompts/finish/_context/production-100-PROGRESS.md
@@ -1758,3 +1758,17 @@ Ran every test file from the order's step 4 list (`tests/economy-reconcile-recip
`npm run check:rules -- --paths api/_lib/solana-signers.js tests/solana-signers-attester.test.js`: "OK: no hard-rule violations." `git diff` reviewed: exactly the one new array entry (9 lines) plus the new test file (25 lines), no secret value anywhere, no live-key loading in the test (asserts against the static array only). Staged both paths explicitly (never `-A`). Fix commit: `f9c44c41b`.
Left: nothing for this order's own scope. Whether `economy-master` currently holds enough SOL to actually fund this plus every other under-floor signer is the separately tracked owner-action row this order explicitly said not to re-litigate; the registry fix alone makes the wallet visible to the existing 30-minute auto-topup cron, same acknowledged-limitation shape as prior orders in this file. `prompts/finish/425-auto-reasoning-ledger-attester-selfheal.md` deleted in this closing commit.
+
+## 2026-10-25: order 426 (auto-walk-companion unhandled fetch rejection) closed
+
+Measured: `gcloud logging read` against `three-ws-api` (project `aerial-vehicle-466722-p5`) for the `TypeError: Failed to fetch` client-error signature: 1 in the last 24h, 941 in the last 30d (order author's 2026-10-24 baseline: 9/24h, 109/7d, 952/30d; the 30d count is still essentially flat, confirming the bug is still live and worth fixing). Sample stack trace confirmed the exact chain: `window.fetch` -> `kd.load`/`G_.load` (three-addons chunk) -> `new Promise` -> `G_.loadAsync` -> `picker` chunk -> `z._loadInto` -> `z._buildScene` -> `z.mount` (companion.js), all on `walk-companion.js` auto-injected by `nav.js`'s `initCompanionAutoStart()`.
+
+Resolved the source location without the order's literal sourcemap-build step: read the actual vendored source directly (`node_modules/three/src/loaders/FileLoader.js`, `node_modules/three/examples/jsm/loaders/GLTFLoader.js`) via targeted `node -e` reads, since the minified frame names (`kd`, `G_`) matched FileLoader/GLTFLoader's method shapes exactly and the chunk names (`three-addons`, `picker`) confirmed which vendored module was in play. Root cause: `FileLoader.js` keeps a MODULE-LEVEL (not per-instance) `loading[url]` dedup table; `load()`'s `fetch(req).then()...finally()` chain is never returned or awaited by `load()` itself, and its `.catch()` handler does a bare `throw err` when `loading[url]` is already `undefined` at catch-time, a state that only arises when 2+ callers have registered against the identical URL concurrently. That `throw` has nothing after it but `.finally()` (which does not catch), so it becomes a genuine unhandled rejection no caller-side try/catch can intercept, because it rejects a promise walk-sdk never held a handle to. The V8 async-stack-trace frames (`mount`/`_buildScene`/`_loadInto`) are companion.js's own synchronous call stack at the time FileLoader's internal fetch was created, not evidence that loadAsync()'s own promise (which walk-sdk already try/catches) is the one rejecting.
+
+Did: test-first. Wrote `walk-sdk/test/load-avatar.test.mjs` (new file, 4 cases) against an as-yet-unmodified `load-avatar.js`; ran it and confirmed it failed for the right reason (`does not provide an export named 'coalesceLoad'`, since the guard did not exist yet). Added `coalesceLoad(key, start)` plus `cloneGltfForJoiner(gltf)` to `walk-sdk/src/internal/load-avatar.js`, right after `makeLoader()`: a pure, loader-agnostic in-flight map keyed by URL so a second concurrent request for the same key joins the first caller's promise instead of starting its own `loader.loadAsync()` call, eliminating the only way walk-sdk's own code could ever hand FileLoader two callbacks for one URL. A joined ("non-owner") caller gets a cloned `gltf.scene` rather than the live one, since the existing code mutates and reparents `gltf.scene` directly (`Object3D.add()` steals a child already attached elsewhere), so sharing the live object across two mounts would be unsafe. Rewired `loadWalkAvatar()`'s primary and fallback `loader.loadAsync(url)` calls to go through `coalesceLoad`. Reran the test: all 4 cases passed. Hit and fixed a self-inflicted floating-promise bug in my own fix (an unguarded `.finally()` on the cleanup listener) before it was done, confirmed by `node --test` reporting an unhandledRejection despite all assertions passing; fixed with a trailing `.catch(() => {})` on that listener branch only, not on the caller-facing chain. Ran `npm test` in `walk-sdk/`: 52/52 passed (0 before the fix existed, since the new file could not even import; 52/52 after).
+
+`npm run check:rules -- --paths walk-sdk/src/internal/load-avatar.js walk-sdk/test/load-avatar.test.mjs vite.config.js`: OK, no hard-rule violations (after fixing 4 em-dashes I introduced in my own new comments, caught by that same run before the fix). Temporary `build.sourcemap: true` line used for Step 0 investigation was reverted; `git diff vite.config.js` is empty both after reverting and immediately before this commit. Staged exactly `walk-sdk/src/internal/load-avatar.js` and `walk-sdk/test/load-avatar.test.mjs` (never `-A`); every other file modified in this shared worktree at commit time belonged to other concurrent agents and was left untouched. Fix commit: `278e53fff15d63e26aab5cb5a6ec6e58a95cf6a6`.
+
+Also found, but explicitly left untouched as out of scope (different page, different stack-trace frame names): `src/agent-trade.js`'s `loadAvatar()` calls `gltfLoader.load()` via an uncaught `.then()` and is invoked twice concurrently for the identical `AVATAR_GLB` URL, a separate instance of the same class of bug. Worth its own future order.
+
+Left: nothing for this order's own scope. The fix reduces risk structurally (it is impossible for walk-sdk's own call sites to ever register two callbacks against FileLoader's dedup table for the same URL after this change), independent of which exact concurrent-mount scenario in production was triggering it. A future sweep of the same `TypeError: Failed to fetch` signature after the next deploy should confirm the 30d count stops climbing from its ~941-952 baseline. `prompts/finish/426-auto-walk-companion-unhandled-fetch-rejection.md` deleted in this closing commit.