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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
fix(forge): stop discarding every director brief, and make run receipts name why a brief fell back
nirholas41e8e201ae65
diff --git a/api/_lib/forge-director-prompts.js b/api/_lib/forge-director-prompts.jsindex 1844059fa..eb122f017 100644--- a/api/_lib/forge-director-prompts.js+++ b/api/_lib/forge-director-prompts.js@@ -86,6 +86,17 @@ export function meshSubjectClass(prompt) {return classifySubject(prompt);}+// The forge accepts a prompt of at most 1000 characters (api/gpt-forge.js), and+// the director guard drops anything longer. Unbudgeted, the chain's specs ran+// 1032 to 1620 characters on 2026-10-11, so every brief was thrown away and the+// raw idea went to paint instead; the signed run receipts showed it as a+// "recovered" brief on every run. The budget is stated in words because the+// chain's models measurably ignore a character count (an "under 600 characters"+// ask still came back at 1071 to 1421) while holding a word count; 90 words of+// spec prose run about 600 characters, leaving headroom under the cap.+export const BRIEF_BUDGET_WORDS = 90;+const BRIEF_BUDGET_DIRECTIVE = `Keep the whole prompt under ${BRIEF_BUDGET_WORDS} words. `;+// Build the MESH_DIRECTOR system prompt for a given subject class — one// isolated subject, its construction, per-part PBR materials, one held art// style, subject-specific realism cues, and fine surface detail, ending in@@ -111,7 +122,9 @@ export function meshDirectorFor(subject = 'object') {'Always end with these composition constraints so the ' +'reference image reconstructs cleanly: full subject in frame, centered, isolated on a plain neutral ' +'background, one camera angle, even studio lighting, no cropping, no motion blur, no text or watermark, no ' +- 'collage or multi-view grid, no second subject. Output ONLY the rewritten prompt as a single line — no ' ++ 'collage or multi-view grid, no second subject. ' ++ BRIEF_BUDGET_DIRECTIVE ++ 'Output ONLY the rewritten prompt as a single line: no ' +'preamble, no quotes.');}@@ -178,6 +191,7 @@ export function avatarDirectorFor(subject = 'person') {'constraints: full body in frame head-to-toe, centered, isolated on a plain neutral background, no props ' +'gripped or crossing the silhouette, one camera angle facing the character, even studio lighting, no ' +'cropping, no motion blur, no text or watermark, no collage or multi-view grid, no second character. ' ++ BRIEF_BUDGET_DIRECTIVE +'Output ONLY the rewritten prompt as a single line — no preamble, no quotes.');}diff --git a/api/_lib/run-receipt.js b/api/_lib/run-receipt.jsindex a60120f40..7ed26e3a7 100644--- a/api/_lib/run-receipt.js+++ b/api/_lib/run-receipt.js@@ -167,19 +167,25 @@ export function finishReceipt(receipt, { outcome, glbUrl, viewerUrl, now = Date.finished_at: final === 'pending' ? null : new Date(now).toISOString(),duration_ms: final === 'pending' || !Number.isFinite(started) ? null : Math.max(0, now - started),outcome: final,- summary: summarize(final, issues),+ summary: summarize(final, issues, receipt.stages),issues,output: glbUrl ? { glb_url: glbUrl, ...(viewerUrl ? { viewer_url: viewerUrl } : {}) } : null,};}-function summarize(outcome, issues) {+function summarize(outcome, issues, stages = []) {const missed = issues.filter((i) => i.verdict === 'missed');const recovered = issues.filter((i) => i.verdict === 'recovered');+ // A skipped stage is not an issue, but it is not a pass either: "every stage+ // met" over a stage that never ran is the overclaim receipts exist to stop.+ const skipped = stages.filter((s) => s.verdict === 'skipped');const parts = [OUTCOME_LABELS[outcome] || outcome];if (missed.length) parts.push(`${missed.length} stage${missed.length === 1 ? '' : 's'} missed (${missed.map((i) => i.label).join(', ')})`);if (recovered.length) parts.push(`${recovered.length} carried by a fallback (${recovered.map((i) => i.label).join(', ')})`);- if (!missed.length && !recovered.length && outcome === 'delivered') parts.push('every stage met its contract');+ if (!missed.length && !recovered.length && outcome === 'delivered') {+ parts.push(skipped.length ? 'Every stage that ran met its contract' : 'Every stage met its contract');+ }+ if (skipped.length) parts.push(`${skipped.length} skipped (${skipped.map((s) => s.label).join(', ')})`);return `${parts.join('. ')}.`;}@@ -252,7 +258,28 @@ export function subjectGateStage({ hasImage, givenMesh, nonHumanoid, override })* fixed one as the fallback) or 'mesh' (an optional enrichment; the raw prompt* is a valid brief on its own).*/-export function briefStage({ kind, hasImage, directed, knownMark = false, ms }) {+// Why the director's brief was not used, in words a reader can check against+// the stage time. `fallback` is what directPrompt reported via onFallback.+function directorFallbackCause(fallback) {+ switch (fallback?.reason) {+ case 'too_long':+ return `The director's brief ran to ${fallback.chars ? `${fallback.chars} characters` : 'over 1000 characters'}; the forge accepts at most 1000, so it was set aside.`;+ case 'unfinished':+ return 'The director reply stopped mid-sentence, so it was treated as clipped and set aside.';+ case 'link':+ return 'The director reply carried a link, which marks a provider notice rather than a brief, so it was set aside.';+ case 'not_enriched':+ return 'The director reply added nothing to the prompt, so the original wording was kept.';+ case 'empty':+ return 'The director returned an empty reply.';+ case 'no_reply':+ return 'No reply from the director models within the time allowed.';+ default:+ return 'The director did not return a usable brief.';+ }+}++export function briefStage({ kind, hasImage, directed, knownMark = false, fallback = null, ms }) {if (hasImage) {return { id: 'brief', label: 'Brief', expected: 'A brief for the reference picture.', observed: 'A reference image was supplied, so it was used directly.', verdict: 'skipped', ms };}@@ -266,6 +293,7 @@ export function briefStage({ kind, hasImage, directed, knownMark = false, ms })ms,};}+ const cause = directorFallbackCause(fallback);if (kind === 'avatar') {const expected = 'A director-written brief that frames the whole figure head to toe in a neutral A-pose.';return directed@@ -276,7 +304,7 @@ export function briefStage({ kind, hasImage, directed, knownMark = false, ms })expected,observed: 'The fixed full-body brief was appended to the prompt as written.',verdict: 'recovered',- cause: 'The director model did not return a usable brief in time; the fixed brief keeps the framing.',+ cause: `${cause} The fixed brief keeps the framing.`,ms,};}@@ -289,7 +317,7 @@ export function briefStage({ kind, hasImage, directed, knownMark = false, ms })expected,observed: 'The prompt was used as written.',verdict: 'recovered',- cause: 'The director model did not return a usable brief in time.',+ cause,ms,};}diff --git a/api/_mcp-studio/forge-client.js b/api/_mcp-studio/forge-client.jsindex 6dafd3231..31d27f222 100644--- a/api/_mcp-studio/forge-client.js+++ b/api/_mcp-studio/forge-client.js@@ -240,41 +240,82 @@ export async function rig(base, glbUrl, { timeoutEnv } = {}) {const DIRECTOR_MAX_TOKENS = 400;const DIRECTOR_TIMEOUT_MS = 20_000;-// Longest brief we forward. The director's own specs land near 800 characters;-// beyond this the model has stopped writing a prompt and started writing prose.+// Longest brief we forward, and the longest prompt the forge itself accepts+// (api/gpt-forge.js rejects anything over 1000). The director prompts ask for+// under 800 (BRIEF_BUDGET_CHARS) so a spec has room to spare.const DIRECTOR_MAX_CHARS = 1000;// The director's system prompts ask for a complete spec, and a complete spec is-// a finished sentence: every well-formed one observed in production closes on a-// period after its negatives clause ("...no second subject."). A generation that-// ran out of tokens cannot, which makes terminal punctuation the one signal that-// separates a whole brief from a clipped one without guessing at grammar. Both-// production truncations fail it ("A small," and "A classic wooden rocking chair-// with gracefully curved"), as does any fragment ending on a separator or a-// dangling connective, with no per-word list to keep current.+// a finished sentence. A generation that ran out of tokens cannot finish one,+// which makes the ending the one signal that separates a whole brief from a+// clipped one without guessing at grammar. Both production truncations fail it+// ("A small," and "A classic wooden rocking chair with gracefully curved"), as+// does any fragment ending on a separator or a dangling connective.const ENDS_COMPLETE = /[.!?]["'\u201d\u2019)\]]*$/;+// The prompts also mandate the LAST words of the brief: the composition list+// closing on "no second subject" (mesh) or "no second character" (avatar). The+// chain copies that list verbatim and often stops without a period, and treating+// those as clipped threw away every brief on 2026-10-11 (run receipts showed the+// brief "recovered" on each studio run). A clip lands mid-word or mid-list, never+// exactly on the mandated last phrase, so that phrase is as whole an ending as a+// period. "no second" alone is still a clip.+const ENDS_ON_CLOSING_CONSTRAINT = /(?:\bno second (?:subject|character)s?|\bone (?:subject|character) only)$/i;+// Decide whether a director rewrite is safe to forward in place of the user's-// own words. The director is a quality lever that must never cost a caller their-// intent, so anything that fails this check falls back to the raw prompt rather-// than shipping a fragment. Erring toward rejection is cheap: the fallback is-// the caller's own wording, which is always a valid brief. Pure: same inputs to-// same verdict.-export function isUsableDirectorRewrite(refined, rawPrompt) {- if (typeof refined !== 'string') return false;+// own words, and if not, name why: the run receipt states the reason, so a+// fallback is never filed under a guess. The director is a quality lever that+// must never cost a caller their intent, so anything named here falls back to+// the raw prompt rather than shipping a fragment. Erring toward rejection is+// cheap: the fallback is the caller's own wording, which is always a valid+// brief. Pure: same inputs to same verdict. gpt-forge-client.js re-exports this.+// Returns null when usable, else 'empty' | 'too_long' | 'unfinished' | 'link' |+// 'not_enriched'.+export function directorRewriteProblem(refined, rawPrompt) {+ if (typeof refined !== 'string') return 'empty';const text = refined.trim();- if (text.length < 3 || text.length > DIRECTOR_MAX_CHARS) return false;- if (!ENDS_COMPLETE.test(text)) return false;+ if (text.length < 3) return 'empty';+ if (text.length > DIRECTOR_MAX_CHARS) return 'too_long';+ if (!ENDS_COMPLETE.test(text) && !ENDS_ON_CLOSING_CONSTRAINT.test(text)) return 'unfinished';+ // A brief describes an object; it never carries a link. A URL or a markdown+ // link means the reply is a provider notice ("raise the key budget at+ // https://...") or chatter, and reconstructing a mesh from it is how 22+ // production generations came out of a billing message.+ if (/https?:\/\/|\]\(|\bwww\./i.test(text)) return 'link';// The director's contract is to ENRICH a rough idea into a denser spec. A// result no longer than what the caller typed has added nothing, and is far// more likely a clipped opening clause than a genuine tightening, so the// user's own wording is the better brief.const raw = String(rawPrompt ?? '').trim();- if (raw && text.length <= raw.length) return false;- return true;+ if (raw && text.length <= raw.length) return 'not_enriched';+ return null;+}++export function isUsableDirectorRewrite(refined, rawPrompt) {+ return directorRewriteProblem(refined, rawPrompt) === null;+}++// Shared tail of both clients' directPrompt: clean the model reply, judge it,+// and tell the caller why it was dropped. `onFallback` receives+// { reason, chars? } where reason is 'no_reply' or a directorRewriteProblem code.+export function finishDirectorReply(text, rawPrompt, onFallback) {+ if (!text) {+ onFallback?.({ reason: 'no_reply' });+ return null;+ }+ // First line only, then strip wrapping quotes; the reverse order leaves a+ // dangling quote when the model adds commentary lines after a quoted prompt.+ const firstLine = text.trim().split('\n')[0].trim();+ const refined = firstLine.replace(/^["'“”]+|["'“”]+$/g, '').trim();+ const reason = directorRewriteProblem(refined, rawPrompt);+ if (reason === null) return refined;+ // Returning null here is the documented fail-soft path: the caller forwards+ // the caller's original prompt unchanged, which is always a valid brief.+ onFallback?.(reason === 'too_long' ? { reason, chars: refined.length } : { reason });+ return null;}-export async function directPrompt(instruction, rawPrompt) {+export async function directPrompt(instruction, rawPrompt, { onFallback } = {}) {const user = `Idea: ${rawPrompt}`;let text = null;@@ -316,18 +357,11 @@ export async function directPrompt(instruction, rawPrompt) {});text = result?.text || null;} catch {- return null;+ text = null;}}- if (!text) return null;- // First line only, then strip wrapping quotes; the reverse order leaves a- // dangling quote when the model adds commentary lines after a quoted prompt.- const firstLine = text.trim().split('\n')[0].trim();- const refined = firstLine.replace(/^["'“”]+|["'“”]+$/g, '').trim();- // Returning null here is the documented fail-soft path: the caller forwards- // the caller's original prompt unchanged, which is always a valid brief.- return isUsableDirectorRewrite(refined, rawPrompt) ? refined : null;+ return finishDirectorReply(text, rawPrompt, onFallback);}function sleep(ms) {diff --git a/api/_mcp-studio/gpt-forge-client.js b/api/_mcp-studio/gpt-forge-client.jsindex 879786aaf..9b608a7cf 100644--- a/api/_mcp-studio/gpt-forge-client.js+++ b/api/_mcp-studio/gpt-forge-client.js@@ -18,6 +18,7 @@import { selfOrigin } from '../_lib/self-origin.js';import { watsonxConfig, watsonxChatComplete } from '../_lib/watsonx.js';import { llmComplete } from '../_lib/llm.js';+import { isUsableDirectorRewrite, finishDirectorReply } from './forge-client.js';import { TICKET_HEADER, newTicket, ticketHandle } from '../_lib/forge-submit-ticket.js';const DEFAULT_TIMEOUT_MS = 180_000;@@ -361,45 +362,11 @@ const DIRECTOR_MAX_TOKENS = 400;const DIRECTOR_TIMEOUT_MS = 15_000;const DIRECTOR_WATSONX_SHARE_MS = 6_000;-// Longest brief we forward. The director's own specs land near 800 characters;-// beyond this the model has stopped writing a prompt and started writing prose.-const DIRECTOR_MAX_CHARS = 1000;+// The rewrite guard is shared with forge-client.js so the two clients cannot+// drift apart again (this copy once had the URL check and the other did not).+export { isUsableDirectorRewrite };-// The director's system prompts ask for a complete spec, and a complete spec is-// a finished sentence: every well-formed one observed in production closes on a-// period after its negatives clause ("...no second subject."). A generation that-// ran out of tokens cannot, which makes terminal punctuation the one signal that-// separates a whole brief from a clipped one without guessing at grammar. Both-// production truncations fail it, as does any fragment ending on a separator or-// a dangling connective, with no per-word list to keep current.-const ENDS_COMPLETE = /[.!?]["'\u201d\u2019)\]]*$/;--// Decide whether a director rewrite is safe to forward in place of the user's-// own words. The director is a quality lever that must never cost a caller their-// intent, so anything that fails this check falls back to the raw prompt rather-// than shipping a fragment. Erring toward rejection is cheap: the fallback is-// the caller's own wording, which is always a valid brief. Pure: same inputs to-// same verdict.-export function isUsableDirectorRewrite(refined, rawPrompt) {- if (typeof refined !== 'string') return false;- const text = refined.trim();- if (text.length < 3 || text.length > DIRECTOR_MAX_CHARS) return false;- if (!ENDS_COMPLETE.test(text)) return false;- // A brief describes an object; it never carries a link. A URL or a markdown- // link means the reply is a provider notice ("raise the key budget at- // https://...") or chatter, and reconstructing a mesh from it is how 22- // production generations came out of a billing message.- if (/https?:\/\/|\]\(|\bwww\./i.test(text)) return false;- // The director's contract is to ENRICH a rough idea into a denser spec. A- // result no longer than what the caller typed has added nothing, and is more- // likely a clipped opening clause than a genuine tightening, so the user's- // own wording is the better brief.- const raw = String(rawPrompt ?? '').trim();- if (raw && text.length <= raw.length) return false;- return true;-}--export async function directPrompt(instruction, rawPrompt) {+export async function directPrompt(instruction, rawPrompt, { onFallback } = {}) {const user = `Idea: ${rawPrompt}`;let text = null;@@ -446,18 +413,11 @@ export async function directPrompt(instruction, rawPrompt) {});text = result?.text || null;} catch {- return null;+ text = null;}}- if (!text) return null;- // First line only, then strip wrapping quotes; the reverse order leaves a- // dangling quote when the model adds commentary lines after a quoted prompt.- const firstLine = text.trim().split('\n')[0].trim();- const refined = firstLine.replace(/^["'“”]+|["'“”]+$/g, '').trim();- // Returning null here is the documented fail-soft path: the caller forwards- // the caller's original prompt unchanged, which is always a valid brief.- return isUsableDirectorRewrite(refined, rawPrompt) ? refined : null;+ return finishDirectorReply(text, rawPrompt, onFallback);}function sleep(ms) {diff --git a/api/_mcp-studio/tools.js b/api/_mcp-studio/tools.jsindex c183c513b..48c5fcc2c 100644--- a/api/_mcp-studio/tools.js+++ b/api/_mcp-studio/tools.js@@ -447,9 +447,10 @@ async function handleForgeFree(args, _auth, req, ctx = {}) {run.add(briefStage({ kind: 'mesh', knownMark: true }));} else {const t0 = Date.now();- const directed = await directPrompt(meshDirectorFor(meshSubjectClass(prompt)), prompt);+ let fallback = null;+ const directed = await directPrompt(meshDirectorFor(meshSubjectClass(prompt)), prompt, { onFallback: (f) => (fallback = f) });if (directed) effective = directed;- run.add(briefStage({ kind: 'mesh', directed: Boolean(directed), ms: Date.now() - t0 }));+ run.add(briefStage({ kind: 'mesh', directed: Boolean(directed), fallback, ms: Date.now() - t0 }));}return finishMesh(run, {base,@@ -518,9 +519,10 @@ async function handleTextToAvatar(args, _auth, req, ctx = {}) {if (prompt && !imageUrl) {const subject = classifySubject(prompt) === 'animal' ? 'animal' : 'person';const t0 = Date.now();- const directed = await directPrompt(avatarDirectorFor(subject), prompt);+ let fallback = null;+ const directed = await directPrompt(avatarDirectorFor(subject), prompt, { onFallback: (f) => (fallback = f) });effective = directed || avatarFallbackBrief(prompt, subject);- run.add(briefStage({ kind: 'avatar', directed: Boolean(directed), ms: Date.now() - t0 }));+ run.add(briefStage({ kind: 'avatar', directed: Boolean(directed), fallback, ms: Date.now() - t0 }));} else {run.add(briefStage({ kind: 'avatar', hasImage: true }));}@@ -556,9 +558,10 @@ async function handleMeshForge(args, _auth, req, ctx = {}) {run.add(briefStage({ kind: 'mesh', knownMark: true }));} else {const t0 = Date.now();- const directed = await directPrompt(meshDirectorFor(meshSubjectClass(prompt)), prompt);+ let fallback = null;+ const directed = await directPrompt(meshDirectorFor(meshSubjectClass(prompt)), prompt, { onFallback: (f) => (fallback = f) });if (directed) effective = directed;- run.add(briefStage({ kind: 'mesh', directed: Boolean(directed), ms: Date.now() - t0 }));+ run.add(briefStage({ kind: 'mesh', directed: Boolean(directed), fallback, ms: Date.now() - t0 }));}} else {run.add(briefStage({ kind: 'mesh', hasImage: true }));@@ -656,9 +659,10 @@ async function handleForgeAvatar(args, _auth, req, ctx = {}) {if (prompt && !imageUrl) {const subject = classifySubject(prompt) === 'animal' ? 'animal' : 'person';const t0 = Date.now();- const directed = await directPrompt(avatarDirectorFor(subject), prompt);+ let fallback = null;+ const directed = await directPrompt(avatarDirectorFor(subject), prompt, { onFallback: (f) => (fallback = f) });effective = directed || avatarFallbackBrief(prompt, subject);- run.add(briefStage({ kind: 'avatar', directed: Boolean(directed), ms: Date.now() - t0 }));+ run.add(briefStage({ kind: 'avatar', directed: Boolean(directed), fallback, ms: Date.now() - t0 }));} else {run.add(briefStage({ kind: 'avatar', hasImage: true }));}diff --git a/data/changelog.json b/data/changelog.jsonindex e8920eff6..7dd9b8d6d 100644--- a/data/changelog.json+++ b/data/changelog.json@@ -1,6 +1,15 @@{"$comment": "Curated changelog entries for three.ws, the editorial layer of the public changelog. New PAGE launches are tracked automatically via the `added` field in data/pages.json; this file is for everything else holders care about: improvements, fixes, SDK releases, trading/payments capabilities, security work. scripts/build-page-index.mjs merges both sources into CHANGELOG.md, public/changelog.json, and public/changelog.xml. Newest first. Allowed tags: feature, improvement, fix, sdk, infra, docs, security, desktop (desktop entries become the desktop app's release notes). `link` is optional and must be a live three.ws path.","entries": [+ {+ "date": "2026-10-11",+ "title": "The prompt director works again, found by its own run receipts",+ "link": "/runs",+ "summary": "The first receipts showed the director's brief falling back on every Studio run. The replies were arriving in 5 to 10 seconds but ran past the 1000-character prompt cap or ended on the closing constraint the director is told to end on, and both were discarded as clipped. The director now writes to a word budget the models actually follow, the guard accepts the mandated ending, both forge clients share one guard, and a receipt now names the exact reason a brief fell back (too long with its length, unfinished, no reply) instead of a generic timeout. Receipts also stop saying every stage met when a stage was skipped.",+ "tags": [+ "fix"+ ]+ },{"date": "2026-10-11","title": "Every 3D generation now writes a signed run receipt",diff --git a/tests/api/forge-director.test.js b/tests/api/forge-director.test.jsindex c386b6502..db82e2e30 100644--- a/tests/api/forge-director.test.js+++ b/tests/api/forge-director.test.js@@ -123,4 +123,38 @@ describe('directPrompt — in-process Granite director', () => {state.watsonx.mockResolvedValue({ text: 'A red car.' });expect(await directPrompt(MESH_DIRECTOR, 'a red sports car with chrome trim')).toBeNull();});++ // The run receipt reports why a brief fell back, so directPrompt tells the+ // caller which failure it hit rather than collapsing them all into null.+ it('reports the fallback reason so the receipt can state it exactly', async () => {+ const seen = [];+ const onFallback = (f) => seen.push(f);++ state.watsonx.mockResolvedValue({ text: `${'A brass lantern with a glass chimney, '.repeat(30)}centered.` });+ expect(await directPrompt(MESH_DIRECTOR, 'lantern', { onFallback })).toBeNull();+ expect(seen.at(-1)).toMatchObject({ reason: 'too_long' });+ expect(seen.at(-1).chars).toBeGreaterThan(1000);++ state.watsonx.mockResolvedValue({ text: 'A classic wooden rocking chair with gracefully curved' });+ await directPrompt(MESH_DIRECTOR, 'rocking chair', { onFallback });+ expect(seen.at(-1)).toMatchObject({ reason: 'unfinished' });++ state.watsonx.mockRejectedValue(new Error('down'));+ state.chain.mockRejectedValue(new Error('all rungs dead'));+ await directPrompt(MESH_DIRECTOR, 'anything', { onFallback });+ expect(seen.at(-1)).toMatchObject({ reason: 'no_reply' });++ state.watsonx.mockResolvedValue({ text: 'A worn oak chair with turned legs, centered.' });+ const before = seen.length;+ expect(await directPrompt(MESH_DIRECTOR, 'chair', { onFallback })).toBe('A worn oak chair with turned legs, centered.');+ expect(seen.length).toBe(before);+ });++ it('reports the same reasons from the client the studio tools use', async () => {+ const { directPrompt: studioDirect } = await import('../../api/_mcp-studio/gpt-forge-client.js');+ const seen = [];+ state.watsonx.mockResolvedValue({ text: `${'A brass lantern with a glass chimney, '.repeat(30)}centered.` });+ expect(await studioDirect(MESH_DIRECTOR, 'lantern', { onFallback: (f) => seen.push(f) })).toBeNull();+ expect(seen[0]).toMatchObject({ reason: 'too_long' });+ });});diff --git a/tests/forge-director-rewrite.test.js b/tests/forge-director-rewrite.test.jsindex a8d60d851..6f41ed3cb 100644--- a/tests/forge-director-rewrite.test.js+++ b/tests/forge-director-rewrite.test.js@@ -8,7 +8,9 @@// the director's stated contract: it may improve a generation, never break one.import { describe, expect, it } from 'vitest';-import { isUsableDirectorRewrite } from '../api/_mcp-studio/forge-client.js';+import { isUsableDirectorRewrite, directorRewriteProblem } from '../api/_mcp-studio/forge-client.js';+import { isUsableDirectorRewrite as isUsableFromGptClient } from '../api/_mcp-studio/gpt-forge-client.js';+import { meshDirectorFor, avatarDirectorFor } from '../api/_lib/forge-director-prompts.js';const RAW = 'a small ceramic teapot with a bamboo handle';@@ -71,8 +73,52 @@ describe('isUsableDirectorRewrite', () => {expect(isUsableDirectorRewrite(undefined, RAW)).toBe(false);});+ // Run receipts showed the brief falling back on every studio run on 2026-10-11.+ // The director prompts tell the model to END on the composition list ("... no+ // collage or multi-view grid, no second subject"), and real outputs from the+ // chain copy that list verbatim with no closing period, so the period-only+ // completeness test rejected every well-formed brief it was asked to produce.+ it('accepts a brief that ends on the mandated closing constraint without a period', () => {+ const spec = COMPLETE_SPEC.replace(/, no text or watermark\.$/, ', no text or watermark, no collage or multi-view grid, no second subject');+ expect(isUsableDirectorRewrite(spec, RAW)).toBe(true);+ expect(isUsableDirectorRewrite(spec.replace(/no second subject$/, 'no second character'), RAW)).toBe(true);+ expect(isUsableDirectorRewrite(spec.replace(/no second subject$/, 'one character only'), RAW)).toBe(true);+ // A clip inside that same closing list is still a clip.+ expect(isUsableDirectorRewrite(spec.replace(/no second subject$/, 'no second'), RAW)).toBe(false);+ });++ it('asks the director for a brief the forge will accept (it rejects prompts over 1000 characters)', () => {+ for (const ins of [meshDirectorFor('object'), avatarDirectorFor('person')]) {+ // Words, not characters: the chain's models ignore a character count.+ const m = /under (\d+) words/.exec(ins);+ expect(m, 'the director prompt states a length budget').not.toBeNull();+ // About 7 characters per word of spec prose; stay well under 1000.+ expect(Number(m[1]) * 7).toBeLessThan(1000);+ }+ });++ it('is one implementation shared by both forge clients', () => {+ expect(isUsableFromGptClient).toBe(isUsableDirectorRewrite);+ });+it('still accepts an enriched spec when the caller brief is absent', () => {expect(isUsableDirectorRewrite(COMPLETE_SPEC, '')).toBe(true);expect(isUsableDirectorRewrite(COMPLETE_SPEC, undefined)).toBe(true);});});++// The run receipt has to say WHY a brief fell back, so the guard names the+// problem instead of only answering yes or no. Before this every fallback was+// filed as "did not return a usable brief in time", which was false for each of+// the 2026-10-11 runs: the replies arrived in 5 to 10 s and were too long.+describe('directorRewriteProblem', () => {+ it('names each way a rewrite can be unusable', () => {+ expect(directorRewriteProblem(COMPLETE_SPEC, RAW)).toBeNull();+ expect(directorRewriteProblem(`${'x'.repeat(1000)}.`, RAW)).toBe('too_long');+ expect(directorRewriteProblem('A small,', RAW)).toBe('unfinished');+ expect(directorRewriteProblem(`${COMPLETE_SPEC.slice(0, -1)} at https://example.com.`, RAW)).toBe('link');+ expect(directorRewriteProblem('A red car.', 'a red sports car with chrome trim')).toBe('not_enriched');+ expect(directorRewriteProblem('', RAW)).toBe('empty');+ expect(directorRewriteProblem(null, RAW)).toBe('empty');+ });+});diff --git a/tests/run-receipt.test.js b/tests/run-receipt.test.jsindex 59069b19c..2ccf3aee3 100644--- a/tests/run-receipt.test.js+++ b/tests/run-receipt.test.js@@ -98,10 +98,25 @@ describe('run receipt core', () => {expect(done.outcome).toBe('delivered');expect(done.issues).toEqual([]);expect(done.duration_ms).toBe(3000);- expect(done.summary).toMatch(/every stage met its contract/);+ expect(done.summary).toBe('Delivered as expected. Every stage met its contract.');expect(done.stages.find((s) => s.id === 'mesh').observed).toMatch(/high-detail tier on Hunyuan3D/);});+ // A skipped stage is not an issue, but it is not a pass either. The 2026-10-11+ // rig_mesh proof run on a lantern read "every stage met its contract" while the+ // humanoid check had never run, which is exactly the overclaim receipts exist+ // to prevent.+ it('never says every stage met when a stage was not checked', () => {+ const r = startReceipt({ tool: 'rig_mesh', prompt: null, now: 1000 });+ addStage(r, inputStage({ allowed: true, hasImage: false, hasPrompt: true }));+ addStage(r, subjectGateStage({ givenMesh: true }));+ addStage(r, deliveryStage({ frame: { glb_url: 'https://x/a.glb', durable: true } }));+ const done = finishReceipt(r, { glbUrl: 'https://x/a.glb', now: 2000 });+ expect(done.outcome).toBe('delivered');+ expect(done.summary).not.toMatch(/every stage met/i);+ expect(done.summary).toBe('Delivered as expected. Every stage that ran met its contract. 1 skipped (Subject check).');+ });+it('names a quiet tier downgrade as recovered, with the cause', () => {const s = meshStage({ frame: { glb_url: 'https://x/a.glb', tier: 'standard', backend: 'trellis_selfhost' }, expectedTier: 'high', labelFor: engineLabel });expect(s.verdict).toBe('recovered');@@ -118,6 +133,17 @@ describe('run receipt core', () => {expect(briefStage({ kind: 'mesh', knownMark: true }).verdict).toBe('met');});+ it('states exactly why the director brief fell back, never a generic timeout', () => {+ const long = briefStage({ kind: 'mesh', directed: false, fallback: { reason: 'too_long', chars: 1245 } });+ expect(long.verdict).toBe('recovered');+ expect(long.cause).toMatch(/1245 characters/);+ expect(long.cause).toMatch(/1000/);+ expect(long.cause).not.toMatch(/in time/);+ expect(briefStage({ kind: 'mesh', directed: false, fallback: { reason: 'unfinished' } }).cause).toMatch(/mid-sentence|unfinished/);+ expect(briefStage({ kind: 'avatar', directed: false, fallback: { reason: 'no_reply' } }).cause).toMatch(/no reply/i);+ expect(briefStage({ kind: 'avatar', directed: false, fallback: { reason: 'too_long', chars: 1100 } }).cause).toMatch(/fixed brief/);+ });+it('turns away a non-humanoid avatar before spending GPU time, and says so', () => {const s = subjectGateStage({ nonHumanoid: true });expect(s.verdict).toBe('missed');