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.

feat(seed-cron): rig the avatars it publishes, and keep the verdict on the keepers

nirholase0b96db4f96e
diff --git a/api/cron/forge-seed-cron.js b/api/cron/forge-seed-cron.js
index 19c87248e..e8ec4c4b8 100644
--- a/api/cron/forge-seed-cron.js
+++ b/api/cron/forge-seed-cron.js
@@ -50,9 +50,13 @@
// SEED_CRON_GATE jobs to gate per tick (default 2). Each costs one GLB
// fetch plus a mesh parse, so the ceiling keeps the
// tick inside its wall when a burst finishes at once.
-// SEED_CRON_RIG '1' routes accepted avatars through the auto-rigger
-// before publishing, so catalog entries arrive
-// animation-ready instead of frozen in bind pose.
+// SEED_CRON_RIG routes accepted avatars through the auto-rigger before
+// publishing, so catalog entries arrive animation-ready
+// instead of driven by the retarget fallback. ON by
+// default since 2026-09-09; set it to '0' to publish
+// static meshes again. A rig fault, or a rig that stops
+// answering (RIG_STALL_MS), publishes the gated keeper
+// static rather than losing it.
import { json, method, wrapCron } from '../_lib/http.js';
import { env } from '../_lib/env.js';
@@ -91,8 +95,9 @@ function intEnv(name, fallback, { min = 1, max = 50 } = {}) {
if (!Number.isFinite(n)) return fallback;
return Math.max(min, Math.min(max, Math.floor(n)));
}
-function boolEnv(name) {
+function boolEnv(name, fallback = false) {
const raw = String(process.env[name] ?? '').trim().toLowerCase();
+ if (!raw) return fallback;
return raw === '1' || raw === 'true' || raw === 'yes';
}
@@ -109,7 +114,22 @@ const SUBMIT_CONCURRENCY = 2;
const visionGateEnabled = () => boolEnv('SEED_CRON_VISION');
const visionGateBudgetMs = () => intEnv('SEED_CRON_VISION_MS', 20_000, { min: 5_000, max: 45_000 });
-const rigStageEnabled = () => boolEnv('SEED_CRON_RIG');
+// On by default since 2026-09-09. A catalog avatar that cannot be skeleton
+// driven is half an asset, and the audit that turned the default around found
+// ZERO of 17,349 published seed avatars had ever been rigged. The lane was
+// verified live the same day (a seeded mesh came back with a 52-joint
+// mixamorig skeleton, which is exactly what src/glb-canonicalize.js maps), and
+// every failure path here publishes the static keeper instead of losing it, so
+// the worst case of leaving it on is the asset the old default always shipped.
+// Set SEED_CRON_RIG=0 to go back to publishing static meshes.
+export const rigStageEnabled = () => boolEnv('SEED_CRON_RIG', true);
+// A rig job that never answers must not hold a row forever. advanceRigs polls
+// the ten oldest 'rigging' rows per tick, so a permanently stuck row would sit
+// at the front of that queue and starve the ones behind it. Past this age the
+// keeper is published static, which is what a reported rig failure already
+// does. Measured against started_at (the whole job, generation included)
+// because the rig submit has no timestamp column of its own.
+const RIG_STALL_MS = 45 * 60 * 1000;
// Gates per tick. Each one fetches the finished GLB and parses its glTF chunk;
// two keeps the phase in the low seconds even when a burst lands together.
const gateBatchSize = () => intEnv('SEED_CRON_GATE', 2, { min: 1, max: 10 });
@@ -499,10 +519,16 @@ async function advanceGates(origin) {
// public avatar for one creation. Only the tick that wins the transition writes.
// Returns null when this tick lost, so the caller reports that instead of
// claiming a publish it did not do.
-async function publishSeedAvatar({ job, verdict, rigged, rigCreationId = null }) {
+export async function publishSeedAvatar({ job, verdict, rigged, rigCreationId = null }) {
+ // The verdict is written on the keeper as well as on the reject. Only the
+ // rejects used to carry one, which made the live accept rate unmeasurable
+ // from this table (every accepted row looked like a row that was never
+ // gated) and left nothing to tune a threshold against except the failures.
const [won] = await sql`
update forge_seed_jobs
set status = 'done',
+ gate = ${verdict ? JSON.stringify(verdict) : null}::jsonb,
+ gate_reasons = ${verdict?.reasons?.length ? verdict.reasons : null}::text[],
finished_at = now()
where id = ${job.id}
and status <> 'done'
@@ -524,7 +550,8 @@ async function publishSeedAvatar({ job, verdict, rigged, rigCreationId = null })
}
// The slice of the verdict worth carrying on the avatar row forever. The full
-// object (every judge score, every render note) stays on forge_seed_jobs.gate.
+// object (every judge score, every render note) stays on forge_seed_jobs.gate,
+// for the keepers as well as the rejects.
// source_meta is read on every avatar detail render, so it gets the summary.
function gateSummary(verdict) {
if (!verdict) return null;
@@ -579,7 +606,7 @@ async function publishableGlbUrl(job) {
async function advanceRigs(origin) {
const rows = await sql`
select id, user_id, raw_client_id, prompt, model_category, creation_id, glb_url,
- rig_job_id, rig_creation_id, gate
+ rig_job_id, rig_creation_id, gate, started_at
from forge_seed_jobs
where status = 'rigging'
order by started_at asc
@@ -628,6 +655,24 @@ async function advanceRigs(origin) {
rigged: false,
avatar_id: avatarId,
});
+ } else if (Date.now() - new Date(job.started_at).getTime() > RIG_STALL_MS) {
+ // Still working, far too long. Treated exactly like a reported rig
+ // failure: the mesh already passed the gate, so it is published
+ // static rather than held back for a rigger that is not answering.
+ const avatarId = await publishSeedAvatar({ job, verdict: job.gate, rigged: false });
+ if (avatarId) {
+ await sql`
+ update forge_seed_jobs
+ set error = ${`rig stalled past ${Math.round(RIG_STALL_MS / 60000)}m, published static`}
+ where id = ${job.id}
+ `;
+ }
+ results.push({
+ job_id: job.id,
+ status: avatarId ? 'published' : 'already_published',
+ rigged: false,
+ stalled: true,
+ });
} else {
results.push({ job_id: job.id, status: 'rigging' });
}
diff --git a/tests/cron-seed-gate-record.test.js b/tests/cron-seed-gate-record.test.js
new file mode 100644
index 000000000..90bb232d7
--- /dev/null
+++ b/tests/cron-seed-gate-record.test.js
@@ -0,0 +1,120 @@
+// The forge seed cron records its quality verdict on the assets it KEEPS, not
+// only on the ones it throws away.
+//
+// Until 2026-09-09 only a rejected row carried `gate`, so every accepted row in
+// forge_seed_jobs was indistinguishable from a row that had never been gated at
+// all: 9,925 publishes in 30 days, zero verdicts. That made the live accept rate
+// unmeasurable from the table the cron writes, and left nothing but the failures
+// to tune a threshold against. A comment in the same file claimed the full
+// verdict was kept there, which is exactly the kind of claim that has to be a
+// test rather than a sentence.
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+const queries = [];
+vi.mock('../api/_lib/db.js', () => ({
+ sql: (strings, ...values) => {
+ const text = strings.join('?');
+ queries.push({ text, values });
+ // The compare-and-set that claims the row, then the avatar insert.
+ if (/update forge_seed_jobs[\s\S]*status = 'done'/.test(text)) {
+ // A row another tick already closed out returns nothing, which is what
+ // the compare-and-set is for.
+ return Promise.resolve(values.includes('taken-by-another-tick') ? [] : [{ id: 'job-1' }]);
+ }
+ if (/insert into avatars/.test(text)) return Promise.resolve([{ id: 'avatar-1' }]);
+ return Promise.resolve([]);
+ },
+}));
+
+const { publishSeedAvatar, rigStageEnabled } = await import('../api/cron/forge-seed-cron.js');
+
+const JOB = {
+ id: 'job-1',
+ user_id: 'user-1',
+ prompt: 'a lighthouse keeper in an oilskin coat',
+ model_category: 'avatar',
+ creation_id: 'creation-1',
+};
+
+const VERDICT = {
+ accepted: true,
+ gateVersion: 1,
+ reasons: [],
+ mesh: { flag: 'ok', score: 0.94, rigged: false, metrics: { vertexCount: 21804 } },
+ vision: { status: 'ok', mean: 0.82 },
+};
+
+function closeOut() {
+ return queries.find((q) => /update forge_seed_jobs[\s\S]*status = 'done'/.test(q.text));
+}
+
+describe('publishSeedAvatar', () => {
+ beforeEach(() => {
+ queries.length = 0;
+ });
+
+ it('writes the full verdict onto the job row it closes out', async () => {
+ const id = await publishSeedAvatar({ job: JOB, verdict: VERDICT, rigged: false });
+ expect(id).toBe('avatar-1');
+
+ const update = closeOut();
+ expect(update).toBeDefined();
+ expect(update.text).toContain('gate =');
+ const written = JSON.parse(update.values.find((v) => typeof v === 'string' && v.startsWith('{')));
+ expect(written.accepted).toBe(true);
+ expect(written.mesh.score).toBe(0.94);
+ expect(written.vision.mean).toBe(0.82);
+ });
+
+ it('carries the summary onto the avatar row as well', async () => {
+ await publishSeedAvatar({ job: JOB, verdict: VERDICT, rigged: false });
+ const insert = queries.find((q) => /insert into avatars/.test(q.text));
+ const meta = insert.values.find((v) => typeof v === 'string' && v.includes('quality_gate'));
+ expect(JSON.parse(meta).quality_gate).toMatchObject({ accepted: true, mesh_flag: 'ok', vision: 'ok' });
+ });
+
+ it('survives a keeper published without a verdict rather than failing the tick', async () => {
+ const id = await publishSeedAvatar({ job: JOB, verdict: null, rigged: false });
+ expect(id).toBe('avatar-1');
+ expect(closeOut().values).toContain(null);
+ });
+
+ it('publishes nothing when another tick already claimed the row', async () => {
+ const lost = await publishSeedAvatar({
+ job: { ...JOB, id: 'taken-by-another-tick' },
+ verdict: VERDICT,
+ rigged: false,
+ });
+ expect(lost).toBe(null);
+ // The verdict write rides on the claim, so losing it must not leave a
+ // second public avatar behind for the same creation.
+ expect(queries.some((q) => /insert into avatars/.test(q.text))).toBe(false);
+ });
+});
+
+// The rig stage: on unless something turns it off. Zero of the 17,349 avatars
+// published before 2026-09-09 were rigged, because the stage was opt-in and
+// nothing opted in.
+describe('rigStageEnabled', () => {
+ const original = process.env.SEED_CRON_RIG;
+ afterEach(() => {
+ if (original === undefined) delete process.env.SEED_CRON_RIG;
+ else process.env.SEED_CRON_RIG = original;
+ });
+
+ it('is on when the env says nothing', () => {
+ delete process.env.SEED_CRON_RIG;
+ expect(rigStageEnabled()).toBe(true);
+ });
+
+ it('is off when the env turns it off', () => {
+ process.env.SEED_CRON_RIG = '0';
+ expect(rigStageEnabled()).toBe(false);
+ });
+
+ it('is on when the env turns it on explicitly', () => {
+ process.env.SEED_CRON_RIG = '1';
+ expect(rigStageEnabled()).toBe(true);
+ });
+});