Show it a video you love. Get a new video in the same style. An AI crew (Claude Code or Codex) plans, builds and reviews it with you.
JavaScript 2d-animationai-agentsai-videoanimationclaude-codecodexmulti-agentstyle-transfervideo-generation
Merge main: port quality modes, parallel final fixes and safe job files onto the split server
許元豪ec670e9768f5
diff --cc app/server/cast.tsindex 0000000,36b9e27..78e7653mode 000000,100644..100644--- a/app/server/cast.ts+++ b/app/server/cast.ts@@@ -1,0 -1,120 +1,127 @@@+ // The cast gate: every character is reviewed and fixed before any shot review counts.+ // Several characters, each in its own file → one reviewer + fixer pair per character, all at once; then one line-up check.+ // One character, or everything in one file → the serial gate.+ import { existsSync } from 'node:fs';+ import { join } from 'node:path';+ import { blockerFree, reviewFix, sharedItems, type LoopEnd } from './review.ts';-import { L, chat, collectNeeds, dirOf, pause, pipe, readJSON, rounds, setStage } from './store.ts';++import { L, chat, collectNeeds, dirOf, pause, pipe, preset, readJSON, rounds, setStage } from './store.ts';+ import { fail, turn, type TurnResult } from './turn.ts';+ import type { CastCharProgress, Pipeline, Review } from '../shared/types.ts';+ import type { CastMember, Production, SharedItem } from './types.ts';++ type CastResult = 'error' | 'needs' | 'passed' | 'failed' | 'shared';+ const RESULT: Record<LoopEnd, CastResult> = { error: 'error', needs: 'needs', passed: 'passed', limit: 'failed', handoff: 'shared' };+ const STATE: Record<LoopEnd, CastCharProgress['state']> = { error: 'error', needs: 'needs_user', passed: 'passed', limit: 'failed', handoff: 'waiting_shared' };++ export async function castGate(id: string, prev: Pipeline): Promise<boolean> {+ const d = dirOf(id), prod = readJSON<Production>(join(d, 'build', 'production.json')) || {};+ const chars = (prod.characters || []).filter((c) => c && c.id && c.file && c.sheet);+ const files = new Set(chars.map((c) => c.file));+ const parallel = chars.length > 1 && files.size === chars.length && chars.every((c) => existsSync(join(d, c.sheet)));+ if (prev.cast?.pass) return true;+ if (!(prod.characters || []).length) { pipe(id, (p) => { p.cast = { round: 0, pass: true, state: 'passed' }; }); return true; } // no cast: nothing to review+ if (!parallel) return castSerial(id, prev);+ const setC = (cid: string, v: Partial<CastCharProgress>) => pipe(id, (p) => { const cast = p.cast!; cast.chars = cast.chars || {}; cast.chars[cid] = { ...(cast.chars[cid] ?? { state: 'queued', round: 0 }), ...v }; });+ const keep: Record<string, CastCharProgress> = prev.cast?.mode === 'parallel' ? prev.cast.chars || {} : {}; // resuming: characters that already passed stay passed+ pipe(id, (p) => { p.cast = { round: 0, pass: false, state: 'reviewing', mode: 'parallel', chars: Object.fromEntries(chars.map((c): [string, CastCharProgress] => [c.id, keep[c.id]?.state === 'passed' ? keep[c.id] : { state: 'queued', round: 0 }])) }; });+ chat(id, 'system', L(id, `角色關:${chars.length} 個角色各自由一組審查+修正同時進行`, `Characters: reviewing and fixing ${chars.length} character${chars.length > 1 ? 's' : ''} in parallel`));+ const shared: SharedItem[] = [];+ let broken = null as TurnResult | null; // the first agent turn that failed: reported as itself, not as "didn't pass review"+ const one = async (c: CastMember, recheck = false): Promise<CastResult> => {+ const reviewFile = join(d, 'out', 'check', 'cast', `review_${c.id}.json`);+ // resuming a character that stopped at its round limit: its last review is still current, so fix those issues first+ const reuse = !recheck && keep[c.id]?.state === 'failed' && existsSync(reviewFile); // a re-check after a shared fix always reviews afresh+ const { end, last } = await reviewFix<Review>({+ review: async (round) => {+ setC(c.id, { state: 'reviewing', round });+ if (!(round === 1 && reuse)) {+ const r = await turn(id, 'cast_qa', { round, character: c }, [`out/check/cast/review_${c.id}.json`], { session: 'fresh', who: `cast-qa-${c.id}` });+ if (!r.ok) { broken ??= r; return null; }+ }+ return readJSON<Review>(reviewFile) || {};+ },+ verdict: (rv) => (collectNeeds(id, rv.needs_user, `cast-qa-${c.id}`) ? 'needs' : blockerFree(rv) ? 'passed' : 'fix'),+ limit: () => rounds(id).castRounds + (reuse ? 1 : 0), // a reused review isn't a round: resuming still gets its fixes+ fix: async (rv, round) => {+ setC(c.id, { state: 'fixing' });+ const f = await turn(id, 'cast_fix', { issues: rv.issues || [], round, character: c, rigFiles: prod.rig_files || [] }, [c.sheet, `out/check/cast/fixes_${c.id}.json`], { session: `cast-${c.id}`, who: `cast-${c.id}` });+ if (!f.ok) { broken ??= f; return 'error'; }+ const sh = sharedItems(readJSON(join(d, 'out', 'check', 'cast', `fixes_${c.id}.json`)));+ if (!sh.length) return 'ok';+ shared.push(...sh.map((x) => ({ ...x, character: c.id })));+ return 'handoff';+ },+ });++ // fast mode: a character at its limit carries on (the issues stay listed; the user can upgrade the mode)++ if (end === 'limit' && !preset(id).pauseAtLimit) { setC(c.id, { state: 'passed', issues: (last?.issues || []).length, acceptedAtLimit: true }); return 'passed'; }+ setC(c.id, end === 'limit' ? { state: 'failed', issues: (last?.issues || []).length } : { state: STATE[end] });+ return RESULT[end];+ };+ let res: CastResult[] = await Promise.all(chars.map((c) => (keep[c.id]?.state === 'passed' ? 'passed' : one(c))));+ if (broken) return fail(id, 'producing', broken);+ if (res.includes('needs')) return pause(id);+ for (let k = 0; shared.length && k < rounds(id).castRounds; k++) { // skeleton changes: one director turn, then re-check who asked (and anyone it may affect)+ pipe(id, (p) => { p.cast!.state = 'fixing'; });+ const f = await turn(id, 'cast_fix', { issues: [...shared], round: 'shared', shared: true }, ['out/check/cast/sheet.jpg'], { who: 'director' });+ if (!f.ok) return fail(id, 'producing', f);+ shared.length = 0;+ res = await Promise.all(chars.map((c, i) => (res[i] === 'passed' || res[i] === 'shared' ? one(c, true) : res[i])));+ if (broken) return fail(id, 'producing', broken);+ if (res.includes('needs')) return pause(id);+ }+ if (res.some((x) => x !== 'passed')) {+ const names = chars.filter((c, i) => res[i] !== 'passed').map((c) => c.name || c.id), n = rounds(id).castRounds;+ pipe(id, (p) => { p.cast!.state = 'failed'; p.cast!.round = n; });+ chat(id, 'system', L(id, `角色關:${names.join('、')} 審了 ${n} 輪還沒通過,請你看設定圖決定`, `Characters: ${names.join(', ')} still not passing after ${n} rounds. Please check the character sheets and decide`));+ return pause(id);+ }+ // every character passed on its own → one line-up check across them, then the serial gate handles anything it finds+ pipe(id, (p) => { p.cast!.state = 'reviewing'; p.cast!.lineup = true; });+ const r = await turn(id, 'cast_qa', { round: 'lineup', lineup: true }, ['out/check/cast/review.json'], { session: 'fresh', who: 'cast-qa' });+ if (!r.ok) return fail(id, 'producing', r);+ const rv = readJSON<Review>(join(d, 'out', 'check', 'cast', 'review.json')) || {};+ if (collectNeeds(id, rv.needs_user, 'cast-qa')) return pause(id);+ if (blockerFree(rv)) { pipe(id, (p) => { p.cast!.pass = true; p.cast!.state = 'passed'; }); chat(id, 'system', L(id, '角色關通過(每個角色各自通過+並排檢查)', 'Characters passed (each one on its own, then side by side)')); return true; }+ return castSerial(id, { cast: { round: 0, pass: false } }, rv);+ }++ // The whole cast as one: one reviewer, the director fixes. firstReview: the line-up check already reviewed, go straight to fixing.+ async function castSerial(id: string, prev: Pipeline, firstReview?: Review | null): Promise<boolean> {+ const d = dirOf(id);+ if (prev.cast?.pass) return true;+ pipe(id, (p) => { p.cast = { round: 0, pass: false }; });+ let broken = null as TurnResult | null;+ const { end, round } = await reviewFix<Review>({+ review: async (round) => {+ pipe(id, (p) => { p.cast!.round = round; p.cast!.state = 'reviewing'; });+ if (firstReview) { const rv = firstReview; firstReview = null; return rv; }+ const r = await turn(id, 'cast_qa', { round }, ['out/check/cast/review.json'], { session: 'fresh', who: 'cast-qa' });+ if (!r.ok) { broken = r; return null; }+ return readJSON<Review>(join(d, 'out', 'check', 'cast', 'review.json')) || {};+ },+ verdict: (rv) => (collectNeeds(id, rv.needs_user, 'cast-qa') ? 'needs' : blockerFree(rv) ? 'passed' : 'fix'),+ limit: () => rounds(id).castRounds,+ fix: async (rv, round) => {+ pipe(id, (p) => { p.cast!.state = 'fixing'; });+ const f = await turn(id, 'cast_fix', { issues: rv.issues || [], round }, ['out/check/cast/sheet.jpg', 'out/check/cast/fixes.json'], { who: 'director' });+ if (!f.ok) { broken = f; return 'error'; }+ return 'ok';+ },+ });+ if (end === 'error') return fail(id, 'producing', broken!);+ if (end === 'needs') return pause(id);++ if (end === 'limit' && !preset(id).pauseAtLimit) {++ pipe(id, (p) => { p.cast!.pass = true; p.cast!.state = 'passed'; p.cast!.acceptedAtLimit = true; });++ chat(id, 'system', L(id, `快速模式:角色關審了 ${round} 輪,還有問題沒修,先繼續製作`, `Fast mode: characters had ${round} review rounds with issues left; carrying on`));++ return true;++ }+ if (end === 'limit') {+ pipe(id, (p) => { p.cast!.state = 'failed'; });+ chat(id, 'system', L(id, `角色關 ${round} 輪仍未通過,請你看角色設定圖決定`, `Characters still not passing after ${round} rounds. Please check the character sheets and decide`));+ setStage(id, 'needs_input');+ return false;+ }+ pipe(id, (p) => { p.cast!.pass = true; p.cast!.state = 'passed'; });+ chat(id, 'system', L(id, `角色關通過(第 ${round} 輪)`, `Characters passed (round ${round})`));+ return true;+ }diff --cc app/server/contract.test.tsindex 0000000,49e2e7f..8bfcb9emode 000000,100644..100644--- a/app/server/contract.test.ts+++ b/app/server/contract.test.ts@@@ -1,0 -1,44 +1,47 @@@+ // contract.ts: what an agent-written file must look like before the server acts on it.+ import { describe, test } from 'node:test';+ import assert from 'node:assert/strict';+ import { checkFile } from './contract.ts';++ const ok = (f: string, v: unknown) => assert.deepEqual(checkFile(f, JSON.stringify(v)), []);+ const bad = (f: string, v: unknown, re: RegExp) => { const p = checkFile(f, typeof v === 'string' ? v : JSON.stringify(v)); assert.ok(p.some((x) => re.test(x)), p.join('\n') || 'no problems'); };++ describe('checkFile', () => {++ test('a byte-order mark is not an error (PowerShell writes one)', () => {++ assert.deepEqual(checkFile('out/check/critique.json', '' + JSON.stringify({ pass: true, must_fix: [] })), []);++ });+ test('any .json must parse; files without a schema need nothing more', () => {+ bad('out/check/shots/C1.done.json', '{ oops', /not valid JSON/);+ ok('out/check/shots/C1.done.json', { anything: 1 });+ });+ test('plan.json: the CONTRACT.md example passes, wrong field types are named', () => {+ ok('plan.json', { version: 1, title: 'T', music: { file: 'inputs/song.mp3', section: { start_s: 100.84, end_s: 131.7 } }, characters: [{ id: 'zhai', name: '阿宅', design: '…' }], assets: [{ id: 'A1', status: 'to_fetch' }], required_inputs: [{ id: 'lyrics', kind: 'lyrics' }], shots: [{ id: 'S1', camera: { move: 'dolly_in' } }] });+ bad('plan.json', { characters: [{ name: 'no id' }] }, /plan\.json\.characters\[0\]\.id: missing/);+ bad('plan.json', { required_inputs: [{ id: 'x' }] }, /required_inputs\[0\]\.kind: missing/);+ bad('plan.json', [], /expected object, got array/);+ });+ test('production.json needs chunks with shots', () => {+ ok('build/production.json', { chunks: [{ id: 'C1', shots: ['S1', 'S2'] }], characters: [{ id: 'hero', file: 'build/hero.js', sheet: 'out/check/cast/sheet_hero.jpg' }] });+ bad('build/production.json', {}, /chunks: missing/);+ bad('build/production.json', { chunks: [] }, /at least 1/);+ bad('build/production.json', { chunks: [{ id: 'C1', shots: [] }] }, /chunks\[0\]\.shots: needs at least 1/);+ });+ test('reviews need a verdict; issues need their text', () => {+ ok('out/check/cast/review.json', { pass: true, issues: [] });+ ok('out/check/cast/review_hero.json', { issues: [{ issue: 'arm floats', severity: 'blocker' }] });+ ok('out/check/shots/S1.review.json', { shots: [{ id: 'S1', pass: false, issues: [{ time: 1.2, where: 'left', issue: 'seam' }] }] });+ bad('out/check/shots/S1.review.json', { summary: 'looks fine' }, /needs "pass", "issues" or "shots"/);+ bad('out/check/cast/review.json', { pass: 'yes' }, /pass: expected boolean/);+ bad('out/check/cast/review.json', { pass: false, issues: ['arm'] }, /issues\[0\]: expected object/);+ bad('out/check/cast/review.json', { pass: false, needs_user: [{ kind: 'lyrics' }] }, /needs_user\[0\]\.issue: missing/);+ });+ test('fixes files: a list or { fixes }', () => {+ ok('out/check/shots/C1.fixes.json', [{ shot: 'S1', change: 'x', status: 'fixed' }]);+ ok('out/check/cast/fixes_hero.json', { fixes: [{ status: 'shared', issue: 'rig neck' }] });+ bad('out/check/fixes.json', { done: true }, /expected array/);+ });+ test('critique: must_fix items need an issue (nulls are tolerated); display fields are free', () => {+ ok('out/check/critique.json', { pass: false, must_fix: [{ shot: 'S1', time: '3.2s', issue: 'seam' }, null], needs_user: [] });+ bad('out/check/critique.json', { must_fix: [{ shot: 'S1' }] }, /must_fix\[0\]/);+ });+ });diff --cc app/server/contract.tsindex 0000000,46957d0..322f0c5mode 000000,100644..100644--- a/app/server/contract.ts+++ b/app/server/contract.ts@@@ -1,0 -1,61 +1,61 @@@+ // The JSON files agents write and the server decides on (CONTRACT.md), checked when the turn that wrote them ends.+ // Only the fields the server reads are checked, and extra fields are fine. A broken file goes back to the agent that wrote it+ // (turn.ts) instead of being read as {} — an empty review would fail the gate, an empty plan would build nothing.+ type Check = (v: unknown, at: string) => string[];++ const kind = (v: unknown) => (v === null ? 'null' : Array.isArray(v) ? 'array' : typeof v);+ const is = (want: string): Check => (v, at) => (kind(v) === want ? [] : [`${at}: expected ${want}, got ${kind(v)}`]);+ const str = is('string'), num = is('number'), bool = is('boolean');+ const either = (...cs: Check[]): Check => (v, at) => { const all = cs.map((c) => c(v, at)); return all.some((p) => !p.length) ? [] : all[0]; };+ const arr = (item: Check, { min = 0 } = {}): Check => (v, at) => {+ if (!Array.isArray(v)) return is('array')(v, at);+ if (v.length < min) return [`${at}: needs at least ${min} item${min > 1 ? 's' : ''}`];+ return v.flatMap((x, i) => item(x, `${at}[${i}]`));+ };+ const obj = (fields: Record<string, Check>, required: string[] = []): Check => (v, at) => {+ if (kind(v) !== 'object') return is('object')(v, at);+ const o = v as Record<string, unknown>;+ return [+ ...required.filter((k) => o[k] === undefined).map((k) => `${at}.${k}: missing`),+ ...Object.entries(fields).flatMap(([k, c]) => (o[k] === undefined ? [] : c(o[k], `${at}.${k}`))),+ ];+ };+ const nul: Check = (v, at) => (v === null ? [] : [`${at}: expected null`]);++ const need = obj({ issue: str }, ['issue']);+ const issue = obj({ issue: str, severity: str }, ['issue']);+ const review: Check = (v, at) => {+ const p = obj({ pass: bool, issues: arr(issue), needs_user: arr(need), shots: arr(obj({ id: str, pass: bool, issues: arr(issue) }, ['id'])) })(v, at);+ if (p.length) return p;+ const o = v as Record<string, unknown>; // a verdict is required: an empty review would read as "failed, nothing to fix"+ return typeof o.pass === 'boolean' || Array.isArray(o.issues) || Array.isArray(o.shots) ? [] : [`${at}: needs "pass", "issues" or "shots"`];+ };+ const fix = obj({ status: str, issue: str });+ const fixes = either(arr(fix), obj({ fixes: arr(fix) }, ['fixes']));++ const SCHEMAS: [RegExp, Check][] = [+ [/(^|\/)analysis\/route\.json$/, obj({ engine: str, style: str })],+ [/(^|\/)plan\.json$/, obj({+ title: str, version: either(num, str),+ characters: arr(obj({ id: str, name: str, file: str }, ['id'])),+ assets: arr(obj({ id: str, status: str })),+ required_inputs: arr(obj({ id: str, kind: str, label: str, file: str, match: str }, ['id', 'kind'])),+ music: obj({ file: str }),+ })],+ [/(^|\/)build\/production\.json$/, obj({+ chunks: arr(obj({ id: str, shots: arr(str, { min: 1 }) }, ['id', 'shots']), { min: 1 }),+ characters: arr(obj({ id: str, name: str, file: str, sheet: str }, ['id'])),+ rig_files: arr(str),+ }, ['chunks'])],+ [/(^|\/)out\/check\/critique\.json$/, obj({ must_fix: arr(either(nul, obj({ issue: str }, ['issue']))), needs_user: arr(need) })],+ [/(^|\/)(review(_[^/]+)?|[^/]+\.review)\.json$/, review],+ [/(^|\/)(fixes(_[^/]+)?|[^/]+\.fixes)\.json$/, fixes],+ ];++ // Problems with one agent-written file (project-relative path), [] when it's fine. Any .json must at least parse.+ export function checkFile(rel: string, text: string): string[] {+ let v: unknown;- try { v = JSON.parse(text); } catch (e) { return [`${rel}: not valid JSON (${(e as Error).message})`]; }++ try { v = JSON.parse(text.charCodeAt(0) === 0xfeff ? text.slice(1) : text); } catch (e) { return [`${rel}: not valid JSON (${(e as Error).message})`]; } // a byte-order mark (PowerShell writes one) is fine+ const s = SCHEMAS.find(([re]) => re.test(rel));+ return s ? s[1](v, rel) : [];+ }diff --cc app/server/final.tsindex 0000000,e6b535a..ad06817mode 000000,100644..100644--- a/app/server/final.ts+++ b/app/server/final.ts@@@ -1,0 -1,50 +1,93 @@@+ // The final panel: a fresh critic looks only at what spans segments (seams, continuity, pacing, captions, the climaxes-// against the reference) and verifies every earlier fix ⇄ the director revises. finalRounds automatic revises, a few more-// while the list is short and shrinking; anything left after that is the user's call.++// against the reference) and verifies every earlier fix ⇄ the builders and the director revise. finalRounds automatic++// revises, a few more while the list keeps shrinking (by quality mode); anything left after that is the user's call++// (or, in fast mode, listed with the delivered film).+ import { join } from 'node:path';+ import { reviewFix } from './review.ts';-import { L, chat, collectNeeds, dirOf, load, now, pipe, readJSON, rounds, setStage, update } from './store.ts';-import { step } from './turn.ts';-import type { Critique } from './types.ts';++import { L, chat, collectNeeds, dirOf, load, now, pipe, preset, readJSON, rounds, setStage, update } from './store.ts';++import { fail, step, turn } from './turn.ts';++import type { Chunk, Critique, Production, ShotEntry } from './types.ts';++ type MustFix = NonNullable<Critique['must_fix']>;++type Item = MustFix[number];++++// A must-fix item is a segment's when every shot it names is in that one segment.++function splitBySegment(id: string, must: MustFix): { local: Map<Chunk, Item[]>; global: Item[] } {++ const chunks = readJSON<Production>(join(dirOf(id), 'build', 'production.json'))?.chunks || [];++ const local = new Map<Chunk, Item[]>(), global: Item[] = [];++ for (const m of must) {++ const shots = [...new Set(String(m.shot || '').match(/S\d+/g) || [])];++ const owners = new Set(shots.map((s) => chunks.find((c) => c.shots.includes(s))));++ const [owner] = [...owners];++ if (shots.length && owners.size === 1 && owner) local.set(owner, [...(local.get(owner) || []), m]);++ else global.push(m);++ }++ return { local, global };++}++++// Segment items go back to the builders who made them, all at once (their conversations still hold how each shot was++// made). Real runs: the director fixing 9–12 items alone was the longest step after approval (14–17 min), and its edits++// to shots it had not built brought back the very defect being fixed in another shot. Returns the fixes files for the++// director's render and evidence, or null when a builder turn failed (the job is stopped with the reason).++async function fixSegments(id: string, local: Map<Chunk, Item[]>, round: number): Promise<string[] | null> {++ if (!local.size) return [];++ const ids = [...local.keys()].map((c) => c.id);++ chat(id, 'system', L(id, `${ids.join('、')} 的必修交回各段的製作 agent 同時修,全片性的交給導演`, `Segment items go back to their builders (${ids.join(', ')}) in parallel; film-wide ones to the director`));++ const results = await Promise.all([...local.entries()].map(async ([c, items]) => {++ const bad: ShotEntry[] = [...new Set(items.flatMap((m) => String(m.shot).match(/S\d+/g) || []))]++ .map((sid) => ({ id: sid, issues: items.filter((m) => String(m.shot).includes(sid)).map((m) => ({ issue: `${m.time != null ? `[${m.time}s] ` : ''}${m.issue}`, fix: m.fix })) }));++ const r = await turn(id, 'fix_chunk', { chunk: c, bad, round: `final-${round}`, final: true }, [`out/check/shots/${c.id}.fixes.json`], { session: `builder-${c.id}`, who: `builder-${c.id}` });++ return { c, r };++ }));++ const failed = results.find((x) => !x.r.ok);++ if (failed) { fail(id, 'revising', failed.r); return null; }++ return results.map((x) => `out/check/shots/${x.c.id}.fixes.json`);++}++ export async function finalPanel(id: string) {+ const d = dirOf(id);+ let needs = 0, total = 0, prevMust = Infinity, converging = false;+ const { end, last } = await reviewFix<MustFix>({+ review: async (round) => {+ pipe(id, (p) => { p.phase = 'final'; p.final = { round }; });+ if (!(await step(id, 'critiquing', 'critique', { round }, ['out/check/critique.json'], null, { session: 'fresh', who: 'critic' }))) return null;+ const c = readJSON<Critique>(join(d, 'out', 'check', 'critique.json')) || {};+ const must = (c.must_fix || []).filter(Boolean);+ // a climax that loses to the reference never passes, even if the critic forgot to list a fix for it+ for (const pk of (c.peaks || []).filter((x) => x?.verdict === 'ref_better'))+ if (!must.some((m) => m.issue.includes(pk.id))) must.push({ shot: pk.id, time: pk.ours?.[0], issue: `高潮 ${pk.id} 輸給參考片:${pk.why || ''}`, fix: `照 ${pk.strip || '高潮對照圖'} 逐格補上參考片爆點的手法,直到不輸參考片` });+ total = (load(id).critiqueRounds || 0) + 1; // every critic pass since approval (retries and user revisions included)+ update(id, (j) => { j.critiqueRounds = total; j.lastCritique = { pass: !must.length, must: must.length, at: now() }; });+ needs = collectNeeds(id, c.needs_user, 'critic'); // never sent to the director: they wait for the user- // Past the limit, keep going while the list is short (≤ 2) and still shrinking, up to 3 extra rounds: a real run went- // 8 → 3 → 2 → 1 and stopped with its last, most visible defect unfixed. A list that stops shrinking stops the loop.- converging = must.length <= 2 && must.length < prevMust && round <= rounds(id).finalRounds + 3;++ // Past the limit, keep going while the list is clearly shrinking — short (≤ 3) or at most half of the last round's —++ // for a few extra rounds (by quality mode). Real runs went 8 → 3 → 2 → 1 and 9 → 3 and stopped with visible defects++ // (a character teleporting between two frames) unfixed. A list that stops shrinking stops the loop.++ const shrinking = must.length < prevMust && (must.length <= 3 || must.length <= prevMust / 2);++ converging = shrinking && round <= rounds(id).finalRounds + preset(id).converge;+ prevMust = must.length;+ return must;+ },+ verdict: (must) => (must.length ? 'fix' : 'passed'),+ limit: () => (converging ? Infinity : rounds(id).finalRounds + 1), // n automatic revises → up to n + 1 reviews+ fix: async (must, round) => {- const msg = must.map((m, i) => `${i + 1}. [${m.shot || '全片'}${m.time != null ? ' ' + m.time + 's' : ''}] ${m.issue}${m.fix ? ' → 建議:' + m.fix : ''}`).join('\n');- chat(id, 'system', L(id, `評審第 ${total} 輪:${must.length} 項必修,交回導演(每項要附修改前後對照)`, `Final review round ${total}: ${must.length} must-fix item${must.length > 1 ? 's' : ''}, sent back to the director (each fix needs before/after proof)`));- return (await step(id, 'revising', 'revise', { message: msg, round }, ['out/video.mp4', 'out/check/fixes.json'])) ? 'ok' : 'error';++ chat(id, 'system', L(id, `評審第 ${total} 輪:${must.length} 項必修(每項要附修改前後對照)`, `Final review round ${total}: ${must.length} must-fix item${must.length > 1 ? 's' : ''} (each fix needs before/after proof)`));++ setStage(id, 'revising', { error: null, failed: null });++ const { local, global } = splitBySegment(id, must);++ const builderFixes = await fixSegments(id, local, round);++ if (builderFixes === null) return 'error';++ const msg = global.map((m, i) => `${i + 1}. [${m.shot || '全片'}${m.time != null ? ' ' + m.time + 's' : ''}] ${m.issue}${m.fix ? ' → 建議:' + m.fix : ''}`).join('\n');++ return (await step(id, 'revising', 'revise', { message: msg, round, builderFixes }, ['out/video.mp4', 'out/check/fixes.json'])) ? 'ok' : 'error';+ },+ });- if (end === 'error') return; // step() already stopped the job with the reason++ if (end === 'error') return; // step() / fixSegments() already stopped the job with the reason+ if (end === 'passed') {+ chat(id, 'system', needs ? L(id, '評審:導演能修的都過了,剩下需要你提供的項目', 'Final review: everything the director can fix is done. What is left needs your input') : L(id, `評審通過(第 ${total} 輪)`, `Final review passed (round ${total})`));+ setStage(id, needs ? 'needs_input' : 'done');+ return;+ }+ const n = last!.length;- chat(id, 'system', L(id, `評審仍有 ${n} 項必修,已達自動修改上限,請你決定`, `The final review still has ${n} must-fix item${n > 1 ? 's' : ''} and the automatic fix limit is reached. Please decide`));++ chat(id, 'system', preset(id).pauseAtLimit++ ? L(id, `評審仍有 ${n} 項必修,已達自動修改上限,請你決定`, `The final review still has ${n} must-fix item${n > 1 ? 's' : ''} and the automatic fix limit is reached. Please decide`)++ : L(id, `快速模式交件:評審還列了 ${n} 項可以再修(在評審報告裡)。想修掉就把品質升級,會從這支片接著修。`, `Fast mode delivered: the final review lists ${n} more item${n > 1 ? 's' : ''} to fix (see the review). Upgrade the quality to fix them, starting from this film.`));+ setStage(id, 'done');+ }diff --cc app/server/index.tsindex 72166e4,fb2673a..9f52501--- a/app/server/index.ts+++ b/app/server/index.ts@@@ -40,9 -45,8 +45,9 @@@ app.post('/api/projects', upload.fieldslet settings;try { settings = Object.fromEntries(Object.entries(J.cleanRounds(req.body)).filter(([, v]) => v != null)); }catch (e) { for (const f of Object.values(files || {}).flat()) try { unlinkSync(f.path); } catch {} return res.status(400).json({ error: (e as Error).message }); }+ const quality = ['fast', 'standard', 'fine'].includes(req.body.quality) ? req.body.quality : undefined; // undefined → DEFAULT_QUALITYconst id = slug();- const job = J.createJob({ id, title: (title || brief.split('\n')[0] || '未命名').slice(0, 40), agent, brief, lang, settings, quality,- const job = J.createJob({ id, title: J.projectTitle(title, brief, lang), agent, brief, lang, settings,++ const job = J.createJob({ id, title: J.projectTitle(title, brief, lang), agent, brief, lang, settings, quality,reference: ref ? { type: 'file', src: 'inputs/reference' + (extname(ref.originalname) || '.mp4') } : { type: 'url', src: url.trim() } });if (ref) renameSync(ref.path, join(J.dirOf(id), job.reference.src));for (const f of files?.inputs || []) renameSync(f.path, join(J.dirOf(id), 'inputs', fileName(f)));diff --cc app/server/jobs.tsindex 3666418,3672614..fdb81ef--- a/app/server/jobs.ts+++ b/app/server/jobs.ts@@@ -1,146 -1,91 +1,117 @@@// Jobs: one folder per video under projects/<id>/, job.json is the state. The server owns the stage machine; agents only// write the files in CONTRACT.md. A step advances only when its output files exist.//- // new → analyzing → styling → planning → plan_review ⇄ replanning- // → [approve: required inputs must be provided or waived]- // → producing: setup (director) → CAST GATE (cast_qa ⇄ cast_fix) → SHOT LINE (N builders in parallel; every chunk- // is reviewed by a fresh shot_qa as soon as it is built ⇄ fix_chunk) → assemble (director)- // → critiquing: final panel (fresh critic: continuity/pacing/seams, verifies earlier fixes) ⇄ revising+ // new → analyzing → styling → planning → plan_review ⇄ replanning preprod.ts+ // → [approve: required inputs must be provided or waived] inputs.ts+ // → producing: setup → cast gate ∥ shot line → assemble production.ts, cast.ts+ // → critiquing: final panel ⇄ revising final.ts// → done (needs_user items never trigger a revise: they pause the job and ask the user)- // Quality is checked where defects are born (each character, each chunk), not only at the end.- import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, statSync, statfsSync, cpSync, renameSync, rmSync } from 'node:fs';- import { join, relative, resolve } from 'node:path';- import { spawn, type ChildProcess } from 'node:child_process';- import { EventEmitter } from 'node:events';- import { runAgent, type AgentResult } from './agents/index.ts';- import { checkOutputs, parseJSON, repairPrompt } from './outputs.ts';- import { prompts as bootPrompts } from './prompts.ts';+ //+ // This file is the server's API over all of that: the user's actions, each one run as the project's single flow+ // (runner.ts), plus the project list and snapshot. Every review/fix gate shares one loop (review.ts); one agent turn is+ // turn.ts; job.json and helpers are store.ts.+ import { appendFileSync, existsSync, mkdirSync, writeFileSync, readdirSync, cpSync } from 'node:fs';+ import { extname, join, relative } from 'node:path';+ import { finalPanel } from './final.ts';+ import { openInputs, alignIfReadyWithNotice, requiredInputs } from './inputs.ts';+ import { flushNotes, fromAnalysis, fromStyle, preProduction } from './preprod.ts';+ import { production } from './production.ts';+ import { stopPrerenders } from './prerender.ts';+ import * as runner from './runner.ts';+ import { active, run } from './runner.ts';-import { CONFIG, L, PROJECTS, ROOT, ROUND_RANGE, chat, cleanRounds, diskWarning, dirOf, jpath, listFiles, load, now, oneOf, pipe, readJSON, readText, recentLog, rounds, save, update } from './store.ts';++import { L, PROJECTS, ROOT, ROUND_RANGE, chat, cleanRounds, diskWarning, dirOf, jpath, listFiles, load, now, oneOf, pipe, presetRounds, qualityOf, readJSON, readText, recentLog, rounds, save, update } from './store.ts';+ import { step } from './turn.ts';-import { ROUND_KEYS } from '../shared/types.ts';-import type { AgentKind, ChatMessage, EngineSnapshot, Job, Lang, Plan, ProjectSummary, Reference, Review, RoundKey, Rounds, Snapshot, Stage } from '../shared/types.ts';+import { DEFAULT_QUALITY, QUALITIES, ROUND_KEYS } from '../shared/types.ts';- import type { AgentKind, CastCharProgress, ChatMessage, ChunkProgress, Config, EngineSnapshot, Job, Lang, LogEntry, LogEvent, Need, NeedRequest, Pipeline, Plan, ProjectSummary, Quality, QualityPreset, Reference, RequiredInput, Review, RoundKey, Rounds, Snapshot, Stage } from '../shared/types.ts';- import type { CastMember, Chunk, ChunkReview, Critique, Phase, Production, Prompts, SharedItem, ShotEntry, StepVars } from './types.ts';++import type { AgentKind, ChatMessage, EngineSnapshot, Job, Lang, Plan, ProjectSummary, Quality, Reference, Review, RoundKey, Rounds, Snapshot, Stage } from '../shared/types.ts';+ import type { Production } from './types.ts';+export { ROUND_KEYS };- // prompts.ts is re-imported when it changes, so prompt fixes reach the next agent turn without restarting running jobs- let promptCache: { m: number; p: Prompts } = { m: 0, p: bootPrompts };- async function livePrompts() {- const f = join(import.meta.dirname, 'prompts.ts'), m = statSync(f).mtimeMs;- if (m !== promptCache.m) { try { promptCache = { m, p: (await import(`./prompts.ts?v=${m}`)).prompts }; } catch (e) { console.error('prompts reload failed', e); } }- return promptCache.p;-export { CANCELLED, CONFIG, PROJECTS, ROOT, ROUND_RANGE, bus, cleanRounds, dirOf, load, rounds, touch, type BusEvent } from './store.ts';++export { CANCELLED, CONFIG, PROJECTS, ROOT, ROUND_RANGE, bus, cleanRounds, dirOf, load, preset, qualityOf, rounds, touch, type BusEvent } from './store.ts';+ export { alignIfReady, alignIfReadyWithNotice, openInputs, provideInput, saveLyrics, unwaive, waive, type LyricsResult } from './inputs.ts';+ export { stopAll } from './runner.ts';+ export const busy = active; // a flow is running for this project (runner.ts allows one at a time)+ // Stop the project's flow and every process it started; background renders queued behind them don't start either.+ export function cancel(id: string) { runner.cancel(id); stopPrerenders(id); }++ // Uploaded references only need to look like a video (by extension); URL references are left to yt-dlp.+ export const REFERENCE_EXTS = ['.mp4', '.mov', '.mkv', '.webm', '.avi', '.m4v', '.mpg', '.mpeg'];+ export const isVideoName = (name: string) => REFERENCE_EXTS.includes(extname(name).toLowerCase());++ // ---------- projects ----------++// Projects whose job.json can be read; a broken one (truncated by a full disk before writes were atomic) is reported++// and skipped instead of stopping the server from starting.++function readableJobs(): string[] {++ return (existsSync(PROJECTS) ? readdirSync(PROJECTS) : []).filter((d) => {++ if (!existsSync(jpath(d))) return false;++ try { load(d); return true; } catch (e) { console.error(`skipping project ${d}: job.json unreadable (${(e as Error).message})`); return false; }++ });++}+ export function listJobs(): ProjectSummary[] {- if (!existsSync(PROJECTS)) return [];- return readdirSync(PROJECTS).filter((d) => existsSync(jpath(d))).map((d) => { const j = load(d); return { id: j.id, title: readJSON<Plan>(join(dirOf(d), 'plan.json'))?.title || j.title, stage: j.stage, agent: j.agent, updatedAt: j.updatedAt, needs: (j.needs || []).length, thumb: existsSync(join(dirOf(d), 'out', 'check', 'style_1.jpg')) ? 'out/check/style_1.jpg' : existsSync(join(dirOf(d), 'analysis', 'sheet_1fps.jpg')) ? 'analysis/sheet_1fps.jpg' : null }; })++ return readableJobs().map((d) => { const j = load(d); return { id: j.id, title: readJSON<Plan>(join(dirOf(d), 'plan.json'))?.title || j.title, stage: j.stage, agent: j.agent, updatedAt: j.updatedAt, needs: (j.needs || []).length, thumb: existsSync(join(dirOf(d), 'out', 'check', 'style_1.jpg')) ? 'out/check/style_1.jpg' : existsSync(join(dirOf(d), 'analysis', 'sheet_1fps.jpg')) ? 'analysis/sheet_1fps.jpg' : null }; })+ .sort((a, b) => (b.updatedAt || '').localeCompare(a.updatedAt || ''));}- export const ROOT = join(import.meta.dirname, '..', '..');- export const PROJECTS = process.env.REELMIMIC_PROJECTS ? resolve(process.env.REELMIMIC_PROJECTS) : join(ROOT, 'projects'); // override: tests, a second checkout- const SCRIPTS = join(ROOT, '.claude', 'skills', 'video-clone', 'scripts');- const PY = process.env.PYTHON || 'python';- const noPython = (e: Error) => `${PY} could not be started (${e.message}). Install Python 3.10+, or set PYTHON=/path/to/python`;- // A review passes when nothing it lists is a blocker (polish items are handed on, they never hold the line)- const passed = (rv: Review) => { const L = rv.issues || []; return L.length && L.every((x) => x.severity) ? !L.some((x) => x.severity !== 'polish') : !!rv.pass; };- const shotPassed = (s: ShotEntry) => { const L = s.issues || []; return L.length && L.every((x) => x.severity) ? !L.some((x) => x.severity !== 'polish') : !!s.pass; };+ // Everything the UI needs for one project, read straight from the contract files.+ export function snapshot(id: string): Snapshot {+ const d = dirOf(id), job = { ...load(id), log: [...recentLog(id)] }, list = (sub: string, re: RegExp) => listFiles(id, sub, re);+ const plan = readJSON<Plan>(join(d, 'plan.json'));+ return {+ job, brief: readText(join(d, 'brief.md')),+ report: readJSON(join(d, 'analysis', 'report.json')), styleMd: readText(join(d, 'analysis', 'STYLE.md')), route: readJSON(join(d, 'analysis', 'route.json')),+ plan, storyboard: readText(join(d, 'STORYBOARD.md')), assetsMd: readText(join(d, 'assets', 'ASSETS.md')),+ checks: list('out/check', /\.(jpg|png)$/i).slice(0, 24), video: existsSync(join(d, 'out', 'video.mp4')) ? 'out/video.mp4' : null,+ critique: readJSON(join(d, 'out', 'check', 'critique.json')),++ styleDistance: readJSON(join(d, 'out', 'check', 'style_distance.json')),+ cast: { sheets: list('out/check/cast', /sheet[^/]*\.(jpg|png)$/i).slice(0, 8), review: readJSON<Review>(join(d, 'out', 'check', 'cast', 'review.json')) },+ shots: list('out/check/shots', /_sheet\.(jpg|png)$/i).slice(0, 60),+ production: readJSON(join(d, 'build', 'production.json')),+ lyrics: readJSON(join(d, 'analysis', 'lyrics', 'subs.json')),+ requiredInputs: requiredInputs(id, plan, job),- rounds: { values: rounds(id), defaults: Object.fromEntries(ROUND_KEYS.map((k) => [k, CONFIG[k]])) as Rounds, ...ROUND_RANGE },++ rounds: { values: rounds(id), defaults: presetRounds(qualityOf(job)), ...ROUND_RANGE },++ quality: qualityOf(job),+ inputs: list('inputs', /./),+ };+ }- const FINE: Rounds = {- castRounds: +(process.env.CAST_ROUNDS || 3), // cast gate: review/fix rounds before asking the user- chunkRounds: +(process.env.CHUNK_ROUNDS || 3), // shot line: review/fix rounds per chunk- finalRounds: +(process.env.FINAL_ROUNDS || 2), // final panel: automatic revise rounds- };- export const CONFIG: Config = {- ...FINE, // the 'fine' line (projects made before modes existed)- // Quality modes (shared/types.ts). The prompts change with the mode too: what blocks, and where every frame is checked.- presets: {- // a round is one review: 2 = review, fix, review again- fast: { castRounds: 2, chunkRounds: 2, finalRounds: 1, converge: 0, pauseAtLimit: false },- standard: { castRounds: 2, chunkRounds: 3, finalRounds: 2, converge: 1, pauseAtLimit: true },- fine: { ...FINE, converge: 3, pauseAtLimit: true },- },- builders: +(process.env.BUILDERS || 6), // parallel shot builders per project (12 cores / 32 GB measured)- maxAgentsGlobal: +(process.env.MAX_AGENTS || 12), // all projects together (CLI rate limits, CPU/GPU for renders)- maxReviews: +(process.env.MAX_REVIEWS || 4), // shot reviews at once per project: each one opens Chrome to grab frames;- // 13 at once meant 80–200 Chrome processes and screenshot timeouts- // Build shots while the cast gate is still running? Faster, but on real runs character files changed under the- // builders and every segment needed an extra round (0nczg, 4f1jx, 1qo20, 7e45u). Off by default: quality first.- overlapCast: process.env.OVERLAP_CAST === '1',- };+ // Project name: the given title, else the brief's first non-empty line, else a placeholder in the project's language.+ // Cut by characters, not UTF-16 units, so an emoji at the limit isn't split in half.+ export function projectTitle(title: string | undefined, brief: string, lang: Lang) {+ const name = (title || '').trim() || brief.split('\n').map((l) => l.trim()).find(Boolean) || (lang === 'en' ? 'Untitled' : '未命名');+ return Array.from(name).slice(0, 40).join('');+ }- // Review/fix round limits: CONFIG holds the defaults; a project can set its own (job.settings), read at every check so a- // change applies from the next round on. When a limit is reached the job pauses for the user instead of looping.- export const ROUND_RANGE = { min: 1, max: 10 };- export const qualityOf = (j: Job): Quality => (QUALITIES.includes(j.quality as Quality) ? j.quality! : 'fine');- export const preset = (id: string): QualityPreset => CONFIG.presets[qualityOf(load(id))];- const presetRounds = (q: Quality) => Object.fromEntries(ROUND_KEYS.map((k) => [k, CONFIG.presets[q][k]])) as Rounds;- export function rounds(id: string): Rounds { const j = load(id), s = j.settings || {}, p = CONFIG.presets[qualityOf(j)]; return Object.fromEntries(ROUND_KEYS.map((k) => [k, s[k] ?? p[k]])) as Rounds; }- // Validates { castRounds?, chunkRounds?, finalRounds? } (whole numbers 1–10; '' / null = back to the default). Throws on bad input.- export function cleanRounds(input: Record<string, unknown> = {}) {- const out: Partial<Record<RoundKey, number | null>> = {};- for (const k of ROUND_KEYS) {- if (!(k in input)) continue;- const raw = input[k];- if (raw === '' || raw == null) { out[k] = null; continue; }- const v = Number(raw);- if (!Number.isInteger(v) || v < ROUND_RANGE.min || v > ROUND_RANGE.max) throw new Error(`${k} must be a whole number from ${ROUND_RANGE.min} to ${ROUND_RANGE.max}`);- out[k] = v;- }- return out;-export function createJob({ id, title, agent, brief, reference, lang = 'zh-TW', settings = {} }: { id: string; title: string; agent: AgentKind; brief: string; reference: Reference; lang?: Lang; settings?: Partial<Rounds> }) {++export function createJob({ id, title, agent, brief, reference, lang = 'zh-TW', settings = {}, quality = DEFAULT_QUALITY }: { id: string; title: string; agent: AgentKind; brief: string; reference: Reference; lang?: Lang; settings?: Partial<Rounds>; quality?: Quality }) {+ const d = dirOf(id); mkdirSync(join(d, 'inputs'), { recursive: true }); mkdirSync(join(d, 'analysis'), { recursive: true });+ writeFileSync(join(d, 'brief.md'), brief || '');- const job: Job = { id, title, agent, lang, reference, settings, stage: 'new', sessionId: null, sessions: {}, createdAt: now(), chat: [], log: [], needs: [], waived: [], pipeline: {} };++ const job: Job = { id, title, agent, lang, reference, settings, quality, stage: 'new', sessionId: null, sessions: {}, createdAt: now(), chat: [], log: [], needs: [], waived: [], pipeline: {} };+ save(job);+ return job;}+export function setRounds(id: string, input: Record<string, unknown>) {const clean = cleanRounds(input);update(id, (x) => { const s = { ...(x.settings || {}) }; for (const [k, v] of Object.entries(clean) as [RoundKey, number | null][]) { if (v == null) delete s[k]; else s[k] = v; } x.settings = s; });return snapshot(id);}+// Change the quality mode. Mid-production it applies from the next check (rounds and prompts read it every turn).+// A finished film moved to a stricter mode goes back to the final review under the new bar, fixing from this film.+const RANK: Record<Quality, number> = { fast: 0, standard: 1, fine: 2 };- export const QUALITY_NAME: Record<Quality, [string, string]> = { fast: ['快速', 'Fast'], standard: ['標準', 'Standard'], fine: ['精緻', 'Fine'] };++const QUALITY_NAME: Record<Quality, [string, string]> = { fast: ['快速', 'Fast'], standard: ['標準', 'Standard'], fine: ['精緻', 'Fine'] };+export function setQuality(id: string, q: unknown): { upgrade: boolean } {+ if (!QUALITIES.includes(q as Quality)) throw new Error(`quality must be one of ${QUALITIES.join(', ')}`);+ const j = load(id), from = qualityOf(j), to = q as Quality;+ if (from === to) return { upgrade: false };+ const upgrade = RANK[to] > RANK[from] && j.stage === 'done' && !busy(id) && existsSync(join(dirOf(id), 'out', 'video.mp4'));+ const [zh, en] = QUALITY_NAME[to];+ update(id, (x) => { x.quality = to; });+ chat(id, 'system', upgrade+ ? L(id, `品質升級為「${zh}」:用新的標準重新評審,從這支片接著修。`, `Quality upgraded to ${en}: the film goes back to the final review under the new bar and is fixed from here.`)+ : L(id, `品質改為「${zh}」,從下一次檢查開始生效。`, `Quality set to ${en}; it applies from the next check.`));+ return { upgrade };+}+- export type BusEvent = { type: 'job'; job: Job } | { type: 'log'; ev: LogEvent };- export const bus = new EventEmitter<{ job: [id: string, ev: BusEvent] }>(); bus.setMaxListeners(100);- const running = new Map<string, Set<AbortController>>();- // Stop every agent this server started (on shutdown), so none keeps working unseen after a restart.- export function stopAll() { for (const set of running.values()) for (const ac of set) ac.abort(); for (const set of prerenderProcs.values()) for (const p of set) p.kill(); }-- const now = () => new Date().toISOString();- export const dirOf = (id: string) => join(PROJECTS, id);- const jpath = (id: string) => join(dirOf(id), 'job.json');- // System messages in the project's language (Simplified Chinese is converted from the Chinese text by the UI).- const L = (id: string, zh: string, en: string) => (load(id).lang === 'en' ? en : zh);- export function load(id: string): Job { return JSON.parse(readFileSync(jpath(id), 'utf8')); }- // Atomic: write a temp file, then rename over job.json. A full disk once truncated job.json to 0 bytes mid-write and the- // project could no longer be opened; now a failed write leaves the previous job.json intact.- function save(job: Job) {- job.updatedAt = now();- const f = jpath(job.id), tmp = `${f}.${process.pid}.tmp`;- try { writeFileSync(tmp, JSON.stringify(job, null, 1)); renameSync(tmp, f); }- catch (e) { try { rmSync(tmp, { force: true }); } catch {} throw e; }- bus.emit('job', job.id, { type: 'job', job }); return job;- }- function update(id: string, fn: (j: Job) => void) { const j = load(id); fn(j); return save(j); }- function log(id: string, ev: LogEntry) {- const e = { ts: now(), ...ev }; bus.emit('job', id, { type: 'log', ev: e });- try { update(id, (j) => { j.log = [...(j.log || []).slice(-600), e]; }); } catch {}- // the full, uncapped record lives in logs/events.jsonl (job.json keeps only the latest 600 for the UI)- try { mkdirSync(join(dirOf(id), 'logs'), { recursive: true }); appendFileSync(join(dirOf(id), 'logs', 'events.jsonl'), JSON.stringify(e) + '\n'); } catch {}- }-// On startup nothing is running, so a job still marked as working was cut off by a restart: say so instead of pretending.- // Projects whose job.json can be read; a broken one (e.g. truncated by a full disk before writes were atomic) is- // reported and skipped instead of stopping the server from starting.- function readableJobs(): string[] {- return (existsSync(PROJECTS) ? readdirSync(PROJECTS) : []).filter((d) => {- if (!existsSync(jpath(d))) return false;- try { load(d); return true; } catch (e) { console.error(`skipping project ${d}: job.json unreadable (${(e as Error).message})`); return false; }- });- }-export function recoverOrphans(): string[] {const cut: string[] = [];const WORK = ['analyzing', 'styling', 'planning', 'replanning', 'producing', 'revising', 'critiquing'];diff --cc app/server/pipeline.test.tsindex 13b7eb7,c95834e..3a3f63d--- a/app/server/pipeline.test.ts+++ b/app/server/pipeline.test.ts@@@ -20,12 -20,16 +20,16 @@@ interface ScenarioshotPass: (shot: string, round: number) => boolean;sharedFix?: (chunk: string, call: number) => boolean; // the builder reports a shared-file problem insteadcastShared?: (char: string, call: number) => boolean;- critique: (round: number) => { must?: number; needs?: number; lostPeak?: boolean };+ critique: (round: number) => { must?: number; needs?: number; lostPeak?: boolean; items?: { shot: string; issue: string }[] };buildDelayMs?: number; // let the per-shot watcher (every 4 s) pick shots upprerender?: string; // production.json prerender command- badJson?: (step: string, call: number) => boolean; // the agent writes broken JSON for this step (LLMs do: trailing commas, comments)- repairFails?: boolean; // … and its repair turn does not fix it+ blockers?: number; // blocker issues in a failing shot review (default 1)+ crash?: (step: string) => string | null; // this turn fails with that error text, writing nothing+ holdMs?: (step: string) => number; // this turn takes that long (ends early when cancelled)+ broken?: (step: string) => 'once' | 'always' | null; // its JSON files come out unreadable; 'once': the format fix repairs them+ say?: (step: string) => string | null; // this turn succeeds and replies with that text}+ const pending = new Map<string, { files: [string, unknown][]; always: boolean }>(); // per project: the good files a format fix writeslet S: Scenario;let calls: string[] = [];const count: Record<string, number> = {};@@@ -491,3 -404,133 +481,133 @@@ describe('restart', () =>assert.ok(calls.includes('replan'));});});++ describe('one flow per project', () => {+ test('an agent that fails inside the parallel cast gate is reported as that error, not as a failed review', async () => {+ S = base({ chars: ['hero', 'cat'], crash: (s) => (s === 'cast_qa:cat' ? 'You hit your limit' : null) });+ const id = newProject('plan_review');+ await J.approve(id);+ const j = J.load(id);+ assert.equal(j.stage, 'error');+ assert.equal(j.failed, 'producing');+ assert.match(j.error || '', /用量到上限|usage limit/);+ assert.ok(!calls.includes('assemble'));+ });++ test('a turn that finished is not stopped for mentioning a rate limit or quota', async () => {+ S = base({ say: (s) => (s === 'build:C1' ? 'yt-dlp hit a rate limit, retried, done' : s === 'shot_qa:S2:1' ? 'within quota' : null) });+ const id = newProject('plan_review');+ await J.approve(id);+ assert.equal(J.load(id).stage, 'done');+ });++ test('an agent that fails on the shot line is reported as that error, not as a part to judge', async () => {+ S = base({ crash: (s) => (s === 'build:C2' ? 'segfault' : null) });+ const id = newProject('plan_review');+ await J.approve(id);+ const j = J.load(id);+ assert.equal(j.stage, 'error', j.chat.at(-1)?.text);+ assert.match(j.error || '', /缺少輸出:out\/check\/shots\/C2\.done\.json/);+ assert.ok(!j.chat.some((c) => /沒通過鏡頭審查/.test(c.text)));+ });++ test('a second flow is refused while one runs, and busy() says so', async () => {+ S = base({ holdMs: (s) => (s === 'setup' ? 300 : 0) });+ const id = newProject('plan_review');+ const first = J.approve(id);+ assert.equal(J.busy(id), true);+ await assert.rejects(J.retry(id), (e: Error & { code?: number }) => e.code === 409);+ await first;+ assert.equal(J.busy(id), false);+ assert.equal(J.load(id).stage, 'done');+ });++ test('cancel stops the whole run: no new segment starts after it', async () => {+ S = base({ chunks: ['C1', 'C2', 'C3', 'C4'].map((c, i) => ({ id: c, shots: [`S${i + 1}`] })), holdMs: (s) => (s.startsWith('build:') ? 400 : 0) });+ const id = newProject('plan_review');+ const saved = J.CONFIG.builders; J.CONFIG.builders = 1;+ try {+ const flow = J.approve(id);+ while (!calls.includes('build:C1')) await new Promise((r) => setTimeout(r, 10));+ J.cancel(id);+ await flow;+ } finally { J.CONFIG.builders = saved; }+ const j = J.load(id);+ assert.equal(j.stage, 'error');+ assert.match(j.error || '', /已取消|Cancelled/);+ assert.deepEqual(calls.filter((c) => c.startsWith('build:')), ['build:C1']);+ assert.equal(J.busy(id), false);+ });+ });++ describe('round limits', () => {+ test('final review: after finalRounds revises it stops and leaves the call to the user', async () => {+ S = base({ critique: () => ({ must: 1 }) });+ const id = newProject('plan_review');+ J.setRounds(id, { finalRounds: 1 });+ await J.approve(id);+ const j = J.load(id);+ assert.equal(j.stage, 'done');- assert.deepEqual(calls.slice(-3), ['critique', 'revise', 'critique']);++ assert.deepEqual(calls.slice(-4), ['critique', 'fix:C1', 'revise', 'critique']); // S1's item goes to its builder first+ assert.match(j.chat.at(-1)!.text, /自動修改上限|fix limit/);+ });++ test('parallel cast gate: a character that never passes stops the gate and is named', async () => {+ S = base({ chars: ['hero', 'cat'], castPass: (w) => w !== 'cat' });+ const id = newProject('plan_review');+ J.setRounds(id, { castRounds: 2 });+ await J.approve(id);+ const j = J.load(id);+ assert.equal(j.stage, 'needs_input');+ assert.equal(j.pipeline.cast!.chars!.cat.state, 'failed');+ assert.equal(j.pipeline.cast!.chars!.hero.state, 'passed');+ assert.deepEqual(calls.filter((c) => c.includes('cat')), ['cast_qa:cat', 'cast_fix:cat', 'cast_qa:cat']);+ assert.match(j.chat.at(-1)!.text, /cat/);+ assert.ok(!calls.includes('cast_qa:lineup'));+ });++ test('a note on a segment stopped at its limit fixes first, then re-reviews only the bad shot (the reused review is not a round)', async () => {+ S = base({ shotPass: (s, r) => s !== 'S2' || r >= 2, blockers: 2 }); // two blockers: no extra round for a single one+ const id = newProject('plan_review');+ J.setRounds(id, { chunkRounds: 1 });+ await J.approve(id);+ assert.equal(J.load(id).pipeline.chunks!.C2.state, 'failed');+ calls = [];+ await J.message(id, 'the seam at S2 is fine if you soften it');+ assert.equal(J.load(id).stage, 'done', J.load(id).error || '');+ assert.deepEqual(calls, ['fix:C2', 'shot_qa:S2:2', 'assemble', 'critique']);+ });++ test('resuming a character stopped at its limit fixes it first (the reused review is not a round)', async () => {+ S = base({ chars: ['hero', 'cat'], castPass: (w, r) => w !== 'cat' || r >= 2 });+ const id = newProject('plan_review');+ J.setRounds(id, { castRounds: 1 });+ await J.approve(id);+ assert.equal(J.load(id).pipeline.cast!.chars!.cat.state, 'failed');+ calls = [];+ await J.resume(id);+ assert.equal(J.load(id).stage, 'done', J.load(id).error || '');+ assert.deepEqual(calls.filter((c) => c.startsWith('cast')), ['cast_fix:cat', 'cast_qa:cat', 'cast_qa:lineup']);+ });+ });++ describe('contract check', () => {+ test('a review that comes out unreadable goes back to its reviewer once, then the line goes on', async () => {+ S = base({ broken: (s) => (s === 'shot_qa:S1:1' ? 'once' : null) });+ const id = newProject('plan_review');+ await J.approve(id);+ assert.equal(J.load(id).stage, 'done', J.load(id).error || '');+ assert.ok(calls.indexOf('fix_format') > calls.indexOf('shot_qa:S1:1')); // reviews run side by side: not necessarily the very next call+ assert.equal(calls.filter((c) => c === 'fix_format').length, 1);+ });++ test('a production plan that stays broken stops the job and says what is wrong', async () => {+ S = base({ broken: (s) => (s === 'setup' ? 'always' : null) });+ const id = newProject('plan_review');+ await J.approve(id);+ const j = J.load(id);+ assert.equal(j.stage, 'error');+ assert.match(j.error || '', /格式不對.*build\/production\.json: not valid JSON/);+ assert.ok(!calls.some((c) => c.startsWith('build:')));+ });+ });diff --cc app/server/production.tsindex 0000000,d872026..d783712mode 000000,100644..100644--- a/app/server/production.ts+++ b/app/server/production.ts@@@ -1,0 -1,149 +1,156 @@@+ // Production after approval: setup (director) → cast gate → shot line (N builders in parallel; every shot is reviewed by+ // a fresh shot_qa as soon as it is built ⇄ fix_chunk; passed segments render in the background) → assemble (director).+ // With OVERLAP_CAST=1 the shot line starts while the cast gate is still running.+ // Quality is checked where defects are born (each character, each segment), not only at the end.+ import { existsSync, writeFileSync, statSync } from 'node:fs';+ import { join } from 'node:path';+ import { castGate } from './cast.ts';+ import { prerender, resetPrerenders, waitPrerenders } from './prerender.ts';+ import { blockerFree, reviewFix, sharedItems } from './review.ts';+ import { aborted } from './runner.ts';-import { CONFIG, L, chat, collectNeeds, dirOf, load, log, pause, pipe, readJSON, rounds, setStage } from './store.ts';++import { CONFIG, L, chat, collectNeeds, dirOf, load, log, pause, pipe, preset, readJSON, rounds, setStage } from './store.ts';+ import { fail, step, turn, type TurnResult } from './turn.ts';+ import type { ChunkProgress, NeedRequest, Pipeline, Plan } from '../shared/types.ts';+ import type { Chunk, ChunkReview, Production, ShotEntry } from './types.ts';++ const sharedLocks = new Map<string, Promise<unknown>>(); // per project: one director edits shared files at a time+ function sharedLock<T>(key: string, fn: () => Promise<T>): Promise<T> { const prev = sharedLocks.get(key) || Promise.resolve(); const next = prev.then(fn, fn); sharedLocks.set(key, next.catch(() => {})); return next; }++ const STATE = { error: 'error', needs: 'needs_user', passed: 'passed', limit: 'failed', handoff: 'error' } as const;++ // at most CONFIG.maxReviews shot reviews of one project at a time (each grabs frames in Chrome)+ const reviewQ = new Map<string, { n: number; wait: (() => void)[] }>();+ async function reviewSlot<T>(id: string, fn: () => Promise<T>): Promise<T> {+ const q = reviewQ.get(id) || { n: 0, wait: [] }; reviewQ.set(id, q);+ if (q.n >= CONFIG.maxReviews) await new Promise<void>((r) => q.wait.push(r)); // woken with the slot already counted+ else q.n++;+ try { return await fn(); } finally { const next = q.wait.shift(); if (next) next(); else q.n--; }+ }++ export async function production(id: string, { fresh = false } = {}): Promise<boolean> {+ const d = dirOf(id), prev: Pipeline = fresh ? {} : load(id).pipeline || {};+ // a piece with no characters (typography, motion graphics) has no cast sheet to make+ const sheet = (readJSON<Plan>(join(d, 'plan.json'))?.characters || []).length ? ['out/check/cast/sheet.jpg'] : [];+ const hasSetup = !fresh && [join('build', 'production.json'), ...sheet].every((f) => existsSync(join(d, f)));+ // 1) director: scaffold, shared assets, cast sheets, chunk plan (skipped when resuming)+ if (!hasSetup) {+ pipe(id, (p) => { p.phase = 'setup'; });+ if (!(await step(id, 'producing', 'setup', {}, ['build/production.json', ...sheet]))) return false;+ } else setStage(id, 'producing', { error: null, failed: null });+ // 2) cast gate, then 3) shot building. With overlapCast they run at the same time: shots only call the shared character+ // definitions, so cast fixes flow into them; shot REVIEWS still wait until the cast has passed.+ resetPrerenders(id); // a fresh or resumed production may render in the background again+ const castP = castGate(id, prev);+ if (!CONFIG.overlapCast && !(await castP)) return false; // characters are final before any shot is built+ const prod = readJSON<Production>(join(d, 'build', 'production.json')) || {};+ const chunks = prod.chunks || [];+ const old = prev.chunks || {};+ let broken = null as TurnResult | null; // the first agent turn that failed: reported as itself, not as "didn't pass review"+ // a segment that stopped at its round limit already has a fresh review: resuming fixes those issues first instead of re-reviewing unchanged shots+ pipe(id, (p) => { p.phase = 'shots'; p.chunks = Object.fromEntries(chunks.map((c): [string, ChunkProgress] => [c.id, old[c.id]?.state === 'passed' ? old[c.id] : { shots: c.shots, state: 'queued', round: 0, fixFirst: !!old[c.id]?.fixFirst || old[c.id]?.state === 'failed' }])); });+ const runChunk = async (c: Chunk): Promise<boolean> => {+ const key = `builder-${c.id}`, set = (s: Partial<ChunkProgress>) => pipe(id, (p) => Object.assign(p.chunks![c.id], s));+ if (load(id).pipeline.chunks?.[c.id]?.state === 'passed') return true;+ const SH = join(d, 'out', 'check', 'shots'), shotFile = (sid: string, kind: string) => join(SH, `${sid}.${kind}.json`);+ // Every shot gets its own fresh reviewer as soon as the builder marks it done (<shot>.done.json), while the builder+ // goes on with the next shot. Reviews still wait for the cast gate, and each one is a full review of that shot.+ const reviews: Record<string, Promise<boolean>> = {}, results: Record<string, { entry: ShotEntry; needs: NeedRequest[]; verified: unknown[] }> = {};+ const reviewShot = (sid: string, round: number) => (reviews[sid] = (async () => {+ if (!(await castP)) return false;+ const r = await reviewSlot(id, () => turn(id, 'shot_qa', { chunk: c, shots: [sid], round, out: `out/check/shots/${sid}.review.json` }, [`out/check/shots/${sid}.review.json`], { session: 'fresh', who: `shot-qa-${sid}` }));+ if (!r.ok) { broken ??= r; return false; }+ const rv = readJSON<ChunkReview>(shotFile(sid, 'review')) || {};+ results[sid] = { entry: (rv.shots || []).find((x) => x.id === sid) || { id: sid, pass: !!rv.pass, issues: rv.issues || [] }, needs: rv.needs_user || [], verified: rv.verified_fixes || [] };+ return true;+ })());+ const mergeReview = () => { // the segment-level file the UI, fixes and resumes read+ const all = c.shots.filter((x) => results[x]);+ writeFileSync(join(SH, `${c.id}.review.json`), JSON.stringify({ shots: all.map((x) => results[x].entry), verified_fixes: all.flatMap((x) => results[x].verified), needs_user: all.flatMap((x) => results[x].needs) }, null, 1));+ };+ let reuse = load(id).pipeline.chunks?.[c.id]?.fixFirst && existsSync(join(SH, `${c.id}.review.json`));+ if (reuse) set({ fixFirst: false });+ if (fresh || !existsSync(join(SH, `${c.id}.done.json`))) {+ set({ state: 'building' });+ const t0 = Date.now(), seen = new Set();+ const watch = setInterval(() => {+ for (const sid of c.shots) if (!seen.has(sid) && existsSync(shotFile(sid, 'done')) && statSync(shotFile(sid, 'done')).mtimeMs > t0) { seen.add(sid); reviewShot(sid, 1); }+ }, 4000);+ const b = await turn(id, 'build_chunk', { chunk: c }, [`out/check/shots/${c.id}.done.json`], { session: key, who: key });+ clearInterval(watch);+ if (!b.ok) { broken ??= b; set({ state: 'error' }); return false; }+ }+ if (!load(id).pipeline.cast?.pass) set({ state: 'waiting_cast' });+ if (!(await castP)) { set({ state: 'built' }); return false; }+ let todo = c.shots, reused = false;+ const { end, last } = await reviewFix<{ bad: ShotEntry[]; needs: NeedRequest[] }>({+ review: async (round) => {+ set({ state: 'reviewing', round });+ if (reuse) { // after a user note the latest review is still valid: fix first+ const rv = readJSON<ChunkReview>(join(SH, `${c.id}.review.json`)) || {};+ for (const e of rv.shots || []) results[e.id] = { entry: e, needs: [], verified: [] };+ reuse = false; reused = true;+ } else {+ for (const sid of todo) if (!reviews[sid] || round > 1) reviewShot(sid, round); // round 1: shots the watcher missed+ const ok = await Promise.all(todo.map((sid) => reviews[sid]));+ if (ok.includes(false)) return null;+ mergeReview();+ }+ return { needs: c.shots.flatMap((x) => results[x]?.needs || []), bad: c.shots.map((x) => results[x]?.entry).filter((e): e is ShotEntry => !!e && !blockerFree(e)) };+ },+ verdict: (r) => (collectNeeds(id, r.needs, `shot-qa-${c.id}`) ? 'needs' : r.bad.length ? 'fix' : 'passed'),+ // a reused review isn't a round: the user's note still gets its fixes. One blocker left at the limit: one more round+ // instead of pausing (a real run sat 23 minutes waiting to say "fix it")+ limit: ({ bad }) => rounds(id).chunkRounds + (reused ? 1 : 0) + (bad.flatMap((e) => e.issues || []).filter((x) => x.severity !== 'polish').length <= 1 ? 1 : 0),+ fix: async ({ bad }, round) => {+ set({ state: 'fixing' });+ const f = await turn(id, 'fix_chunk', { chunk: c, bad, round, message: load(id).userNote }, [`out/check/shots/${c.id}.fixes.json`], { session: key, who: key });+ if (!f.ok) { broken ??= f; return 'error'; }+ // shared-file problems (rig, cast, common assets) can't be fixed by a builder: the director fixes them right now,+ // one at a time across segments, before this segment is reviewed again+ const shared = sharedItems(readJSON(join(SH, `${c.id}.fixes.json`)));+ if (shared.length) {+ set({ state: 'shared_fix' });+ const ok = await sharedLock(id, async () => {+ const r = await turn(id, 'shared_fix', { chunk: c, items: shared }, [`out/check/shots/${c.id}.shared.json`], { who: 'director' });+ if (!r.ok) log(id, { type: 'error', text: `共用檔修正沒有完成(${c.id})` });+ return r.ok;+ });+ if (ok) { // the builder applies the new shared feature in the same round, so the next review sees it+ set({ state: 'fixing' });+ const g = await turn(id, 'fix_chunk', { chunk: c, bad: shared.map((x) => ({ id: x.shot ?? '', issues: [{ issue: x.issue, fix: '導演已改好共用檔,照 shared.json 的 api 套用' }] })), round, message: load(id).userNote }, [`out/check/shots/${c.id}.fixes.json`], { session: key, who: key });+ if (!g.ok) { broken ??= g; return 'error'; }+ }+ }+ todo = bad.map((e): string | undefined => e.id).concat(shared.map((x) => x.shot)).filter((x, i, A): x is string => !!x && A.indexOf(x) === i && c.shots.includes(x));+ return 'ok';+ },+ });++ if (end === 'limit' && !preset(id).pauseAtLimit) {++ // fast mode: carry on with what is left (the final review sees the whole film; the user can upgrade the mode)++ const left = last!.bad.flatMap((e) => e.issues || []).filter((x) => x.severity !== 'polish').length;++ set({ state: 'passed', open: last!.bad.length, acceptedAtLimit: true }); prerender(id, c);++ chat(id, 'system', L(id, `快速模式:${c.id} 審到上限,還有 ${left} 個問題,先繼續製作(最後評審會再看整支片)`, `Fast mode: ${c.id} reached its review limit with ${left} issue${left === 1 ? '' : 's'} left; carrying on (the final review sees the whole film)`));++ return true;++ }+ set(end === 'limit' ? { state: 'failed', open: last!.bad.length } : { state: STATE[end] });+ if (end === 'passed') prerender(id, c);+ return end === 'passed';+ };+ const queue = [...chunks];+ await Promise.all(Array.from({ length: Math.max(1, Math.min(CONFIG.builders, chunks.length)) }, async () => {+ while (queue.length && !aborted(id)) await runChunk(queue.shift()!);+ }));+ if (!(await castP)) return false; // the cast gate paused for the user; built segments are kept+ if (broken) return fail(id, 'producing', broken);+ const j = load(id);+ if ((j.needs || []).length) return pause(id);+ const failed = Object.entries(j.pipeline.chunks || {}).filter(([, v]) => v.state !== 'passed');+ if (failed.length) {+ chat(id, 'system', L(id, `有 ${failed.length} 段沒通過鏡頭審查:${failed.map(([k, v]) => `${k}(${v.state})`).join('、')},請你看這幾段決定`, `${failed.length} part${failed.length > 1 ? 's' : ''} didn't pass shot review: ${failed.map(([k, v]) => `${k} (${v.state})`).join(', ')}. Please take a look and decide`));+ return pause(id);+ }+ // 4) assemble (after the background renders of passed segments, so their frames are reused, not redrawn)+ pipe(id, (p) => { p.phase = 'assemble'; });+ await waitPrerenders(id);+ return step(id, 'producing', 'assemble', {}, ['out/video.mp4'], 'done');+ }diff --cc app/server/store.tsindex 0000000,6625c85..aaf5a58mode 000000,100644..100644--- a/app/server/store.ts+++ b/app/server/store.ts@@@ -1,0 -1,123 +1,142 @@@+ // The job's files: projects/<id>/job.json is the state, logs/events.jsonl the full event log. Everything that reads or+ // writes them goes through here, and every write is announced on `bus` (the SSE stream and notify.ts listen).-import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, writeFileSync, readdirSync, statSync, statfsSync } from 'node:fs';++import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, writeFileSync, readdirSync, renameSync, rmSync, statSync, statfsSync } from 'node:fs';+ import { dirname, join, resolve } from 'node:path';+ import { EventEmitter } from 'node:events';-import { ROUND_KEYS } from '../shared/types.ts';-import type { ChatMessage, Config, Job, LogEntry, LogEvent, Need, NeedRequest, Pipeline, RoundKey, Rounds, Stage } from '../shared/types.ts';++import { QUALITIES, ROUND_KEYS } from '../shared/types.ts';++import type { ChatMessage, Config, Job, LogEntry, LogEvent, Need, NeedRequest, Pipeline, Quality, QualityPreset, RoundKey, Rounds, Stage } from '../shared/types.ts';++ export const ROOT = join(import.meta.dirname, '..', '..');+ export const PROJECTS = process.env.REELMIMIC_PROJECTS ? resolve(process.env.REELMIMIC_PROJECTS) : join(ROOT, 'projects'); // override: tests, a second checkout+ export const SCRIPTS = join(ROOT, '.claude', 'skills', 'video-clone', 'scripts');+ export const PY = process.env.PYTHON || 'python';+ export const noPython = (e: Error) => `${PY} could not be started (${e.message}). Install Python 3.10+, or set PYTHON=/path/to/python`;+-export const CONFIG: Config = {- builders: +(process.env.BUILDERS || 6), // parallel shot builders per project (12 cores / 32 GB measured)++const FINE: Rounds = {+ castRounds: +(process.env.CAST_ROUNDS || 3), // cast gate: review/fix rounds before asking the user+ chunkRounds: +(process.env.CHUNK_ROUNDS || 3), // shot line: review/fix rounds per chunk+ finalRounds: +(process.env.FINAL_ROUNDS || 2), // final panel: automatic revise rounds++};++export const CONFIG: Config = {++ ...FINE, // the 'fine' line (projects made before modes existed)++ // Quality modes (shared/types.ts). The prompts change with the mode too: what blocks, and where every frame is checked.++ presets: {++ // a round is one review: 2 = review, fix, review again++ fast: { castRounds: 2, chunkRounds: 2, finalRounds: 1, converge: 0, pauseAtLimit: false },++ standard: { castRounds: 2, chunkRounds: 3, finalRounds: 2, converge: 1, pauseAtLimit: true },++ fine: { ...FINE, converge: 3, pauseAtLimit: true },++ },++ builders: +(process.env.BUILDERS || 6), // parallel shot builders per project (12 cores / 32 GB measured)+ maxAgentsGlobal: +(process.env.MAX_AGENTS || 12), // all projects together (CLI rate limits, CPU/GPU for renders)+ maxReviews: +(process.env.MAX_REVIEWS || 4), // shot reviews at once per project: each one opens Chrome to grab frames;+ // 13 at once meant 80–200 Chrome processes and screenshot timeouts+ // Build shots while the cast gate is still running? Faster, but on real runs character files changed under the+ // builders and every segment needed an extra round (0nczg, 4f1jx, 1qo20, 7e45u). Off by default: quality first.+ overlapCast: process.env.OVERLAP_CAST === '1',+ };++ // Review/fix round limits: CONFIG holds the defaults; a project can set its own (job.settings), read at every check so a+ // change applies from the next round on. When a limit is reached the job pauses for the user instead of looping.+ export const ROUND_RANGE = { min: 1, max: 10 };-export function rounds(id: string): Rounds { const s = load(id).settings || {}; return Object.fromEntries(ROUND_KEYS.map((k) => [k, s[k] ?? CONFIG[k]])) as Rounds; }++export const qualityOf = (j: Job): Quality => (QUALITIES.includes(j.quality as Quality) ? j.quality! : 'fine');++export const preset = (id: string): QualityPreset => CONFIG.presets[qualityOf(load(id))];++export const presetRounds = (q: Quality) => Object.fromEntries(ROUND_KEYS.map((k) => [k, CONFIG.presets[q][k]])) as Rounds;++export function rounds(id: string): Rounds { const j = load(id), s = j.settings || {}, p = CONFIG.presets[qualityOf(j)]; return Object.fromEntries(ROUND_KEYS.map((k) => [k, s[k] ?? p[k]])) as Rounds; }+ // Validates { castRounds?, chunkRounds?, finalRounds? } (whole numbers 1–10; '' / null = back to the default). Throws on bad input.+ export function cleanRounds(input: Record<string, unknown> = {}) {+ const out: Partial<Record<RoundKey, number | null>> = {};+ for (const k of ROUND_KEYS) {+ if (!(k in input)) continue;+ const raw = input[k];+ if (raw === '' || raw == null) { out[k] = null; continue; }+ const v = Number(raw);+ if (!Number.isInteger(v) || v < ROUND_RANGE.min || v > ROUND_RANGE.max) throw new Error(`${k} must be a whole number from ${ROUND_RANGE.min} to ${ROUND_RANGE.max}`);+ out[k] = v;+ }+ return out;+ }++ export type BusEvent = { type: 'job'; job: Job } | { type: 'log'; ev: LogEvent };+ export const bus = new EventEmitter<{ job: [id: string, ev: BusEvent] }>(); bus.setMaxListeners(100);++ export const now = () => new Date().toISOString();+ export const dirOf = (id: string) => join(PROJECTS, id);+ export const jpath = (id: string) => join(dirOf(id), 'job.json');+ // System messages in the project's language (Simplified Chinese is converted from the Chinese text by the UI).+ export const L = (id: string, zh: string, en: string) => (load(id).lang === 'en' ? en : zh);+ export const CANCELLED = { zh: '已取消', en: 'Cancelled' }; // the error text of a cancelled turn (notify.ts stays quiet on it)+ // job.json carries no event log: rewriting the whole file for every agent event (a dozen agents streaming at once) was+ // most of the server's disk work. The log is logs/events.jsonl (complete), and the latest LOG_KEEP events are kept in+ // memory for the UI (snapshot() puts them in job.log).+ export function load(id: string): Job { const j = JSON.parse(readFileSync(jpath(id), 'utf8')); j.log = []; return j; }+ export function save(job: Job) {+ recentLog(job.id); // first touch: a project from before events.jsonl still has its log in job.json; move it out before it's dropped- job.updatedAt = now(); writeFileSync(jpath(job.id), JSON.stringify({ ...job, log: undefined }, null, 1)); bus.emit('job', job.id, { type: 'job', job }); return job;++ // atomic: a full disk once truncated job.json to 0 bytes mid-write and the project could no longer be opened++ job.updatedAt = now();++ const f = jpath(job.id), tmp = `${f}.${process.pid}.tmp`;++ try { writeFileSync(tmp, JSON.stringify({ ...job, log: undefined }, null, 1)); renameSync(tmp, f); }++ catch (e) { try { rmSync(tmp, { force: true }); } catch {} throw e; }++ bus.emit('job', job.id, { type: 'job', job }); return job;+ }+ export function update(id: string, fn: (j: Job) => void) { const j = load(id); fn(j); return save(j); }+ const LOG_KEEP = 600, TAIL_BYTES = 1 << 20;+ const recent = new Map<string, LogEvent[]>();+ const eventsFile = (id: string) => join(dirOf(id), 'logs', 'events.jsonl');+ export function recentLog(id: string): LogEvent[] {+ let list = recent.get(id);+ if (list) return list;+ const f = eventsFile(id);+ if (existsSync(f)) { // the tail of the full log (one read per project per server start)+ const size = statSync(f).size, start = Math.max(0, size - TAIL_BYTES), buf = Buffer.alloc(size - start), fd = openSync(f, 'r');+ try { readSync(fd, buf, 0, buf.length, start); } finally { closeSync(fd); }+ const lines = buf.toString('utf8').split('\n').slice(start > 0 ? 1 : 0); // the first line may be cut+ list = lines.flatMap((l) => { try { return l.trim() ? [JSON.parse(l) as LogEvent] : []; } catch { return []; } }).slice(-LOG_KEEP);+ } else {+ list = (readJSON<Job>(jpath(id))?.log || []).slice(-LOG_KEEP);+ if (list.length) try { mkdirSync(dirname(f), { recursive: true }); appendFileSync(f, list.map((e) => JSON.stringify(e) + '\n').join('')); } catch {}+ }+ recent.set(id, list);+ return list;+ }+ export function log(id: string, ev: LogEntry) {+ const e = { ts: now(), ...ev }, list = recentLog(id);+ list.push(e); if (list.length > LOG_KEEP) list.splice(0, list.length - LOG_KEEP);+ try { mkdirSync(dirname(eventsFile(id)), { recursive: true }); appendFileSync(eventsFile(id), JSON.stringify(e) + '\n'); } catch {}+ bus.emit('job', id, { type: 'log', ev: e });+ }+ export function touch(id: string) { update(id, () => {}); } // tell open pages to reload (e.g. after files were added)++ export const setStage = (id: string, stage: Stage, extra: Partial<Job> = {}) => update(id, (j) => Object.assign(j, { stage, ...extra }));+ export const chat = (id: string, role: ChatMessage['role'], text: string, extra: Partial<ChatMessage> = {}) => update(id, (j) => { j.chat.push({ role, text, ts: now(), ...extra }); });+ export const pipe = (id: string, fn: (p: Pipeline) => void) => update(id, (j) => { j.pipeline = j.pipeline || {}; fn(j.pipeline); });+ export function pause(id: string) { setStage(id, 'needs_input'); return false; }++ // Renders need room (frames, previews, the encode): warn early instead of failing mid-render. A real run had 66 MB left.+ const MIN_FREE_GB = 5;+ export function diskWarning(id: string) {+ try {+ const f = statfsSync(PROJECTS), gb = (f.bavail * f.bsize) / 2 ** 30;+ if (gb < MIN_FREE_GB) chat(id, 'system', L(id, `⚠️ 磁碟只剩 ${gb.toFixed(1)} GB,渲染可能中途失敗;建議先清出 ${MIN_FREE_GB} GB 以上。`, `⚠️ Only ${gb.toFixed(1)} GB of disk left; rendering may fail midway. Free at least ${MIN_FREE_GB} GB first.`));+ } catch { /* statfs unsupported: skip */ }+ }++ // needs_user items (from any reviewer) pause instead of looping+ export function collectNeeds(id: string, items: NeedRequest[] | undefined, from: string) {+ const add: Need[] = (items || []).filter(Boolean).map((n) => ({ ...n, from, at: now() }));+ if (!add.length) return 0;+ // a new batch from the same reviewer replaces its earlier one (the critic re-reports open items every round)+ update(id, (j) => { j.needs = [...(j.needs || []).filter((x) => x.from !== from && !add.some((a) => a.issue === x.issue)), ...add]; });+ chat(id, 'system', L(id, `需要你提供:${add.map((n) => n.issue).join(';')}`, `Needs your input: ${add.map((n) => n.issue).join('; ')}`));+ return add.length;+ }+-export const readJSON = <T>(p: string): T | null => { try { return JSON.parse(readFileSync(p, 'utf8')); } catch { return null; } };++// a byte-order mark (PowerShell writes one) is fine++export const readJSON = <T>(p: string): T | null => { try { const t = readFileSync(p, 'utf8'); return JSON.parse(t.charCodeAt(0) === 0xfeff ? t.slice(1) : t); } catch { return null; } };+ export const readText = (p: string): string | null => { try { return readFileSync(p, 'utf8'); } catch { return null; } };+ export const oneOf = (v: string | null | undefined, ...L: string[]) => !!v && L.includes(v);+ export const mtime = (p: string) => (existsSync(p) ? statSync(p).mtimeMs : 0);+ // Files in one folder of the project matching re, newest first, as project-relative paths.+ export function listFiles(id: string, sub: string, re: RegExp) {+ const p = join(dirOf(id), sub);+ return existsSync(p) ? readdirSync(p).filter((f) => re.test(f)).map((f) => ({ f: `${sub}/${f}`, t: statSync(join(p, f)).mtimeMs })).sort((a, b) => b.t - a.t).map((x) => x.f) : [];+ }diff --cc app/server/turn.tsindex 0000000,ea12f90..026d6a6mode 000000,100644..100644--- a/app/server/turn.ts+++ b/app/server/turn.ts@@@ -1,0 -1,118 +1,118 @@@+ // One agent turn: a slot from the global budget, the step's prompt, and a check that the files it must write were updated.+ // turn() never touches the stage; step() is a turn that does (it moves the job on, or stops it in `error` with the reason).+ import { existsSync, statSync } from 'node:fs';+ import { join, relative } from 'node:path';+ import { runAgent, type AgentResult } from './agents/index.ts';+ import { checkFile } from './contract.ts';+ import { prompts as bootPrompts } from './prompts.ts';+ import { signalOf } from './runner.ts';-import { CANCELLED, CONFIG, L, ROOT, chat, dirOf, listFiles, load, log, mtime, readText, setStage, update } from './store.ts';++import { CANCELLED, CONFIG, L, ROOT, chat, dirOf, listFiles, load, log, mtime, qualityOf, readText, setStage, update } from './store.ts';+ import type { Stage } from '../shared/types.ts';+ import type { Phase, Prompts, StepVars } from './types.ts';++ // prompts.ts is re-imported when it changes, so prompt fixes reach the next agent turn without restarting running jobs+ let promptCache: { m: number; p: Prompts } = { m: 0, p: bootPrompts };+ async function livePrompts() {+ const f = join(import.meta.dirname, 'prompts.ts'), m = statSync(f).mtimeMs;+ if (m !== promptCache.m) { try { promptCache = { m, p: (await import(`./prompts.ts?v=${m}`)).prompts }; } catch (e) { console.error('prompts reload failed', e); } }+ return promptCache.p;+ }++ // ---------- global agent slots (all projects share them) ----------+ // Reviews and fixes jump the queue: a defect is fixed while the builder still has it in mind, and nobody waits on a+ // review behind a fresh 30-minute build. New builds take whatever slots are left.+ let used = 0; const waiters: { r: (ok: boolean) => void; hi: boolean }[] = [];+ const URGENT = new Set(['cast_qa', 'cast_fix', 'shot_qa', 'fix_chunk', 'assemble', 'critique', 'revise', 'replan', 'plan', 'style']);+ // false: the run was cancelled while waiting (no slot taken)+ async function slot(phase: Phase, signal: AbortSignal): Promise<boolean> {+ if (signal.aborted) return false;+ if (used < CONFIG.maxAgentsGlobal) { used++; return true; }+ const ok = await new Promise<boolean>((r) => {+ const w = { r, hi: URGENT.has(phase) };+ if (w.hi) { const i = waiters.findIndex((x) => !x.hi); i < 0 ? waiters.push(w) : waiters.splice(i, 0, w); } else waiters.push(w);+ signal.addEventListener('abort', () => { const i = waiters.indexOf(w); if (i >= 0) { waiters.splice(i, 1); r(false); } }, { once: true });+ });+ if (ok) used++;+ return ok;+ }+ function release() { used--; const w = waiters.shift(); if (w) w.r(true); }++ // session: 'director' (the project's main conversation), 'fresh' (a reviewer with no stake), or any key (a builder that keeps+ // its own conversation across its fix rounds).+ // A failed turn says why: cancelled, the AI account's usage limit, outputs not written, outputs that break CONTRACT.md+ // (after one chance to fix them), or the agent itself failed.+ export interface TurnOpts { session?: string; who?: string }+ type Why = 'aborted' | 'limit' | 'missing' | 'invalid' | 'crashed';+ export interface TurnResult { ok: boolean; why?: Why; text?: string; missing?: string[]; detail?: string }+ const LIMIT = /usage limit|rate limit|hit your limit|limit reached|quota|credit balance/i;+ export async function turn<P extends Phase>(id: string, phase: P, vars: StepVars[P], must: string[], { session = 'director', who }: TurnOpts = {}): Promise<TurnResult> {+ const j = load(id), d = dirOf(id), signal = signalOf(id);- const p = { dir: relative(ROOT, d).replace(/\\/g, '/'), brief: readText(join(d, 'brief.md')) || '', inputs: listFiles(id, 'inputs', /./), config: CONFIG, lang: j.lang || 'zh-TW', ...vars };++ const p = { dir: relative(ROOT, d).replace(/\\/g, '/'), brief: readText(join(d, 'brief.md')) || '', inputs: listFiles(id, 'inputs', /./), config: CONFIG, lang: j.lang || 'zh-TW', quality: qualityOf(j), ...vars };+ const before = must.map((f) => mtime(join(d, f)));+ const sid = session === 'fresh' ? undefined : session === 'director' ? j.sessionId : (j.sessions || {})[session];+ const label = who || (session === 'fresh' ? 'reviewer' : session);+ // one agent run in a slot; the session id is kept for the director and builders (a reviewer's only lives in this turn)+ const once = async (prompt: string, resume: string | null | undefined): Promise<AgentResult | null> => {+ if (!(await slot(phase, signal))) return null;+ log(id, { type: 'turn', state: 'start', phase, who: label });+ let res: AgentResult;+ try {+ res = await runAgent({ kind: j.agent, cwd: ROOT, prompt, sessionId: resume, signal,+ onEvent: (e) => {+ if (e.type === 'session' && session !== 'fresh') update(id, (jj) => { if (session === 'director') jj.sessionId = e.id; else { jj.sessions = jj.sessions || {}; jj.sessions[session] = e.id; } });+ if (e.type !== 'done') log(id, { ...e, who: label });+ } });+ } finally { release(); }+ log(id, { type: 'turn', state: 'end', phase, who: label, ok: !!res?.ok && !signal.aborted });+ return signal.aborted ? null : res;+ };+ let r = await once((await livePrompts())[phase](p), sid);+ if (!r) return { ok: false, why: 'aborted' };+ let missing = must.filter((f, i) => !(mtime(join(d, f)) > before[i]));+ // first turn after "retry": the interrupted turn may already have written everything, and the agent rightly+ // changes nothing. Existing outputs count then, so the user isn't stuck retrying a finished step.+ if (missing.length && r.ok && load(id).retryPending) missing = missing.filter((f) => !existsSync(join(d, f)));+ if (load(id).retryPending) update(id, (x) => { delete x.retryPending; });+ if (r.text) chat(id, session === 'fresh' ? 'critic' : session === 'director' ? 'agent' : 'builder', r.text, { phase, who: label });+ // an account limit is the real cause, even when it also left outputs missing: say so plainly. Only for a turn that+ // failed: a finished one may mention "rate limit" or "quota" (yt-dlp output, a reviewer's notes) without being stopped by one+ const limit = (!r.ok || missing.length) && [r.lastError, r.text, r.stderr].find((t) => t && LIMIT.test(t));+ if (limit) return { ok: false, why: 'limit', text: r.text, missing, detail: limit.slice(-300) };+ if (!r.ok && !missing.length) return { ok: false, why: 'crashed', text: r.text, detail: r.stderr.slice(-300) };+ if (missing.length) return { ok: false, why: 'missing', text: r.text, missing };+ // the files are there; do they follow CONTRACT.md? One chance to fix them, in the same conversation+ const check = () => must.filter((f) => f.endsWith('.json')).flatMap((f) => checkFile(f, readText(join(d, f)) ?? ''));+ let bad = check();+ if (bad.length && r.sessionId) {+ log(id, { type: 'error', text: `${label}: ${bad.join('; ')}`.slice(0, 400), who: label });+ r = await once(fixFormat(p.dir, bad), r.sessionId);+ if (!r) return { ok: false, why: 'aborted' };+ bad = check();+ }+ if (bad.length) return { ok: false, why: 'invalid', text: r.text, detail: bad.slice(0, 6).join('; ') };+ return { ok: true, text: r.text };+ }+ const fixFormat = (dir: string, bad: string[]) => `## 修正檔案格式+ 專案資料夾:${dir}。你剛寫的檔案不符合 .claude/skills/video-clone/CONTRACT.md,伺服器讀不懂:+ ${bad.map((b) => `- ${b}`).join('\n')}+ 只要把這些檔案照 CONTRACT.md 的格式重寫(內容保持你剛剛的判斷,只修格式),不要做別的事。`;++ export function fail(id: string, stageName: Stage, res: TurnResult) {+ const d = res.detail || '';+ const error = {+ aborted: () => L(id, CANCELLED.zh, CANCELLED.en),+ limit: () => L(id, `AI 帳號的用量到上限了,等額度恢復或換另一個 AI 導演再按「重試這一步」。原始訊息:${d}`, `Your AI account hit its usage limit. Wait until it resets (or switch to the other AI director), then click “Retry this step”. Message: ${d}`),+ missing: () => L(id, `缺少輸出:${(res.missing || []).join(', ')}`, `Missing output: ${(res.missing || []).join(', ')}`),+ invalid: () => L(id, `agent 寫的檔案格式不對(已請它重寫一次):${d}`, `The agent's files don't follow the contract (it was asked to rewrite them once): ${d}`),+ crashed: () => L(id, `agent 回合失敗${d ? ':' + d : ''}`, `The agent turn failed${d ? ': ' + d : ''}`),+ }[res.why || 'crashed']();+ setStage(id, 'error', { failed: stageName, error });+ return false;+ }+ export async function step<P extends Phase>(id: string, stageName: Stage, phase: P, vars: StepVars[P], must: string[], next?: Stage | null, opts?: TurnOpts) {+ setStage(id, stageName, { error: null, failed: null });+ const r = await turn(id, phase, vars, must, opts);+ if (!r.ok) return fail(id, stageName, r);+ if (next) setStage(id, next);+ return true;+ }diff --cc docs/ARCHITECTURE.mdindex d964a55,d3f7268..06bf84e--- a/docs/ARCHITECTURE.md+++ b/docs/ARCHITECTURE.md@@@ -15,8 -15,18 +15,18 @@@ Browser (app/web, React + ViteServer (app/server)├─ index.ts HTTP API, uploads, SSE, project files (/files/:id/*)├─ env.ts loads ~/.reelmimic/secrets.json at startup- ├─ jobs.ts workflow state machine + production scheduling (order, parallelism, pausing)- ├─ outputs.ts checks agent outputs: the JSON files a step must write parse and have the shape jobs.ts reads+ ├─ jobs.ts the user's actions (start, approve, message, retry…), project list and snapshot+ ├─ preprod.ts analysis → style → plan (characters and assets drafted in parallel)+ ├─ production.ts setup → cast gate → shot line (parallel builders, per-shot review) → assemble+ ├─ prerender.ts background render of passed segments (engines with a frame cache), stopped by Cancel+ ├─ cast.ts cast gate: per-character review/fix in parallel, line-up check, serial fallback+ ├─ final.ts final panel: critic ⇄ revise+ ├─ review.ts the review → fix loop every gate shares (round limits, needs_user, pass rule)+ ├─ turn.ts one agent turn: global slots (reviews and fixes jump the queue), required-file check, failure reason+ ├─ contract.ts format check for the JSON files agents write (plan, production, reviews, fixes, critique)+ ├─ runner.ts one flow per project; Cancel stops every agent and tool process it started (whole process tree)- ├─ store.ts job.json, event log, live-update bus, round limits++ ├─ store.ts job.json (written atomically), event log, live-update bus, round limits and quality presets+ ├─ inputs.ts required inputs and lyric timing├─ prompts.ts the instructions each step gives its agent (edits apply on the next turn, no restart)└─ agents/index.ts agent adapters: Claude Code / Codex → one event stream│ spawn (prompt on stdin, events streamed on stdout)diff --cc docs/COMPILER.mdindex 7eb7a01,0000000..5e61861mode 100644,000000..100644--- a/docs/COMPILER.md+++ b/docs/COMPILER.md@@@ -1,265 -1,0 +1,266 @@@+# ReelMimic as a style compiler — design++Status: stages 1–3 are implemented, tested and wired into the production line; the measurable part of stage 4 (agent+outputs checked, not just timestamped) is in; the rest of stage 4 and stage 5 are deliberately not built yet — see+[Decisions](#decisions-what-was-not-built-and-why). [Validation](#validation) says what was measured and what it showed,+including the parts that did not work.++## Why++Today the pipeline is open-loop: an agent writes engine code, another agent looks at screenshots and says whether it is+good. Nothing in the system *understands* what was built, and the only quantity we measure about the reference is one+averaged camera vector per shot plus a label (`push_in / slow`). What makes a reference film land — the shape of a push,+where a cut sits against the beat, how tension builds, holds its breath and hits — is a set of continuous, time-varying+signals, and we measure none of them.++The direction: treat ReelMimic as a **compiler** from a reference film to a new film.++```+reference video ──[1 perception]──▶ Style Fingerprint (time series + fitted curves)+ │+brief + plan ─────[LLM planning]───▶ Motion Score IR (typed scene graph, parametric curves, beat-anchored time)+ │ ▲+ │ └──[3 optimizer] tunes IR parameters against style_distance+ ▼+ [2 backends] HyperFrames · canvas engines · …+ ▼+ render ──▶ perception again ──▶ feedback+```++## Stages++| # | Stage | What it adds | Where |+|---|---|---|---|+| 1 | **Perception** | Style Fingerprint: per-frame camera trajectory, fitted easing curves, local (in-frame) motion, tension curve with peak shapes, cut-vs-beat phase, colour arc, frame descriptors; `style_distance` between two fingerprints with readable findings | `.claude/skills/video-clone/scripts/perception/` |+| 2 | **Motion Score IR** | A typed scene description: shots, layers, rig references, keyframe tracks whose curves are parametric (bezier / spring / named ease) and whose times are musical (`beat 17 + 2f`). Agents emit and patch IR for camera, timing and easing; engines compile it. Drawing code stays agent-written (IR and free code coexist) | `ir/` (schema + validator), one backend per engine, HyperFrames first |+| 3 | **Closed-loop optimizer** | CMA-ES over IR parameters of the climax shots, objective = `style_distance` to the reference peak, multi-fidelity (low-res proxy renders of key frames → full render to confirm). The LLM decides structure; the optimizer decides numbers | `optimize/` |+| 4 | **Orchestration kernel** | Event-sourced job state (state = fold(events)), a typed task DAG with declared inputs/outputs, schema-validated agent outputs instead of mtime checks, content-addressed caching, one resource-aware scheduler (agent tokens, Chrome, CPU/GPU) instead of three ad-hoc locks | `app/server/kernel/` replacing `jobs.ts` |+| 5 | **Learned critic** | Pairwise preference model over fingerprint features + frame embeddings, trained on reviewer verdicts and user feedback, used to calibrate the LLM critic | later |++Order: perception first (every later stage consumes it), then IR (the largest piece), then the kernel (task types only+settle once the IR exists), then the optimizer and the learned critic.++## Stage 1 — Perception++### Signals++All signals are sampled on one clock (`fps`, default 24) so they line up frame for frame.++| Module | Signal | Method |+|---|---|---|+| `video.py` | frames | ffmpeg → raw BGR pipe at fixed fps and width, streamed (a 3-minute reference never sits in memory) |+| `camera.py` | global motion per frame: `dx, dy` (frame widths), `dz` (log scale), `dr` (radians), camera convention (camera right = +x, push in = +z) | Shi–Tomasi corners → pyramidal Lucas–Kanade with forward–backward check → RANSAC similarity on centred coordinates; low texture falls back to 0 with `ok=false` |+| | local motion energy | median residual of tracked points after removing the global similarity (characters moving vs. the camera moving) |+| | cuts | HSV histogram correlation + mean abs difference, or the cut list from `analyze.py` |+| `curves.py` | per-shot move: active window, amplitude per axis, duration, easing as CSS `cubic-bezier`, damped spring, overshoot, nearest GSAP ease name | least squares on the normalised progress curve (Newton-solved bezier x(s)=u); presets sampled from GSAP's formulas |+| `tension.py` | tension(t) ∈ [0,1] and peak shapes | robust-normalised mix of loudness, spectral flux, camera speed, local motion, cut density and luminance jumps; each peak described by build slope, breath (dip before the hit), rise frames, height, decay |+| `rhythm.py` | cut phase against the beat | signed frame offset to the nearest beat, on-beat ratio (±1 frame), circular mean phase (on the beat vs. on the "and") |+| `look.py` | colour arc | per-frame Lab mean/std and a per-shot Lab histogram |+| `distance.py` | `style_distance` | banded DTW on curves, sliced Wasserstein on Lab histograms, easing curve RMSE, log ratios of durations and amplitudes; every component maps to 0–100 and produces findings in words |++### What real footage taught (each one is handled and tested)++| Problem | Seen on | Handling |+|---|---|---|+| A static overlay (phone UI over a screen recording, watermark, letterbox) votes "the camera did not move" | `20261002-xqmlk`: TikTok UI down the right side | pre-pass at 4 fps: pixels that never change over the clip are masked out of corner detection (`video.static_mask`) |+| A character moving over a plain background is read as the camera moving | a real film: a head tilt over a flat gradient measured as a 2.5° camera roll | two-layer motion: the tracks that agree mark the subject; the background's own motion is measured from corners searched for outside it (faint detail like sparkles counts); with no trackable background, the camera stands still unless moving it explains the background better than not (`camera.background_motion`, `background_says_still`) |+| A burned-in caption is a strip of strong corners that never moves | a real film: a 26 % push on a bowl read as "still" because the caption held still | background tracks only count when they spread over ≥ 15 % of the frame |+| A camera that rests a few frames before a move looked like limited animation | found by rendering through the real engine | a held drawing needs a real change on both sides; the first frame and cuts do not count |+| A move the edit cuts into or out of is fitted as a longer move than the shot | a real reference: a 1.83 s shot showing part of a 3.57 s push | the move's on-screen share is measured (`visible`, `seen`, `cut_off`, `lead_in`); the transfer writes the whole curve and lets our cut interrupt it the same way (`"past_cut": true`) |+| A slow drift down and back up over twelve seconds was called a shake | a real reference shot | a shake must change direction ≥ 1.5 times a second; slower back-and-forth is segmented into moves |+| A shot list a frame off the real cut turns the cut into a huge fake camera move | plan cut at 7.92 s, picture cut one frame later: "14 % pan in one frame" | cuts are always detected; given cuts snap to a detected one within ±3 frames; every fit is **photometrically verified** — warping the previous frame must explain the current one (`camera.photometric_ok`) |+| Limited animation (drawings held for two frames) makes speed a comb: 0, 2v, 0, 2v | the reference: 31 % of moving frames are holds | held runs (≤ 3 frames inside motion) share the step that ends them; the hold ratio itself is reported as **cadence** (on ones / mixed / on twos / on threes) |+| A speed-threshold window clips an ease's slow tail and stretches the shape | power3.out measured as 0.72 s instead of 1.0 s | start, duration, amount, offset and ease are fitted **jointly** on the whole shot: `x(t) = B + A·E(clip((t − t0)/D))` |+| An ease fitted on log-scale is not the ease a builder types | power3.out zoom read as power4.out | zoom eases are fitted on scale (`exp z`), the quantity engines tween |+| One long shot holds several moves | ref shot 3: settle, then a 1.2 s back.in pan | moves are segmented by still stretches; the biggest is the shot's move, the rest are `other_moves` |+| Comparing moves on different axes (a pull-out against a pan) gives nonsense timings | "0.04 s vs 2.10 s" | timing/ease compared only on the same main axis; 1–2-frame moves are `snap` (jump cuts, impact jolts), not eases |++### Files++```+analysis/fingerprint.json reference fingerprint (written by analyze.py)+analysis/fingerprint.png tension, camera speed, cuts, beats, peaks on one time axis+out/check/fingerprint.json our film's fingerprint (written by compare.py)+out/check/style_distance.json scores per component and per mapped shot, plus findings+out/check/fingerprint_overlay.png reference vs. ours, tension and camera speed overlaid+```++`fingerprint.json` is versioned (`"version"`); readers ignore fields they do not know.++### How it is used now++- `analyze.py` writes the reference fingerprint; the style and plan prompts can quote fitted eases and peak shapes+ instead of "slow push".+- `compare.py` adds `style_distance.json`; the final critic reads its findings ("s3 vs ref #4: the push is 38% slower+ and eases ≈ power1.out where the reference uses ≈ expo.out") as evidence next to the frames.++### Verification++`scripts/tests/` renders synthetic videos with known camera moves (a textured plate warped by a known similarity on a+known ease, with a cut) and checks that the trajectory, the fitted ease and the cut are recovered; curve fitting, DTW,+tension peaks and beat phase have analytic tests. Run: `python -m pytest .claude/skills/video-clone/scripts/tests`.++## Stage 2 — Motion Score IR++The camera and the timing of every shot as data instead of expressions buried in scene code+(`camBegin(lerp(925, 985, k), …)` with `k = ease(lt / dur)` and hit times typed as literals).++### Layers++```+authored score (build/score/film.json + shots/<id>.json) ← director (from-ref, then edits), builders (their own shot file)+ │ score/model.py: parse time expressions, normalise eases, check, resolve+ ▼+resolved score (every time in seconds, every move a segment {t0, t1, v0, v1, ease})+ ├── assets/score/score.js runtime the engines load (canvas kit and HyperFrames Kit share one camera model)+ └── score/runtime.py the same evaluator in Python — tests/test_score.py runs both and compares+ │+ └── score/predict.py camera → the trajectory perception would measure → compared with the reference+```++The front end does all parsing and checking, so the JS runtime is only evaluation (≈ 100 lines): the engines cannot+disagree with the tools about what a score means. One file per shot keeps parallel builders from colliding.++### Language++- **Time** (`score/timeexpr.py`): `B12` (beat 12), `S` / `E` (shot start / end), cue names, lengths in `s`, `b` (beats),+ `f` (frames): `"B12-2f"`, `"P1_hit+1b"`, `"S+0.25s"`. An instant has exactly one anchor; a length has none.+- **Camera**: `base {x, y, zoom, rot}` in stage coordinates (1920×1080, x/y = the world point at the frame centre) and+ `moves [{at, dur | until, to | by, ease}]`; zoom `by` multiplies. Moves on one channel run one after the other (a+ spring may be interrupted). `shakes [{at, amp, decay}]` use the kit's stable per-frame noise.+- **Eases**: GSAP names (the same formulas perception fits), `back.out(s)`, `{bezier: [...]}`, `{spring: {omega, zeta}}`,+ `hold`.+- **Tracks**: any other named number a shot animates (a reach, a lean) with the same moves. **Cadence**: 1–4 frames per+ drawing; `Score.held(id, t)` snaps time for limited animation.++Errors carry their place: `shots/S3.json.camera.moves[1]: x is still moving until 4.550s (moves[0]); start at or after it`.++### Motion transfer (`motion_score.py from-ref`)++Each move perception found in the mapped reference shot becomes a score move: same pace in seconds, amount converted+from frame widths to stage pixels at the current zoom, ease = the fitted curve (a GSAP name when it fits within 10 % of+the best model, else the cubic-bezier or spring) with *that model's own* start and duration. A scheduler places the+moves inside our (usually shorter) shot: as near as possible to where they happened, never overlapping, pace kept when+they fit, all compressed by one factor when they do not (recorded as `from_ref.compressed`). Cuts stay where the plan+put them; move starts snap to a beat only when that keeps them in place.++### Render-free prediction (`motion_score.py predict`)++The stage camera maps to perception's camera terms exactly (x += zoom·Δcx/W, z = ln zoom/zoom₀, r = −Δrot), so the+trajectory perception *would* measure is computed from the score and compared with the reference shot by the same+`camera_pair()` used on rendered films. Moves are compared on a model-free window — the curve between 5 % and 95 % of+the travel, read off the best-fitting model at 10× frame resolution — because "flat start + ease" and "later start ++another ease" are the same motion, and a fast move spans only a few frames.++On `20261002-xqmlk`: the delivered film's hand-written camera measures **10.4**; the transferred score predicts+**71.5** before a frame is rendered (73.3 after `optimize`). Across 18 projects see [Validation](#validation).++### Verification++`tests/test_score.py`: time expressions; resolving and its error messages; **the JS and Python runtimes agree** to 1e-9+on a score exercising every ease kind, shakes, tracks and cadence (it caught `%` on negative frame numbers differing+between the languages); **prediction = measurement** (the score's camera is filmed on the synthetic plate and perception+recovers the predicted kinds, amounts, duration and shape); **transfer closes the loop** (reference → measured →+score → predicted ≈ reference, score > 80, no major finding).++## Stage 3 — Closed-loop optimizer++`motion_score.py optimize <project> [--peaks] [--apply]` searches a score for the version closest to the reference,+render-free.++- **Search** (`optimize/cmaes.py`): CMA-ES in the unit box (Hansen's tutorial algorithm, boundary handling by+ projection + penalty), deterministic per seed. Tested on the sphere, Rosenbrock and an optimum outside the box.+- **Space** (`optimize/space.py`): per move its start (± 0.25 s), duration (× 2^±1) and curve (as a cubic-bezier,+ springs as ω, ζ); per shake amplitude and decay. **Amounts are locked** — they are the director's framing intent —+ unless `--tune-amounts`. A point is written back in the author's terms (an unchanged start keeps `B12`, an unchanged+ ease keeps its name) and every changed move records what it was (`"tuned": {"from": …}`).+- **Objective** (`optimize/objective.py`): per shot 100 − camera_pair against the mapped reference shot, read off the+ exact predicted trajectory sampled 10× finer than the frames (no fitting, vectorised evaluation: 1.8 ms an+ evaluation, 50× faster than the first version); plus staying near the author's values; with `--peaks`, the predicted+ tension at each plan peak against the reference peak's shape (one-sided: a deeper breath or a sharper hit than the+ reference costs nothing). Predicted tension is multi-fidelity: the film's own sound, the score's exact camera and+ cuts, in-frame motion from the last render.+- **Groups**: shots are independent for the camera, so each is searched alone; the shots around a plan peak are+ searched together. A group's result is kept only if it beats the author's version.++On `20261002-xqmlk`: 8 s for the whole film; with `--peaks` it proposes an 8 px shake on the chorus downbeat (which+the plan asked for) and moves the predicted climax onto the beat.++### Four ways the optimizer gamed its objective, and the fixes++Each was caught by checking a result some other way than the optimizer's own number.++1. **An invisible shake.** The first `--peaks` run "fixed" the climax with a 1.07 px shake: tension normalised each+ feature to the film's own range, so in a still film 1 px read as strong motion. Fix: just-noticeable floors per+ feature, perceptual dead zones for motion (`tension.JND`, `DEADZONE`), measured-but-constant features kept in the+ mix (dropping them made the weights jump), shakes under 4 px removed. Regression test: a ±1 px jitter changes+ tension by < 0.02, a real whip pan by > 0.08.+2. **Bent eases in a shortened shot.** When the plan makes a shot shorter than the reference's moves, the move must be+ faster — but the duration term compared absolute seconds, so the optimizer bent the curve to stretch its 5–95 %+ window, and a metric it never saw (the camera-speed profile) got worse (0.106 → 0.186). Fix: moves are expected to+ be as much faster as the shot is shorter (`distance.time_available`), the same rule the transfer schedules by.+ After it, that held-out metric improves too (table below).+3. **Curves no measurement describes.** The search reads shapes straight off the exact predicted curve; a rendered+ film is measured through fitted eases. With wide bezier bounds it found curves that score well on the exact curve+ and are unrecognisable once measured (88.8 predicted, 32.8 measured). Fix: eases bounded to readable curves+ (modest overshoot at most), and a **verification gate** — a group's result is kept only if it also wins measured+ the way a rendered film is (`Objective.verified_camera_costs`).+4. **Where in the shot.** Nothing in the comparison saw whether a move happens at the start or at the end of its+ shot; the optimizer moved one, and the held-out speed profile caught it. Fix: a placement term+ (`distance.placement_gap`), its expectation following the transfer's own time mapping.++## Validation++What was checked beyond unit tests, on the 18 projects with a reference and a delivered film (7 distinct references).+The scripts only read projects; results below are with the final code.++| Question | Method | Result |+|---|---|---|+| Does style_distance measure *style*? | split-half retrieval: 12 s windows of each reference find the other half of the same reference among all (balanced: ≤ 4 queries and candidates per reference, mean not max, ties count half) | **style** ranks the own reference **2.35** (chance 4.0): palette 2.12, pace 2.53, rhythm 3.00, frames 3.03; **tension 3.71 and peaks 3.74 ≈ chance** — they describe a stretch's content, not a style, so they only count as *structure* against the mapped window. Pace counts only *visible* camera motion (dead zone): with raw speed it partly measured each file's noise floor; removing that cost little (2.35 → 2.53), so it measures style |+| Do the delivered films (old pipeline) look like their references? | each film against every reference's best-matching window | palette **2.44**: colour was cloned; pace **3.22**, style 3.11: how the films *move* was barely cloned — the gap stages 1–3 target |+| Would following the score close that gap? | counterfactual: each film's measured camera replaced by its transferred score's camera, all else as measured | **per shot, yes**: camera_pair against the mapped reference shot **36.4 → 75.1** (median 24.9 → 83.0) over 202 shots, better in 73 % (the rest equal, mostly still against still). **Whole-film pace, no**: own-reference rank 3.22 → 3.39 — see the next row |+| Why not the whole film? | pace features of the delivered films against the stretch of reference they clone | the plans cut **1.6× as often** as their references' hard cuts (3.8 vs 2.4 per 10 s). First reading: a pacing gap made at planning. A real A/B run corrected it (below): references change scene *inside* their shots, so hard cuts undercount how often their picture changes, and holding a plan to them cost variety. `fingerprint.py plan-check` now only flags plans *slower* than the reference; the plan prompt asks for at least the reference's rate of scene changes (cuts + in-shot transitions) |+| Does the browser runtime do what the tools predict? | the engine kit renders a scene whose camera comes only from `Score.cam` in headless Chrome; perception measures it | camera_pair(measured, predicted) **99.2 / 99.6**; SVG camera = canvas camera to < 0.05 px (`tests/test_engine_render.py`) |+| Does optimizing help a *rendered* film, or only the number? | before/after cameras filmed on the textured plate, measured with full fitting (not the optimizer's path); plus a metric the optimizer never sees (DTW of camera-speed profiles) | from the transferred score (the production path): camera_pair **68.9 → 76.4**, held-out 0.052 → 0.051 (unchanged); from a hand-written camera (every move spread over the shot with a generic ease, as builders write today): **17.4 → 45.2**, held-out 0.105 → 0.124 — better on one shot, equal on one, worse on one whose reference move (already moving at the cut in, then still) cannot keep pace, placement and speed profile at once in a shorter shot. The optimizer proposes; the director applies |+| Do the tools work on projects made before them? | every command of the setup prompt run on a copy of a pre-perception HyperFrames project | yes, after making the reference fingerprint build itself when missing or stale (`ensure_reference`) |+| Cost | analysis adds the fingerprint | ≈ 20–40 s for a 30 s reference, ≈ 2.5 min for a 13 min one; optimize ≈ 8 s per film |++### Real productions (A/B)++The same reference, brief and inputs as two earlier projects, produced again end to end by real agents (Claude Code)+through the app with the new system; the earlier films are the baseline. Times are from `timeline.py`.++| | 30 s party MV (HyperFrames; old film: painted) | 15 s pixel story (pixel-art) |+|---|---|---|+| plan cutting vs reference | 1.12× (old plan 2.22×) | 1.07× |+| camera: the film follows the score? | yes — per shot measured ≈ predicted (S3 73.6 / 79.6, S6 36.8 / 36.8, S7 51.3 / 51.3) | mostly; an iris transition (a screen-space overlay) was read as a still background — see limits |+| measured vs reference | overall 30.2 → 36.4, style 13.9 → 21.0, camera 10.1 → 28.1 | — |+| final critic | 4 rounds, all 13 scores 4/5, both climaxes *beat* the reference | 4 rounds, climax 5/5, variety 5/5, both climaxes beat the reference (old critic had no climax check) |+| by eye | new: a clearer story (Clawd + Mimi), climaxes land; old: more varied compositions — the plan had been held to the reference's hard cuts (14 → 8 shots), the lesson behind the plan-check change | new clearly better: big expressive subject, a real reveal at the climax, a warm ending; old: tiny subject in wide shots |+| approve → done | 167 min (old 160) | 90 min (old 49) |+| where the time went | setup 13 (old 7), cast 19 (41), shots 65 (49), final 46 + one revise round (58) | setup 10 (4), cast 13 (20), shots 23 (33), final 42 (7) |++Production itself got faster on both (cast and shots); setup costs ≈ 6 min more (transfer, prediction, optimization);+the final review is where the time goes — the critic of this branch is much stricter (12 must-fix items in round 1 of+the pixel film against 1 for the old critic) and each round is ≈ 10–15 min. Found in these runs and fixed: a long+reference take mapped to several shots gave each shot the whole take (now each gets its part —+`fingerprint.reference_for`); the final review stopped at 9 → 3 must-fix items with a character still teleporting+(it now continues while the list halves or is ≤ 3); a contradictory finding ("holds still; ours holds still").++Limits: screen-space layers (an iris, a spotlight, a vignette) look like a background that does not move, so a push+behind them can be read as a still camera; and a single critic is still the final judge of quality.+++## Decisions: what was not built, and why++- **Stage 4, event-sourced kernel.** Measured first: a `log()` rewrites job.json (≈ 260 KB) in 3.9 ms, and the busiest+ real minute had 82 events — 0.5 % of a core. Rewriting a working, tested orchestrator for that would be change for- its own sake. What stage 4 was for that *does* fail in practice is in: outputs are checked- (`app/server/outputs.ts`), with one repair turn in the same conversation — before it, a critique.json with a- trailing comma was read as "nothing to fix" and the film delivered as passed, and a broken production.json built- nothing yet reached "done" (both reproduced in `pipeline.test.ts`).++ its own sake (main has since moved the event log out of job.json into `logs/events.jsonl`). What stage 4 was for++ that *does* fail in practice is in: agent outputs are checked against the contract (`app/server/contract.ts`), with++ one repair turn in the same conversation — otherwise a critique.json with a trailing comma reads as "nothing to fix"++ and a broken production.json builds nothing; and job.json is written atomically, after a full disk once truncated it++ to 0 bytes and the project could no longer be opened.+- **Stage 5, learned critic.** It needs labelled outcomes — which findings a director acted on, which the user agreed+ with — and there are 18 projects, judged only by an LLM critic. A model trained on that would learn the LLM critic+ and overfit. The data it needs is now produced for every film (`style_distance.json` next to `critique.json` and the+ user's notes); build it when there are a few hundred.diff --cc docs/assets/star-history.pngindex 0000000,0000000..70fc92fnew file mode 100644Binary files differ