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(reconstruct-sweep): close a job refused by a full avatar library instead of retrying it every tick

nirholas85d3b203499e
diff --git a/api/_lib/avatars.js b/api/_lib/avatars.js
index ea4878c90..d6b4f920c 100644
--- a/api/_lib/avatars.js
+++ b/api/_lib/avatars.js
@@ -608,6 +608,14 @@ export async function enforceQuotas(userId, incomingBytes) {
* @param {unknown} err
* @returns {boolean}
*/
+/**
+ * Copy for a job that reaches materialization with the owner's library full.
+ * Every lane that terminates a job on a plan limit (the status poll and the
+ * reconstruct sweep) shows the same words, relayed verbatim as error_kind 'input'.
+ */
+export const PLAN_LIMIT_JOB_ERROR =
+ 'Your avatar library is full on this plan. Delete an avatar or upgrade, then build this one again.';
+
export function isPlanLimitError(err) {
const code = /** @type {any} */ (err)?.code;
return typeof code === 'string' && code.startsWith('plan_limit');
diff --git a/api/avatars/_actions.js b/api/avatars/_actions.js
index 9d4440fb4..9f99bf2d0 100644
--- a/api/avatars/_actions.js
+++ b/api/avatars/_actions.js
@@ -3,7 +3,7 @@
import { getSessionUser, authenticateBearer, extractBearer, hasScope } from '../_lib/auth.js';
import { presignUpload, headObject, r2, publicUrl, putObject } from '../_lib/r2.js';
-import { storageKeyFor, enforceQuotas, searchPublicAvatars, stripOwnerFor, assertAvatarSlotAvailable, isPlanLimitError, defaultAvatarVisibilityFor } from '../_lib/avatars.js';
+import { storageKeyFor, enforceQuotas, searchPublicAvatars, stripOwnerFor, assertAvatarSlotAvailable, isPlanLimitError, PLAN_LIMIT_JOB_ERROR, defaultAvatarVisibilityFor } from '../_lib/avatars.js';
import { listAvatars } from '../_lib/avatars.js';
import { env } from '../_lib/env.js';
import { sql } from '../_lib/db.js';
@@ -513,12 +513,11 @@ const handleRegenerate = wrap(async (req, res) => {
// ── regenerate-status ─────────────────────────────────────────────────────────
-// Copy shown to a user whose library is full when a job reaches materialization.
-// handleReconstruct pre-flights the same quota, so this only fires on the race
-// (another avatar landed while the mesh was generating), but a job that loses
-// that race must still end somewhere the user can act on.
-const PLAN_LIMIT_JOB_ERROR =
- 'Your avatar library is full on this plan. Delete an avatar or upgrade, then build this one again.';
+// PLAN_LIMIT_JOB_ERROR is the copy shown to a user whose library is full when a
+// job reaches materialization. handleReconstruct pre-flights the same quota, so
+// this only fires on the race (another avatar landed while the mesh was
+// generating), but a job that loses that race must still end somewhere the user
+// can act on.
/**
* A materialize stage threw. If the cause was a plan-limit refusal, terminate
diff --git a/api/cron/reconstruct-sweep.js b/api/cron/reconstruct-sweep.js
index 1cfa75254..923011003 100644
--- a/api/cron/reconstruct-sweep.js
+++ b/api/cron/reconstruct-sweep.js
@@ -31,6 +31,7 @@ import { getRegenProviderForMode } from '../_lib/regen-provider.js';
import { finalizeReconstructStage, pollRiggingStage } from '../_lib/reconstruct-finalize.js';
import { isAllowedProviderResultUrl } from '../_lib/provider-result-url.js';
import { requireCron } from '../_lib/cron-auth.js';
+import { isPlanLimitError, PLAN_LIMIT_JOB_ERROR } from '../_lib/avatars.js';
// The browser polls every few seconds while the tab is open, so a row that has
// been untouched for 3 minutes is either abandoned or wedged — never a job
@@ -218,6 +219,15 @@ export default wrapCron(async (req, res) => {
summary.pending++;
}
} catch (err) {
+ // A full library is the owner's to fix, not a fault to retry: left open,
+ // the job re-ran the same refused materialization on every 5-minute tick
+ // (one job logged 'avatar count limit reached' all day on 2026-10-09).
+ // Close it with the copy the status poll relays, as that path does.
+ if (isPlanLimitError(err)) {
+ await failJob(job.job_id, job.user_id, PLAN_LIMIT_JOB_ERROR, 'input');
+ summary.failed++;
+ continue;
+ }
console.warn('[reconstruct-sweep] job error', { jobId: job.job_id, error: err?.message });
summary.errored++;
}
diff --git a/tests/reconstruct-sweep-plan-limit.test.js b/tests/reconstruct-sweep-plan-limit.test.js
new file mode 100644
index 000000000..4366b8bb4
--- /dev/null
+++ b/tests/reconstruct-sweep-plan-limit.test.js
@@ -0,0 +1,83 @@
+// The reconstruct sweep rescues jobs whose finalize was interrupted. When the
+// owner's avatar library is full, materialization is refused with a plan-limit
+// error. That is the owner's to fix, not a fault to retry: before this fix the
+// sweep logged it and left the job open, so the same refused materialization
+// re-ran on every 5-minute tick for the whole 30-day rescue window (production,
+// 2026-10-09). The job must close as failed with the copy the status poll relays.
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+const sqlCalls = [];
+let openRows = [];
+
+vi.mock('../api/_lib/db.js', () => {
+ const sql = vi.fn(async (strings, ...values) => {
+ const query = Array.isArray(strings) ? strings.join('?') : String(strings);
+ sqlCalls.push({ query, values });
+ if (/from avatar_regen_jobs\s+where mode = 'reconstruct'\s+and result_avatar_id is null/.test(query) && /select job_id/.test(query)) return openRows;
+ return [];
+ });
+ return { sql, isDbUnavailableError: () => false, isDbCapacityError: () => false };
+});
+vi.mock('../api/_lib/http.js', () => ({
+ wrapCron: (fn) => fn,
+ method: () => true,
+ json: (res, status, body) => {
+ res._json = { status, body };
+ return res;
+ },
+}));
+vi.mock('../api/_lib/cron-auth.js', () => ({ requireCron: () => true }));
+vi.mock('../api/_lib/regen-provider.js', () => ({
+ getRegenProviderForMode: vi.fn(async () => ({ name: 'gcp', instance: { status: vi.fn() } })),
+}));
+const finalize = vi.fn();
+vi.mock('../api/_lib/reconstruct-finalize.js', () => ({
+ finalizeReconstructStage: (...a) => finalize(...a),
+ pollRiggingStage: vi.fn(),
+}));
+vi.mock('../api/_lib/provider-result-url.js', () => ({ isAllowedProviderResultUrl: () => true }));
+
+const { default: handler } = await import('../api/cron/reconstruct-sweep.js');
+const { PLAN_LIMIT_JOB_ERROR } = await import('../api/_lib/avatars.js');
+
+const doneJob = {
+ job_id: 'job-1',
+ user_id: 'user-1',
+ mode: 'reconstruct',
+ status: 'done',
+ provider: 'gcp',
+ ext_job_id: 'ext-1',
+ result_glb_url: 'https://storage.googleapis.com/bucket/job-1.glb',
+ error: null,
+ params: {},
+};
+
+beforeEach(() => {
+ sqlCalls.length = 0;
+ openRows = [doneJob];
+ finalize.mockReset();
+});
+
+describe('reconstruct sweep on a full avatar library', () => {
+ it('closes the job as failed with the caller-facing plan-limit copy', async () => {
+ finalize.mockRejectedValue(Object.assign(new Error('avatar count limit reached on plan free'), { status: 402, code: 'plan_limit_count' }));
+ const res = {};
+ await handler({ method: 'GET', url: '/api/cron/reconstruct-sweep', headers: {} }, res);
+
+ const close = sqlCalls.find((c) => /set status = 'failed', error = \?, error_kind = \?/.test(c.query));
+ expect(close).toBeTruthy();
+ expect(close.values).toEqual([PLAN_LIMIT_JOB_ERROR, 'input', 'job-1', 'user-1']);
+ expect(res._json.body.failed).toBe(1);
+ expect(res._json.body.errored).toBe(0);
+ });
+
+ it('still leaves a genuine engine fault open for the next tick', async () => {
+ finalize.mockRejectedValue(new Error('fetch failed'));
+ const res = {};
+ await handler({ method: 'GET', url: '/api/cron/reconstruct-sweep', headers: {} }, res);
+
+ expect(sqlCalls.some((c) => /set status = 'failed', error = \?, error_kind/.test(c.query))).toBe(false);
+ expect(res._json.body.errored).toBe(1);
+ });
+});