videoclaw 3.0.0-alpha.1

package/src/video/emotion-cues.ts

@@ -0,0 +1,36 @@
+/**
+ * Emotion → physical-cue rewriting. Models render emotion better from physical
+ * cues ("eyes wide, jaw slack") than from named emotions ("scared"). ADVISORY +
+ * ADDITIVE: only moderate emotions are mapped; EXTREMES (panic, terror, rage,
+ * ecstatic, ...) are deliberately left named so the model pushes the
+ * performance. Unmapped names pass through unchanged.
+ */
+export const EMOTION_PHYSICAL_CUE_MAP: Readonly<Record<string, string>> = {
+  calm: 'shoulders relaxed, breathing even, jaw unclenched, gaze steady',
+  scared: 'eyes wide, jaw slack, breath shallow and quick, shoulders drawn up',
+  afraid: 'eyes wide, jaw slack, breath shallow and quick, shoulders drawn up',
+  angry: 'jaw clenched, eyes narrowed, nostrils flared, shoulders squared',
+  sad: 'eyes downcast and glassy, mouth corners pulled down, shoulders sunk',
+  surprised: 'eyebrows raised high, eyes round, mouth parted, head drawn back',
+  tense: 'jaw set, breath held, fingers curled tight, muscles rigid',
+  nervous: 'eyes flicking, throat swallowing, fingers fidgeting, weight shifting',
+  confused: 'brows knitted, head tilted, eyes searching, mouth slightly open',
+  joyful: 'eyes crinkled at the corners, cheeks lifted, easy open smile',
+  happy: 'eyes crinkled at the corners, cheeks lifted, easy open smile',
+  determined: 'jaw set, eyes locked forward, brow level, chin slightly lowered',
+  shaken: 'breath unsteady, hands trembling, gaze unfocused, shoulders caved',
+  wary: 'eyes narrowed and tracking, chin tucked, weight back on the heels',
+  relieved: 'shoulders dropping, a long slow exhale, brow smoothing',
+  defiant: 'chin raised, eyes hard, mouth a flat line, stance widened',
+};
+
+/**
+ * Map a named emotion to its physical-cue descriptor. Advisory: an unmapped or
+ * deliberately-excluded (extreme) emotion is returned unchanged, never dropped
+ * and never throws. `undefined` in → `undefined` out.
+ */
+export function rewriteEmotionAsPhysical(emotion: string | undefined): string | undefined {
+  if (emotion === undefined) return undefined;
+  const key = emotion.trim().toLowerCase();
+  return EMOTION_PHYSICAL_CUE_MAP[key] ?? emotion;
+}

package/src/video/environment-assets.ts

@@ -0,0 +1,69 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { resolveProjectWorkspace } from './workspace.js';
+import { writeTextFileAtomic } from './atomic-write.js';
+import type { AssetTagEntry } from './prompt-rules.js';
+
+export interface EnvironmentAssetEntry {
+  name: string;
+  description: string;
+  plateUrl: string;
+  plateRef: string;
+}
+
+export interface EnvironmentAssetsArtifact {
+  schemaVersion: 1;
+  projectSlug: string;
+  generatedAt: string;
+  environments: EnvironmentAssetEntry[];
+}
+
+export interface EnvironmentAssetsLookup {
+  environments: EnvironmentAssetEntry[];
+  /** name (lowercased) -> AssetTagEntry, ready for buildAssetTagLookup's environmentsByName. */
+  environmentEntryByName: Map<string, AssetTagEntry>;
+}
+
+export function environmentAssetsPathFor(root: string, slug: string): string {
+  return join(resolveProjectWorkspace(slug, root).projectDir, 'artifacts', 'environment-assets.json');
+}
+
+export async function writeEnvironmentAssets(
+  root: string,
+  slug: string,
+  artifact: EnvironmentAssetsArtifact,
+): Promise<void> {
+  const path = environmentAssetsPathFor(root, slug);
+  await mkdir(dirname(path), { recursive: true });
+  await writeTextFileAtomic(path, JSON.stringify(artifact, null, 2) + '\n');
+}
+
+/**
+ * Read `artifacts/environment-assets.json`. Returns an empty lookup when absent
+ * (graceful — `@location` tags then fall through to strip-and-warn). The
+ * `environmentEntryByName` map is the AssetTagEntry shape `buildAssetTagLookup`
+ * consumes via `environmentsByName`.
+ */
+export async function readEnvironmentAssets(root: string, slug: string): Promise<EnvironmentAssetsLookup> {
+  const path = environmentAssetsPathFor(root, slug);
+  if (!existsSync(path)) {
+    return { environments: [], environmentEntryByName: new Map() };
+  }
+  const parsed = JSON.parse(await readFile(path, 'utf-8')) as Partial<EnvironmentAssetsArtifact>;
+  const environments = Array.isArray(parsed.environments) ? parsed.environments : [];
+  const environmentEntryByName = new Map<string, AssetTagEntry>();
+  for (const env of environments) {
+    if (!env?.name) continue;
+    // Wire the HOSTED plate URL (public R2) as the reference — providers
+    // (seedance-direct etc.) require a real HTTP/HTTPS URL or Asset:// URI and
+    // reject the internal `gobananas://` plateRef. Fall back to plateRef only if
+    // no hosted URL was captured.
+    const referencePath = env.plateUrl || env.plateRef;
+    environmentEntryByName.set(env.name.toLowerCase(), {
+      descriptor: env.description ?? env.name,
+      ...(referencePath ? { referencePath } : {}),
+    });
+  }
+  return { environments, environmentEntryByName };
+}

package/src/video/environment-auto-create.ts

@@ -0,0 +1,122 @@
+import { writeEnvironmentAssets, type EnvironmentAssetEntry } from './environment-assets.js';
+import { ensureProjectWorkspace } from './workspace.js';
+
+// Go Bananas image generation for seamless empty environment/location plates —
+// the location half of the Asset-First Principle, mirroring character-auto-create.
+
+const DEFAULT_BASE_URL = 'https://gobananasai.com/api';
+const BROWSER_UA =
+  'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ' +
+  'AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36';
+
+export interface EnvironmentAutoCreateInput {
+  name: string;
+  description: string;
+  style?: string;
+}
+
+export interface EnvironmentAutoCreateResult {
+  imageUrl: string;
+  plateRef: string;
+  created: boolean;
+  persisted: boolean;
+}
+
+function authHeaders(apiKey: string): Record<string, string> {
+  return {
+    'X-API-Key': apiKey,
+    'Content-Type': 'application/json',
+    Accept: 'application/json',
+    'User-Agent': BROWSER_UA,
+  };
+}
+
+export function buildPlatePrompt(input: EnvironmentAutoCreateInput): string {
+  const stylePrefix = input.style?.trim() || 'photoreal cinematic establishing plate';
+  return `${stylePrefix} of ${input.description.trim()}, empty environment, no people, no characters, distraction-free, even neutral lighting, deep focus, high detail, consistent location design. No text, no watermarks.`;
+}
+
+async function generatePlateUrl(
+  input: EnvironmentAutoCreateInput,
+  apiKey: string,
+  apiUrl: string,
+): Promise<string> {
+  const response = await fetch(`${apiUrl}/images`, {
+    method: 'POST',
+    headers: authHeaders(apiKey),
+    body: JSON.stringify({
+      prompt: buildPlatePrompt(input),
+      aspect_ratio: '16:9',
+      model_id: 'gemini-pro-image',
+      enhance_prompt: false,
+      negative_prompt: 'people, person, face, text, watermark, logo, blurry, deformed',
+    }),
+  });
+  if (!response.ok) {
+    throw new Error(`POST /images failed: ${response.status} ${(await response.text()).slice(0, 200)}`);
+  }
+  const payload = await response.json() as {
+    url?: string;
+    image_url?: string;
+    data?: { url?: string; images?: Array<{ full_url?: string; url?: string }> };
+    images?: Array<{ full_url?: string; url?: string }>;
+  };
+  const imageUrl = payload.url
+    ?? payload.image_url
+    ?? payload.data?.url
+    ?? payload.data?.images?.[0]?.full_url
+    ?? payload.data?.images?.[0]?.url
+    ?? payload.images?.[0]?.full_url
+    ?? payload.images?.[0]?.url;
+  if (!imageUrl) {
+    throw new Error('POST /images succeeded but returned no image URL');
+  }
+  return imageUrl;
+}
+
+function plateRefFor(name: string): string {
+  const slug = name.trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+  return `gobananas://environment/${slug}`;
+}
+
+export async function autoCreateEnvironments(
+  inputs: EnvironmentAutoCreateInput[],
+  options?: { projectSlug?: string; root?: string; apiKey?: string; apiUrl?: string; dryRun?: boolean },
+): Promise<Record<string, EnvironmentAutoCreateResult>> {
+  const apiKey = options?.apiKey ?? process.env.GO_BANANAS_API_KEY ?? '';
+  if (!apiKey) {
+    throw new Error('GO_BANANAS_API_KEY is required for environment auto-create');
+  }
+  const apiUrl = (options?.apiUrl ?? process.env.GO_BANANAS_API_URL ?? DEFAULT_BASE_URL).trim();
+  const workspace = options?.projectSlug
+    ? await ensureProjectWorkspace(options.projectSlug, options.root ?? process.cwd())
+    : null;
+  const results: Record<string, EnvironmentAutoCreateResult> = {};
+  const persistedEntries: EnvironmentAssetEntry[] = [];
+
+  for (const input of inputs) {
+    const name = input.name.trim();
+    const description = input.description.trim();
+    if (!name || !description) {
+      continue;
+    }
+    if (options?.dryRun) {
+      results[name] = { imageUrl: '', plateRef: plateRefFor(name), created: true, persisted: false };
+      continue;
+    }
+    const imageUrl = await generatePlateUrl(input, apiKey, apiUrl);
+    const plateRef = plateRefFor(name);
+    persistedEntries.push({ name, description, plateUrl: imageUrl, plateRef });
+    results[name] = { imageUrl, plateRef, created: true, persisted: Boolean(workspace) };
+  }
+
+  if (workspace && persistedEntries.length > 0 && options?.projectSlug) {
+    await writeEnvironmentAssets(options.root ?? process.cwd(), options.projectSlug, {
+      schemaVersion: 1,
+      projectSlug: options.projectSlug,
+      generatedAt: new Date().toISOString(),
+      environments: persistedEntries,
+    });
+  }
+  return results;
+}

package/src/video/errors.ts

@@ -0,0 +1,133 @@
+/**
+ * Stable error codes for vclaw CLI output.
+ *
+ * The TS enum + the JSON catalog at schemas/video/errors.json are kept in
+ * sync by a test in cli-errors.test.ts. Add codes here AND in the JSON.
+ *
+ * Conventions:
+ * - snake_case
+ * - Specific over generic (prefer "image_not_found" over "not_found")
+ * - Stable: never rename a code once shipped; deprecate and add a new one
+ */
+export const ALL_ERROR_CODES = [
+  // User-input errors (exit code 1)
+  'invalid_slug',
+  'project_not_found',
+  'missing_required_flag',
+  'invalid_flag_value',
+  'unknown_subcommand',
+  'invalid_mode',
+  'invalid_aspect_ratio',
+  'image_not_found',
+  'asset_not_found',
+  'template_not_found',
+  'character_not_found',
+  'duplicate_project',
+  'directory_not_writable',
+  'invalid_role',
+  'invalid_audio_format',
+  'invalid_video_format',
+  'unsupported_codec',
+
+  // System errors (exit code 2)
+  'provider_unreachable',
+  'adapter_command_failed',
+  'env_var_missing',
+  'native_transport_failed',
+  'schema_validation_failed',
+  'workspace_corrupt',
+  'unexpected_internal_error',
+  'tts_failed',
+  'music_gen_failed',
+  'soundtrack_no_backend',
+  'pdf_parse_failed',
+  'ffmpeg_failed',
+  'audio_sync_drift',
+
+  // Gates (exit code 3)
+  'storyboard_approval_required',
+  'storyboard_review_stale',
+  'execution_blocked_by_readiness',
+  'spend_confirmation_required',
+] as const;
+
+export type ErrorCode = typeof ALL_ERROR_CODES[number];
+
+/**
+ * Maps each ErrorCode to its CLI exit code (1=user, 2=system, 3=gate).
+ * Stays in sync with schemas/video/errors.json via the catalog test.
+ */
+export const EXIT_CODES: Record<ErrorCode, 1 | 2 | 3> = {
+  // User-input errors (1)
+  invalid_slug: 1,
+  project_not_found: 1,
+  missing_required_flag: 1,
+  invalid_flag_value: 1,
+  unknown_subcommand: 1,
+  invalid_mode: 1,
+  invalid_aspect_ratio: 1,
+  image_not_found: 1,
+  asset_not_found: 1,
+  template_not_found: 1,
+  character_not_found: 1,
+  duplicate_project: 1,
+  directory_not_writable: 1,
+  invalid_role: 1,
+  invalid_audio_format: 1,
+  invalid_video_format: 1,
+  unsupported_codec: 1,
+  // System errors (2)
+  provider_unreachable: 2,
+  adapter_command_failed: 2,
+  env_var_missing: 2,
+  native_transport_failed: 2,
+  schema_validation_failed: 2,
+  workspace_corrupt: 2,
+  unexpected_internal_error: 2,
+  tts_failed: 2,
+  music_gen_failed: 2,
+  soundtrack_no_backend: 2,
+  pdf_parse_failed: 2,
+  ffmpeg_failed: 2,
+  audio_sync_drift: 2,
+  // Gates (3)
+  storyboard_approval_required: 3,
+  storyboard_review_stale: 3,
+  execution_blocked_by_readiness: 3,
+  spend_confirmation_required: 3,
+};
+
+export function exitCodeFor(code: ErrorCode): 1 | 2 | 3 {
+  return EXIT_CODES[code];
+}
+
+export interface ErrorResponse {
+  code: ErrorCode;
+  message: string;
+  details?: Record<string, unknown>;
+}
+
+export function errorResponse(
+  code: ErrorCode,
+  message: string,
+  details?: Record<string, unknown>,
+): ErrorResponse {
+  const out: ErrorResponse = { code, message };
+  if (details !== undefined) out.details = details;
+  return out;
+}
+
+/**
+ * Throwable error that carries an ErrorCode. The top-level main() catch in
+ * vclaw.ts unwraps VclawError into an ErrorResponse + appropriate ExitCode.
+ */
+export class VclawError extends Error {
+  readonly code: ErrorCode;
+  readonly details?: Record<string, unknown>;
+  constructor(code: ErrorCode, message: string, details?: Record<string, unknown>) {
+    super(message);
+    this.name = 'VclawError';
+    this.code = code;
+    this.details = details;
+  }
+}

package/src/video/events.ts

@@ -0,0 +1,42 @@
+import { appendFile, readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import type { VideoProjectWorkspace } from './workspace.js';
+
+export interface VideoProjectEvent {
+  type: string;
+  recordedAt: string;
+  payload?: Record<string, unknown>;
+}
+
+export async function appendProjectEvent(
+  workspace: VideoProjectWorkspace,
+  event: Omit<VideoProjectEvent, 'recordedAt'> & { recordedAt?: string },
+): Promise<void> {
+  const record: VideoProjectEvent = {
+    ...event,
+    recordedAt: event.recordedAt ?? new Date().toISOString(),
+  };
+  await appendFile(workspace.eventsPath, `${JSON.stringify(record)}\n`);
+}
+
+export async function readProjectEvents(
+  workspace: VideoProjectWorkspace,
+): Promise<VideoProjectEvent[]> {
+  if (!existsSync(workspace.eventsPath)) return [];
+  const raw = await readFile(workspace.eventsPath, 'utf-8');
+  const events: VideoProjectEvent[] = [];
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      events.push(JSON.parse(trimmed) as VideoProjectEvent);
+    } catch {
+      // Append-only logs can be left with a torn line when a writer is
+      // interrupted or a concurrent append exceeds the atomic-write size
+      // (PIPE_BUF). One bad line must not poison the whole timeline that
+      // status/report/obsidian-export consume — skip it and keep the rest.
+      continue;
+    }
+  }
+  return events;
+}

package/src/video/execute-autochain.ts

@@ -0,0 +1,226 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { resolveProjectWorkspace } from './workspace.js';
+import { readSceneSelectionArtifact, writeSceneSelectionArtifact } from './scene-selection-store.js';
+import { readSceneCandidatesArtifact } from './scene-candidate-store.js';
+import { selectCandidate, setChainFromPrev, setChainFromSource } from './scene-selection.js';
+import { executeProject } from './execute.js';
+import { refreshExecutionStatus } from './execution-status.js';
+import { planChainFallbackLadder, describeChainSource, type ChainSource } from './chain-fallback.js';
+import type { SceneCandidatesArtifact, VideoExecutionReport, VideoProductionMode } from './types.js';
+
+export type AutoChainSceneRunner = (
+  sceneIndex: number,
+) => Promise<{ report: VideoExecutionReport; reportPath: string }>;
+
+export interface AutoChainOptions {
+  root: string;
+  productionMode?: VideoProductionMode;
+  /** Ordered subset of scene indices. When omitted, read from the storyboard. */
+  sceneIndices?: number[];
+  /** Injectable per-scene runner (tests). Defaults to a single-scene executeProject call. */
+  runScene?: AutoChainSceneRunner;
+  /**
+   * Opt-in fallback ladder. When a chained scene produces no usable candidate
+   * (e.g. the provider rejected its video reference — Seedance RejectFace),
+   * retry it down the ladder: chain-from-prev → chain-from-anchor → image-only,
+   * instead of fail-fast stopping. Default off → byte-identical fail-fast.
+   */
+  chainFallback?: boolean;
+}
+
+export interface AutoChainSceneResult {
+  sceneIndex: number;
+  chainedFrom: number | null;
+  selectedCandidateId: string | null;
+  status: 'completed' | 'failed';
+  /** Set when the fallback ladder used a non-default chain source (e.g. 'chain-from-0', 'image-only'). */
+  fallback?: string;
+}
+
+export interface AutoChainReport {
+  schemaVersion: 1;
+  projectSlug: string;
+  mode: 'auto-chain';
+  scenes: AutoChainSceneResult[];
+  stoppedAt: number | null;
+}
+
+async function readStoryboardSceneOrder(root: string, projectSlug: string): Promise<number[]> {
+  const workspace = resolveProjectWorkspace(projectSlug, root);
+  const path = join(workspace.artifactsDir, 'storyboard.json');
+  if (!existsSync(path)) {
+    throw new Error(`auto-chain: storyboard artifact not found for "${projectSlug}". Run storyboard first.`);
+  }
+  const parsed = JSON.parse(await readFile(path, 'utf-8')) as { scenes?: Array<{ sceneIndex?: number }> };
+  return (parsed.scenes ?? []).map((s, i) => s.sceneIndex ?? i).sort((a, b) => a - b);
+}
+
+const DEFAULT_POLL_INTERVAL_MS = 15_000;
+const DEFAULT_MAX_POLL_ATTEMPTS = 60; // ~15 min/scene at 15s
+
+function candidatesHaveVideo(candidates: SceneCandidatesArtifact, sceneIndex: number): boolean {
+  const scene = candidates.scenes.find((s) => s.sceneIndex === sceneIndex);
+  return !!scene && scene.candidates.some((c) => (c.outputs ?? []).some((o) => o.kind === 'video'));
+}
+
+/**
+ * Poll a just-submitted scene to completion. On async routes (e.g.
+ * seedance-direct) `executeProject` returns after SUBMIT — the render finishes
+ * later via polling — so auto-chain MUST wait for the scene's candidate to gain
+ * a video output before the next scene can chain from it (otherwise the chain
+ * seed resolves to a video-less candidate and `chain-from-prev-source-missing`
+ * fires). Returns true once a video output exists; false if the job fails or the
+ * attempts are exhausted. Dependencies are injectable for offline tests.
+ */
+export async function waitForSceneVideo(
+  projectSlug: string,
+  sceneIndex: number,
+  deps: {
+    root: string;
+    productionMode?: VideoProductionMode;
+    refresh?: typeof refreshExecutionStatus;
+    readCandidates?: typeof readSceneCandidatesArtifact;
+    sleep?: (ms: number) => Promise<void>;
+    intervalMs?: number;
+    maxAttempts?: number;
+  },
+): Promise<boolean> {
+  const refresh = deps.refresh ?? refreshExecutionStatus;
+  const readCandidates = deps.readCandidates ?? readSceneCandidatesArtifact;
+  const sleep = deps.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)));
+  const intervalMs = deps.intervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+  const maxAttempts = deps.maxAttempts ?? DEFAULT_MAX_POLL_ATTEMPTS;
+
+  if (candidatesHaveVideo(await readCandidates(deps.root, projectSlug), sceneIndex)) return true;
+  for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+    const status = await refresh(projectSlug, { root: deps.root, productionMode: deps.productionMode });
+    if (candidatesHaveVideo(await readCandidates(deps.root, projectSlug), sceneIndex)) return true;
+    if (status.poll.status === 'failed') return false;
+    await sleep(intervalMs);
+  }
+  return candidatesHaveVideo(await readCandidates(deps.root, projectSlug), sceneIndex);
+}
+
+function defaultRunScene(projectSlug: string, options: AutoChainOptions): AutoChainSceneRunner {
+  return async (sceneIndex) => {
+    const result = await executeProject(projectSlug, {
+      root: options.root,
+      productionMode: options.productionMode,
+      sceneIndices: [sceneIndex],
+      continuityFeedback: true, // bundled — locked during brainstorming
+    });
+    // Async submit-only routes (seedance-direct etc.): wait for the render to
+    // finish + download so the scene's candidate gains a video output before the
+    // next scene chains from it. Synchronous/dry paths skip this.
+    if (result.report.status === 'live-submitted') {
+      const rendered = await waitForSceneVideo(projectSlug, sceneIndex, {
+        root: options.root,
+        productionMode: options.productionMode,
+      });
+      if (!rendered) {
+        // Render never produced a video → signal failure (no usable candidate).
+        return { report: { ...result.report, candidatesByScene: [] }, reportPath: result.reportPath };
+      }
+    }
+    return result;
+  };
+}
+
+/**
+ * Drive the existing chain-from-prev engine across a whole storyboard,
+ * unattended. Renders scenes sequentially; each scene after the first seeds
+ * from the previous scene's auto-selected output video (chainFromPrev) with
+ * continuity prompt-augmentation bundled in. Resumable (skips scenes that
+ * already have a selection) and fail-fast (halts at the first scene that yields
+ * no usable candidate, recording stoppedAt).
+ */
+export async function runAutoChain(
+  projectSlug: string,
+  options: AutoChainOptions,
+): Promise<AutoChainReport> {
+  const root = options.root;
+  const sceneOrder = options.sceneIndices ?? (await readStoryboardSceneOrder(root, projectSlug));
+  const runScene = options.runScene ?? defaultRunScene(projectSlug, options);
+  const scenes: AutoChainSceneResult[] = [];
+  let stoppedAt: number | null = null;
+
+  for (let i = 0; i < sceneOrder.length; i += 1) {
+    const sceneIndex = sceneOrder[i];
+    const chainedFrom = i > 0 ? sceneOrder[i - 1] : null;
+
+    // Resume: a scene that already has a selected candidate is left as-is.
+    let selection = await readSceneSelectionArtifact(root, projectSlug);
+    const existing = selection.scenes.find((s) => s.sceneIndex === sceneIndex);
+    if (existing?.selectedCandidateId) {
+      scenes.push({ sceneIndex, chainedFrom, selectedCandidateId: existing.selectedCandidateId, status: 'completed' });
+      continue;
+    }
+
+    // Chain rungs to try, in order. First scene: no chain. Non-first scene:
+    // a single chain-from-prev rung (legacy fail-fast) unless `chainFallback`
+    // is on, which walks the full ladder so a rejected video reference doesn't
+    // stop the whole chain.
+    const rungs: ChainSource[] = i === 0
+      ? [{ kind: 'image-only' }]
+      : options.chainFallback
+        ? planChainFallbackLadder({ positionInOrder: i, sceneOrder })
+        : [{ kind: 'chain', sourceSceneIndex: sceneIndex - 1 }];
+
+    let produced: { sceneIndex: number; candidateId: string } | undefined;
+    let usedRung: ChainSource | null = null;
+    let hardError = false;
+
+    for (const rung of rungs) {
+      if (i > 0) {
+        // Apply the rung's chain source. `chain-from-(sceneIndex-1)` uses the
+        // legacy flag (no explicit pin → byte-identical); an earlier anchor pins
+        // `chainFromSceneIndex`; image-only clears the chain seed.
+        let next = await readSceneSelectionArtifact(root, projectSlug);
+        next = rung.kind === 'image-only'
+          ? setChainFromPrev(next, sceneIndex, false)
+          : rung.sourceSceneIndex === sceneIndex - 1
+            ? setChainFromPrev(next, sceneIndex, true)
+            : setChainFromSource(next, sceneIndex, rung.sourceSceneIndex);
+        await writeSceneSelectionArtifact(root, projectSlug, next);
+      }
+
+      let stepReport: VideoExecutionReport;
+      try {
+        ({ report: stepReport } = await runScene(sceneIndex));
+      } catch {
+        hardError = true; // a thrown error is a hard failure — stop laddering
+        break;
+      }
+      const got = (stepReport.candidatesByScene ?? []).find((c) => c.sceneIndex === sceneIndex);
+      if (got) { produced = got; usedRung = rung; break; }
+      // else: this rung produced no usable candidate → try the next rung
+    }
+
+    if (hardError || !produced) {
+      scenes.push({ sceneIndex, chainedFrom, selectedCandidateId: null, status: 'failed' });
+      stoppedAt = sceneIndex;
+      break;
+    }
+
+    // Auto-select so the next scene's chain seed resolves.
+    selection = await readSceneSelectionArtifact(root, projectSlug);
+    selection = selectCandidate(selection, sceneIndex, produced.candidateId);
+    await writeSceneSelectionArtifact(root, projectSlug, selection);
+
+    // Record the fallback label only when a non-default chain source was used.
+    const fallbackLabel = i > 0 && usedRung && describeChainSource(usedRung) !== `chain-from-${sceneIndex - 1}`
+      ? describeChainSource(usedRung)
+      : undefined;
+    scenes.push({
+      sceneIndex,
+      chainedFrom,
+      selectedCandidateId: produced.candidateId,
+      status: 'completed',
+      ...(fallbackLabel ? { fallback: fallbackLabel } : {}),
+    });
+  }
+
+  return { schemaVersion: 1, projectSlug, mode: 'auto-chain', scenes, stoppedAt };
+}