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.

21.8 KB
Raw Blame

Guard wiring: which checks actually run, and which never did

An unwired guard is not a guard.

scripts/check-gcloudignore.mjs was written to catch exactly one failure: .gcloudignore is an allowlist and never re-included services/, so two modules server/index.mjs imports at load time were absent from the image. The guard's own commit message said it "fails before a build instead of in production". It was referenced by no npm script, nothing ran it, and on 2026-09-04 production answered /api/healthz, /api/wk, /api/x402-pay and every /api/home/* route with a 500 for roughly thirteen hours. Nothing was red, because a missing re-include is not a build error, it is a runtime one.

That guard is now wired into gate and deploy:gcp:submit, pinned by tests/gcloudignore-wiring.test.js. Auditing the rest of the repo found the same shape 42 more times. This file is the classification of every one of them: what it checks, what it measured, and where it belongs.

How to re-derive the list

node -e "
const s=require('./package.json').scripts, all=Object.keys(s);
const bodies=all.map(k=>s[k]).join(' && ');
const guards=all.filter(k=>/^(check|audit):/.test(k));
const unwired=guards.filter(k=>!new RegExp('npm run '+k.replace(/[:.]/g,'\\\\\$&')+'(\\\\s|\$|&)').test(bodies));
console.log(guards.length+' guards, '+unwired.length+' unwired'); unwired.forEach(u=>console.log('  '+u));
"

Measured 2026-09-04: 73 guards, 39 unwired. Measured 2026-09-08 after this pass: 80 guards, 35 unwired, and every one of the 35 has a row below. Re-run 2026-10-25: 107 guards, 42 unwired, and all 42 still have a row (the registry in data/guards.json has grown with the new gate guards, for example check:mcp-counts and check:site-builder-embeds, which are wired, not unwired). tests/guard-wiring.test.js fails if a guard drops off gate or off the deploy path, and fails if a newly unwired guard has no row here.

The rule for gate

npm run gate is on the deploy path for every agent in this worktree. A guard earns a place in it only when all four hold:

  1. Green. A red guard in gate blocks everyone's work, including concurrent sessions.
  2. Repo-only. No network, no browser, no credential, no live database. A guard that reads production measures production, and production drifts for reasons a diff cannot fix.
  3. Fast. Roughly 15 seconds or less, measured solo on this machine.
  4. Deterministic. The same worktree gives the same answer. A guard that compares against a gitignored artifact, or against live infrastructure, does not.

Anything failing (2), (3) or (4) is not a lesser guard, it is a different kind of guard: it belongs on the deploy path, in npm test, or in an operator's hands.

Wired in this pass

Guard What it checks Exit Runtime Wired into
check:announce Every announcement pack clears the media, length and shape rules before it is published 0 3.5s gate
check:skills-seed data/skills/seed.json still matches the SKILL.md files it mirrors 0 3.7s gate
audit:motion public/animations/signatures.json still matches the baked clips it indexes 0 2.4s gate
audit:tour-global The committed public/tour-builder/tour.global.js matches a fresh build of the SDK in this repo 0 4.4s gate
check:doc-media Every doc figure exists, matches its manifest hash, has alt text, and is actually embedded by the doc that claims it 0 6.3s gate
check:images Every JS-rendered <img> in src/ declares a loading attribute 0 10.6s gate
audit:route-shadowing No api/** handler is unreachable behind a broader route rule 0 9.3s gate
check:docs-freshness Whether each doc's prose still matches the code it names, against the budget in data/docs-freshness-budget.json 0 11s gate
check:pay-skills The committed distributions/pay-skills/ provider files against a fresh projection of the service catalog, including orphaned files 0 1.2s gate
audit:deploy Committed symlinks, unsatisfied peers, undeclared api imports, an installed node_modules that matches package-lock.json, and the Draco/KTX2 decoder assets in dist/ 0 5.2s deploy:gcp:submit

audit:deploy is the one that is not a gate guard despite being green, repo-only and fast. Four of its five checks are already covered by tests/deploy-artifacts.test.js, which imports the same functions, so npm test runs them. The lockfile check, findLockDrift(), joined them on 2026-09-18 after a dependency bump nobody reinstalled shipped untested and every paid x402 route answered 500 on import. The fifth, findMissingDistAssets(), returns { skipped: true } whenever dist/ is absent, which is always true in vitest and always true in gate. It only means anything after a build, so it is wired into deploy:gcp:submit ahead of the upload, where a missing decoder asset (the /scene Draco outage) is still cheap to fix.

Wiring a guard is three edits, not one

data/guards.json is the registry that /guards and ../guards.md render, and it records the stage each guard runs in. Wiring a guard into gate without updating its stages leaves the public answer wrong in the confident direction: four guards went on claiming they were on-demand while the gate was already running them. scripts/audit-guards.mjs verifies a claim against the real npm chain, and tests/audit-guards.test.js fails if a gate step has no registry entry at all. So:

  1. Wire it into the chain in package.json.
  2. Set its stages in data/guards.json, then npm run build:guards to refresh public/guards.json.
  3. Add a wiring assertion in tests/guard-wiring.test.js.

audit:deploy needed a fourth: it runs in deploy:gcp:submit, which was not a stage the auditor could verify (it knew only prebuild, gate, build:gcp and pre-push). deploy:submit is now a real stage, checked against the real chain and described for readers in both the registry and the runbook.

Reds fixed in this pass

Guard Finding Fix
audit:tour-global The CDN bundle served at /tour-builder was built against an older walk-sdk than the repo Rebuilt and committed
check:images 3 <img> tags with no loading attribute (certificate poster, companion fallback face, print-insert QR) All three are the primary visible content, so loading="eager" decoding="async"
audit:route-shadowing GET /api/agents/vitals, documented in docs/agent-vitals.md and announced in the changelog, resolved to api/agents/[id].js instead of its own handler Explicit vercel.json rule above the /api/agents/([^/]+) catch-all
check:doc-media 30 problems: scene-studio never captured, and 29 usedBy claims naming docs that embedded no figure at all Captured scene-studio; embedded all 20 figures with their alt text and captions in the 27 docs that claimed them
check:runnable-docs 8 documented curl samples no longer answered as documented 7 declared their real contract (<!-- runnable: 401 ... --> for the two session-gated calls, 404/400 for the five illustrative ids and placeholders). The eighth is a deploy lag, below.

Still unwired, with the reason

Every row below was measured, not inferred from the script's name. Runtimes are wall clock on this machine; the browser sweeps were capped where noted.

Measures live production, not the repo

These fail whenever work has landed but not yet deployed, so they can never gate a commit. They belong to an operator, or to a post-deploy check.

Guard What it checks Exit Runtime Verdict
check:runnable-docs Executes every runnable sample in docs/ against the live API 1 15s manual (post-deploy). One finding left: /api/v1/hood-portfolios/universe 404s because api/v1/hood-portfolios/universe.js landed 2026-09-07 and production runs the 2026-09-05 image. Declaring 404 would be wrong the moment it deploys. Re-run after the next deploy.
check:windows-widget:live The same Windows widget contract against what three.ws is really serving: the deployed manifest, the worker bytes, the picker assets, and whether the deployed Adaptive Card expands in the board's engine 1 4.1s manual (post-deploy). Its 5 findings are one defect: production serves a card whose expressions the board's own engine refuses (Invalid expression format), so every pinned slot draws empty. The card in this tree expands cleanly, so the fix ships with the next deploy; re-run after it.
audit:seo Titles, descriptions, canonicals and sitemap agreement, fetched as Googlebot 0 17.2s manual (post-deploy). Fetches https://three.ws.
check:asset-encoding The largest compressible files under public/, fetched from the live site with a browser's exact Accept-Encoding, checking the bytes received against what the response promised 0 8.4s manual (post-deploy). Requests https://three.ws, so it measures the CDN rather than the diff: it exists because a brotli body served under an uncompressed content-length hung /create/selfie for every Chrome and Edge on 2026-09-11, and a page check never reads the largest binary on the site. Re-run after a deploy that changes a large asset.
audit:ibm-hosted The IBM-hosted page against a local publisher plus live three.ws 1 15.7s manual. Its 6 findings are all CORS refusals of https://three.ws/*.js from a 127.0.0.1 publisher origin, which is the harness's origin, not a page defect. Needs the real IBM origin to mean anything.
audit:mcp-reviewer Drives the published stdio MCP server the way a Connectors reviewer's host does 0 11.7s manual (pre-submission). Spawns the published server and hits live x402 endpoints; run before a directory submission.
check:cron-drift vercel.json crons against what Cloud Scheduler is really running 0 3.5s manual (needs live gcloud). Owned by fix-queue.
audit:cron-liveness Every cron handler resolves through the real route table, loads, and runs 0 19.6s manual. Boots a server and probes each job.
audit:cron-liveness:static The same, static resolution only, no server and no probe 0 23.5s manual. Repo-only and green, but 23.5s is too slow for gate and it imports every cron handler at module scope.
audit:llm-metering Whether any lane that spends money reports exactly $0 0 1.7s manual (ops). Reads usage_events from the live database; its answer is about production spend, not about the diff.
check:erc7710 Every DELEGATION_MANAGER_DEPLOYMENTS address is a deployed contract 0 3.0s manual. eth_getCode against public RPCs; a third-party RPC outage would read as a red gate.
check:evm-rpc Every EVM RPC endpoint answers a keyless server-side POST, in priority order 0 8.6s manual (ops). Network by definition.
check:trading-routes Each swap aggregator behind swap_quote/swap_execute quotes, builds, passes the wallet-outflow guard and simulates on mainnet with nothing signed 0 3.3s manual (ops). Network by definition: needs --wallet <funded pubkey>. Run it when a swap route starts refusing or failing; a refusal names the router and the exact transfer.
check:xai-models The Grok model catalog (GROK_MODELS in api/_lib/chat-models.js) against the ids, context sizes and prices xAI actually serves 0 0.5s manual (ops). Reads api.x.ai with GROK_API_KEY or XAI_API_KEY, else xAI's public model docs, so its answer moves whenever xAI ships or retires a model, not when the diff changes. Exit 2 means the source could not be read. Run it when the Grok rung of a failover chain starts erroring.
audit:deps The Python workers' pinned deps against the OSV vulnerability database 1 16.6s manual (security sweep). 285 advisories across 17 pinned versions, mostly transformers (two are RCE, fixed in 5.0.0 and 5.3.0). Each fix is a pin bump plus a worker image rebuild, which is its own piece of work, not a gate.
check:xai-models The Grok catalog (GROK_MODELS in api/_lib/chat-models.js) against the models xAI serves: ids, context windows and prices, from the xAI API with a key or its public model docs without one 0 0.7s manual (ops). Measured 2026-10-08 against the public docs (no key on this box): 8 of 8 ids in sync. xAI ships and retires models on its own schedule, so it can go red with no diff on our side. Run it when a Grok rung errors or before touching the catalog.
check:earnings-board Every row of /api/leaderboard/earnings, in all four windows, against the agent's own /api/agents/:id/earnings (creator fees, service income, total, rank) 2 0.2s manual (post-deploy). Measured 2026-10-08 against https://three.ws: the board answers 404 because the endpoint landed after the running image (fe2a8b24f), so exit 2 is a deploy lag, not a mismatch. Re-run after the next deploy, or point it at a local server with --base http://localhost:<port>. The offline half of the same comparison runs in npm test as tests/agent-earnings-board.test.js.
audit:upstreams:map Not a guard: --map regenerates docs/resilience.md 0 38.6s manual (generator). The guard half, audit:upstreams, is already in gate.
publish:stale Every publishable package's local version against npm view <name> time --json, flagging one whose version is already on npm but whose directory has real source commits after that publish 1 ~55s for 102 packages manual (pre-release). Network by definition (one npm view per package, concurrency 4) and about whether npm lags the repo, not about the diff. Measured 2026-10-14: 60+ of 102 publishable directories are stale, @three-ws/avatar-agent among them (1.2.3 published 2026-09-11, 7 real commits since). Run before cutting a release, or whenever "does npm match main" comes up.

Needs a credential this box does not hold

Guard What it checks Exit Runtime Verdict
audit:custodial-keys How much SOL sits behind a secret we can no longer decrypt 3 1.1s manual. Aborts without WALLET_ENCRYPTION_KEY, deliberately: without it every wallet would report undecryptable and the run would prove nothing. Read it with node scripts/read-service-env.mjs '^WALLET_ENCRYPTION_KEY$' --raw.
audit:home-credentials Whether connected homes are still reachable, or sealed by a key rotation 3 1.1s manual. Same key, same deliberate abort.
audit:wallet-flows Where the platform's SOL is and where it has been going 1 1.7s manual. Exits on no Solana RPC configured; needs SOLANA_RPC_FALLBACK_URLS or QUICKNODE_RPC_URL.
audit:service-wallets Every service wallet's pubkey, balance, SOL floor, and advertised fee-payer 0 2.3s manual. Runs, but a local .env carries a subset of the signer secrets, so most rows read UNCONFIGURED. Green here does not mean green in production.
check:relayer-balances Every decodable relayer signer against its documented minimum 0 1.4s manual. Same subset problem.
audit:rig-coverage Which real stored avatars the bone-name canonicalizer actually maps 1 0.8s manual. Requires S3_PUBLIC_DOMAIN; reads the live avatar library.
audit:web:provision Creates the QA account the authed sweeps need, through the real /register page not run n/a manual, deliberately not measured. It registers a real production account. Running it to measure it would create one. Documented in page-audit.md.

Needs a browser, and minutes

None of these can gate a commit: they drive real Chromium/WebKit across many routes and viewports. They are pre-event, pre-release and incident tools.

Guard What it checks Exit Runtime Verdict
audit:console Console errors, page errors and failed requests on every route in data/pages.json, desktop and mobile capped >600s (reached 591 of 796 route-viewport pairs in 600s) manual (pre-release).
audit:agent-operability Drives /create, /forge, /connect, an agent profile chat, and /launch with getByRole/getByLabel locators only, the way a computer-use agent or screen reader drives a page 0 needs a live BASE_URL plus audit:web:login for the avatar-limited and /launch steps manual (x-grok, pre-release).
audit:web / audit:web:login The full authed page sweep: console, network, layout capped >600s manual. See page-audit.md. audit:web:login mints the session audit:web replays, so it is the same sweep plus a login.
audit:agent-operability Whether /create, /forge, /connect, an agent profile and /launch can be completed with role and label locators only not run n/a manual. Needs a running npm run dev and drives a real browser (plus a bounded wait on a live generation), so it cannot sit in gate. See page-audit.md.
audit:a11y Playwright accessibility pass over the top pages killed at cap >578s (44 tests, one worker, several minutes each) manual. It is also a second playwright test run, which fights the shared dev server on :3000.
audit:overlays That no floating widget covers another, across routes and viewports capped >240s manual.
audit:mobile-touch Live computed touch-target sizes and spacing in a Pixel 5 context capped >240s manual.
audit:play-failures /play under deliberate failure injection (dead GLB, 500 on nonce, hostile query strings) capped >240s manual.
audit:meetup The /play live-event layer end to end capped >240s manual (pre-event). Needs npm run dev and npm run dev:walk-all, per its header.
audit:csp Every CSP violation in a real browser 2 6.0s manual (post-build). Defaults to 127.0.0.1:8099; it reported "25 of 25 pages never loaded, so this run proves nothing", which is the honest answer with nothing serving a built dist/ there. Run it as npm run audit:csp -- --base https://three.ws.
check:home-voice The hands-free voice loop: wake word, barge-in, self-trigger, confirmation guards 2 11.2s manual. Starts its own server and drives real speech lanes.
audit:garments Every wardrobe garment: manifest validation, GLB hash, attach, walk-gait deviation 1 133s manual. Real finding: 1 hard failure and 4 review flags out of 59. Owned by fix-queue.
check:glb:payload The mobile payload budget for a high-resolution GLB, loaded under WebKit and Android Chrome 1 17.4s manual. Needs npm run dev serving /avatar-embed, one or more GLB paths as arguments, and Playwright's WebKit and Chromium. It stages derived files under the gitignored public/_payload-check/ and exits 1 when either engine fails to render the finished GLB. The measured run predates the script being committed and died on ENOENT writing that directory.

Deterministic problems, deliberately not gated

Guard What it checks Exit Runtime Verdict
check:docs-search The docs search index against docs/**/*.md 1 11.6s manual (local convenience). public/docs-search-index.json is gitignored on purpose (~2 MB, rewritten by every docs edit) and regenerated by prebuild and postinstall, so the shipped copy is never stale and there is nothing to commit. Its error message used to say "commit the result", which was impossible; that message is fixed. In this shared worktree it also flips red within seconds of a peer editing a doc.

Wired, but not through another npm script

Guard Where it runs
check:rules The pre-push hook, as --base <remote sha> --head <local sha> per pushed ref (scripts/setup-git-hooks.mjs:66). Push-scoped is the point: it judges the commits leaving the machine, never the shared working tree, and it also lints each pushed commit subject. The bare npm script (17.5s) scans the whole worktree and would fail on other agents' in-flight work.
check:secrets The same hook, the same push-scoped mode, one line later, so no credential material leaves the machine.
check:community-skills prebuild, by path: node scripts/build-community-registry.mjs --check runs in the parallel group of every npm run build, and build:pages runs the same script in write mode. Measured 2026-10-08: exit 0 in 0.5s, 12 skills valid and community-skills/registry.json up to date. The npm entry point is the one a contributor runs before opening a pull request.
check:sri-pins build:gcp, through check:dist, which imports the same checkPins() from scripts/lib/agent-3d-releases.mjs and fails the deploy build on a stale pin, and tests/agent-3d-releases.test.js runs it under npm test. Measured 2026-10-08: exit 0 in 0.4s, 6 documented pins match data/agent-3d-releases.json. The npm entry point is the one to run while editing docs, and -- --fix rewrites stale hashes from the ledger.

Nothing was deleted

Every guard measured here does something no other check does. audit:deploy was the one candidate for deletion, since npm test already imports four of its five functions, but its decoder-asset check only fires after a build, so it moved to the deploy path instead of going away. check:docs-search looked like a decoy (its message told you to commit a gitignored file) and would have been a delete, except three open work orders under prompts/finish/ invoke it as a local check; its message was corrected instead.