videoclaw 3.0.0-alpha.1

package/src/video/storyboard-templates.ts

@@ -0,0 +1,249 @@
+export interface StoryboardPanelTemplate {
+  sceneIndex: number;
+  shotType: string;
+  purpose: string;
+  descriptionTemplate: string;
+}
+
+export interface StoryboardTemplate {
+  id: string;
+  name: string;
+  description: string;
+  emotionalArc: string;
+  bestFor: string[];
+  minCharacters: number;
+  panels: StoryboardPanelTemplate[];
+}
+
+export interface BuildStoryboardFromTemplateInput {
+  templateId: string;
+  environment?: string;
+  characterA?: string;
+  characterB?: string;
+}
+
+function fillTemplate(
+  template: string,
+  input: { environment: string; characterA: string; characterB: string },
+): string {
+  return template
+    .replaceAll('{environment}', input.environment)
+    .replaceAll('{characterA}', input.characterA)
+    .replaceAll('{characterB}', input.characterB);
+}
+
+const STORYBOARD_TEMPLATES: StoryboardTemplate[] = [
+  {
+    id: 'dialogue-confrontation',
+    name: 'Dialogue Confrontation',
+    description: 'Two-character tension build with decision-point coverage.',
+    emotionalArc: 'Tension -> breaking point -> resolution',
+    bestFor: ['arguments', 'negotiations', 'dramatic conversations', 'decisions'],
+    minCharacters: 2,
+    panels: [
+      { sceneIndex: 0, shotType: 'wide establishing', purpose: 'context', descriptionTemplate: 'Wide establishing shot of {characterA} and {characterB} in {environment}, emphasizing distance and tension.' },
+      { sceneIndex: 1, shotType: 'medium A', purpose: 'state', descriptionTemplate: 'Medium shot on {characterA}, posture tense, eyes fixed on {characterB} in {environment}.' },
+      { sceneIndex: 2, shotType: 'medium B', purpose: 'counterpoint', descriptionTemplate: 'Medium shot on {characterB}, guarded and uncertain, framed against {environment}.' },
+      { sceneIndex: 3, shotType: 'close A', purpose: 'reaction', descriptionTemplate: 'Tight close-up on {characterA} as emotion breaks through restraint.' },
+      { sceneIndex: 4, shotType: 'insert', purpose: 'symbol', descriptionTemplate: 'Insert shot of a symbolic object or environmental detail in {environment} that sharpens the conflict.' },
+      { sceneIndex: 5, shotType: 'close B', purpose: 'counter-reaction', descriptionTemplate: 'Tight close-up on {characterB} processing the stakes of the confrontation.' },
+      { sceneIndex: 6, shotType: 'high wide', purpose: 'stakes', descriptionTemplate: 'High-angle wide shot of both characters in {environment}, making them feel small against the stakes.' },
+      { sceneIndex: 7, shotType: 'two-shot', purpose: 'dynamic', descriptionTemplate: 'Two-shot of {characterA} and {characterB} with visible space and unresolved tension between them.' },
+      { sceneIndex: 8, shotType: 'wide exit', purpose: 'resolution', descriptionTemplate: 'Wide resolution shot of one or both characters moving forward, leaving something behind in {environment}.' },
+    ],
+  },
+  {
+    id: 'chase-pursuit',
+    name: 'Chase Pursuit',
+    description: 'Urgent motion language for pursuit, escape, or physical race sequences.',
+    emotionalArc: 'Urgency -> escalation -> climax',
+    bestFor: ['escapes', 'races', 'being followed', 'physical conflict'],
+    minCharacters: 1,
+    panels: [
+      { sceneIndex: 0, shotType: 'wide establishing', purpose: 'arena', descriptionTemplate: 'Wide establishing shot of the chase arena in {environment}, with {characterA} already in motion.' },
+      { sceneIndex: 1, shotType: 'tracking medium', purpose: 'momentum', descriptionTemplate: 'Tracking medium shot beside {characterA} sprinting through {environment} with visible urgency.' },
+      { sceneIndex: 2, shotType: 'over-shoulder', purpose: 'threat', descriptionTemplate: 'Over-shoulder shot from {characterA} looking back at the threat or pursuer gaining ground in {environment}.' },
+      { sceneIndex: 3, shotType: 'detail close-up', purpose: 'strain', descriptionTemplate: 'Detail close-up of feet, hands, or impact points showing the physical strain of the chase.' },
+      { sceneIndex: 4, shotType: 'insert', purpose: 'obstacle', descriptionTemplate: 'Insert shot of a critical obstacle or goal object that defines the next beat of the chase.' },
+      { sceneIndex: 5, shotType: 'face close-up', purpose: 'fear', descriptionTemplate: 'Tight close-up of {characterA} showing fear, exhaustion, or determination.' },
+      { sceneIndex: 6, shotType: 'low angle', purpose: 'pressure', descriptionTemplate: 'Low-angle shot that makes the pursuing force or danger feel dominant and inescapable.' },
+      { sceneIndex: 7, shotType: 'action two-shot', purpose: 'near catch', descriptionTemplate: 'Action two-shot where {characterA} and the threat nearly collide or the gap narrows dramatically.' },
+      { sceneIndex: 8, shotType: 'wide resolution', purpose: 'outcome', descriptionTemplate: 'Wide outcome shot showing whether {characterA} escapes, is cornered, or enters the next danger zone.' },
+    ],
+  },
+  {
+    id: 'discovery-reveal',
+    name: 'Discovery Reveal',
+    description: 'Mystery and reveal structure for secrets, twists, or important finds.',
+    emotionalArc: 'Mystery -> investigation -> revelation',
+    bestFor: ['finding something', 'plot twists', 'mysteries', 'secret reveals'],
+    minCharacters: 1,
+    panels: [
+      { sceneIndex: 0, shotType: 'wide establishing', purpose: 'mystery setup', descriptionTemplate: 'Wide shot of {characterA} entering {environment}, with an unsettling or mysterious tone.' },
+      { sceneIndex: 1, shotType: 'medium search', purpose: 'investigation', descriptionTemplate: 'Medium shot of {characterA} moving through {environment}, actively searching for clues.' },
+      { sceneIndex: 2, shotType: 'reaction close-up', purpose: 'notice detail', descriptionTemplate: 'Close-up of {characterA} noticing something unexpected or out of place.' },
+      { sceneIndex: 3, shotType: 'POV approach', purpose: 'approach', descriptionTemplate: 'Point-of-view style shot approaching the source of the mystery in {environment}.' },
+      { sceneIndex: 4, shotType: 'insert reveal', purpose: 'reveal', descriptionTemplate: 'Insert reveal of the crucial object, clue, or secret that changes the scene.' },
+      { sceneIndex: 5, shotType: 'extreme close-up', purpose: 'impact', descriptionTemplate: 'Extreme close-up of {characterA} as the meaning of the reveal lands emotionally.' },
+      { sceneIndex: 6, shotType: 'wide context', purpose: 'implications', descriptionTemplate: 'Wide context shot of {characterA} with the discovery, showing how it changes the room or situation.' },
+      { sceneIndex: 7, shotType: 'decision medium', purpose: 'decision', descriptionTemplate: 'Medium shot of {characterA} making a new decision after the reveal.' },
+      { sceneIndex: 8, shotType: 'wide departure', purpose: 'new trajectory', descriptionTemplate: 'Wide departure shot showing {characterA} leaving {environment} with new purpose.' },
+    ],
+  },
+  {
+    id: 'product-story',
+    name: 'Product Story',
+    description: 'Problem-solution commercial structure centered on discovering and using a product.',
+    emotionalArc: 'Problem -> discovery -> transformation',
+    bestFor: ['commercials', 'product narratives', 'before/after', 'testimonials'],
+    minCharacters: 1,
+    panels: [
+      { sceneIndex: 0, shotType: 'wide problem', purpose: 'pain point', descriptionTemplate: 'Wide shot of {characterA} struggling with a clear problem in {environment}.' },
+      { sceneIndex: 1, shotType: 'close frustration', purpose: 'emotion', descriptionTemplate: 'Close-up on {characterA} showing frustration, inconvenience, or fatigue.' },
+      { sceneIndex: 2, shotType: 'insert product', purpose: 'introduction', descriptionTemplate: 'Clean insert shot revealing the product that may solve the problem.' },
+      { sceneIndex: 3, shotType: 'medium discovery', purpose: 'discovery', descriptionTemplate: 'Medium shot of {characterA} discovering or picking up the product in {environment}.' },
+      { sceneIndex: 4, shotType: 'detail use', purpose: 'usage detail', descriptionTemplate: 'Detail shot of hands interacting with the product in a clear, readable way.' },
+      { sceneIndex: 5, shotType: 'medium use', purpose: 'active use', descriptionTemplate: 'Medium shot of {characterA} actively using the product with confidence.' },
+      { sceneIndex: 6, shotType: 'close satisfaction', purpose: 'benefit', descriptionTemplate: 'Close-up on {characterA} as the benefit lands and satisfaction becomes visible.' },
+      { sceneIndex: 7, shotType: 'wide transformed', purpose: 'after state', descriptionTemplate: 'Wide shot of {characterA} in an improved situation made possible by the product.' },
+      { sceneIndex: 8, shotType: 'hero finale', purpose: 'finish', descriptionTemplate: 'Hero finale shot of the product and {characterA}, clean and campaign-ready.' },
+    ],
+  },
+  {
+    id: 'beat-structure-3',
+    name: 'Beat Structure — 3 scene',
+    description: 'Minimal Establish → Develop → Payoff beat structure for short-form narrative and ads (Seedance handbook beat structure).',
+    emotionalArc: 'Setup → escalation → resolution',
+    bestFor: ['short ads', 'social cuts', 'quick narratives', 'one-take stories', 'punchlines'],
+    minCharacters: 1,
+    panels: [
+      { sceneIndex: 0, shotType: 'establish', purpose: 'establish', descriptionTemplate: 'Establish: wide or medium shot that introduces {characterA} and the situation in {environment}.' },
+      { sceneIndex: 1, shotType: 'develop', purpose: 'develop', descriptionTemplate: 'Develop: medium or close shot that escalates the situation — a meaningful change in stakes, action, or intent for {characterA} in {environment}.' },
+      { sceneIndex: 2, shotType: 'payoff', purpose: 'payoff', descriptionTemplate: 'Payoff: the shot that delivers the outcome, reveal, or emotional landing — clean and readable.' },
+    ],
+  },
+  {
+    id: 'beat-structure-6',
+    name: 'Beat Structure — 6 scene',
+    description: 'Two shots per beat — Establish / Develop / Payoff — for mid-length narrative, educational explainers, and product sequences (Seedance handbook beat structure).',
+    emotionalArc: 'Setup → escalation → resolution with breathing room',
+    bestFor: ['explainers', 'product launches', 'transformations', 'before/after', 'educational sequences'],
+    minCharacters: 1,
+    panels: [
+      { sceneIndex: 0, shotType: 'establish wide', purpose: 'establish-context', descriptionTemplate: 'Establish wide: context shot of {characterA} in {environment}, introducing the situation.' },
+      { sceneIndex: 1, shotType: 'establish detail', purpose: 'establish-detail', descriptionTemplate: 'Establish detail: medium or insert shot anchoring the specific element, object, or intent {characterA} is focused on.' },
+      { sceneIndex: 2, shotType: 'develop action', purpose: 'develop-action', descriptionTemplate: 'Develop action: medium shot of {characterA} taking the meaningful action that changes the situation in {environment}.' },
+      { sceneIndex: 3, shotType: 'develop consequence', purpose: 'develop-consequence', descriptionTemplate: 'Develop consequence: close-up or detail showing the immediate consequence of the action — visible change, reaction, or progress.' },
+      { sceneIndex: 4, shotType: 'payoff reveal', purpose: 'payoff-reveal', descriptionTemplate: 'Payoff reveal: the moment the outcome lands — clean and readable, framed for maximum impact.' },
+      { sceneIndex: 5, shotType: 'payoff resolve', purpose: 'payoff-resolve', descriptionTemplate: 'Payoff resolve: final shot of {characterA} in the new state, closing the beat structure.' },
+    ],
+  },
+  {
+    id: 'product-commercial-4',
+    name: 'Product Commercial — 4 scene',
+    description: 'Compact problem, product, use, payoff structure for short commercials.',
+    emotionalArc: 'Need -> reveal -> proof -> desire',
+    bestFor: ['short ads', 'launch teasers', 'UGC product spots', 'before/after'],
+    minCharacters: 1,
+    panels: [
+      { sceneIndex: 0, shotType: 'problem hook', purpose: 'need', descriptionTemplate: 'Problem hook: {characterA} faces one clear friction point in {environment}, readable in a single action.' },
+      { sceneIndex: 1, shotType: 'product reveal', purpose: 'reveal', descriptionTemplate: 'Product reveal: clean hero shot of the product entering frame with simple, premium composition.' },
+      { sceneIndex: 2, shotType: 'usage proof', purpose: 'proof', descriptionTemplate: 'Usage proof: {characterA} uses the product once in {environment}, with the benefit visible on screen.' },
+      { sceneIndex: 3, shotType: 'payoff hero', purpose: 'desire', descriptionTemplate: 'Payoff hero: final product-and-person shot showing the improved state, confident and uncluttered.' },
+    ],
+  },
+  {
+    id: 'food-tutorial-6',
+    name: 'Food Tutorial — 6 scene',
+    description: 'Stepwise ingredient, action, transformation, and final bite template.',
+    emotionalArc: 'Curiosity -> method -> appetite',
+    bestFor: ['recipe clips', 'cooking tutorials', 'food prep', 'creator shorts'],
+    minCharacters: 1,
+    panels: [
+      { sceneIndex: 0, shotType: 'ingredient overview', purpose: 'setup', descriptionTemplate: 'Ingredient overview: organized food and tools in {environment}, with {characterA} ready to begin.' },
+      { sceneIndex: 1, shotType: 'prep detail', purpose: 'prep', descriptionTemplate: 'Prep detail: hands complete one clear prep action, framed close enough to understand the technique.' },
+      { sceneIndex: 2, shotType: 'mix or season', purpose: 'method', descriptionTemplate: 'Mix or season: {characterA} adds flavor or combines ingredients with visible texture and motion.' },
+      { sceneIndex: 3, shotType: 'heat transformation', purpose: 'transformation', descriptionTemplate: 'Heat transformation: cooking action shows steam, sizzle, melt, or color change in {environment}.' },
+      { sceneIndex: 4, shotType: 'plate reveal', purpose: 'reveal', descriptionTemplate: 'Plate reveal: finished dish appears cleanly arranged, with the most appetizing detail in focus.' },
+      { sceneIndex: 5, shotType: 'taste payoff', purpose: 'payoff', descriptionTemplate: 'Taste payoff: {characterA} reacts naturally after one bite, closing on satisfaction and food texture.' },
+    ],
+  },
+  {
+    id: 'dance-social-6',
+    name: 'Dance Social — 6 scene',
+    description: 'Rhythmic short-form dance structure with hook, moves, and loopable finish.',
+    emotionalArc: 'Anticipation -> energy -> replay',
+    bestFor: ['dance trends', 'music promos', 'social shorts', 'creator choreography'],
+    minCharacters: 1,
+    panels: [
+      { sceneIndex: 0, shotType: 'pose hook', purpose: 'hook', descriptionTemplate: 'Pose hook: {characterA} holds a distinct starting pose in {environment}, ready for the beat to drop.' },
+      { sceneIndex: 1, shotType: 'first move', purpose: 'launch', descriptionTemplate: 'First move: {characterA} starts the choreography with one bold, readable movement.' },
+      { sceneIndex: 2, shotType: 'footwork detail', purpose: 'precision', descriptionTemplate: 'Footwork detail: close framing highlights rhythm, steps, and clean timing without changing the setting.' },
+      { sceneIndex: 3, shotType: 'signature move', purpose: 'identity', descriptionTemplate: 'Signature move: {characterA} performs the most memorable gesture or transition in {environment}.' },
+      { sceneIndex: 4, shotType: 'energy lift', purpose: 'escalation', descriptionTemplate: 'Energy lift: movement becomes bigger and more expressive while the framing stays easy to follow.' },
+      { sceneIndex: 5, shotType: 'loop finish', purpose: 'replay', descriptionTemplate: 'Loop finish: {characterA} lands on a final pose that can cut smoothly back to the opening.' },
+    ],
+  },
+  {
+    id: 'dramatic-short-6',
+    name: 'Dramatic Short — 6 scene',
+    description: 'Concise emotional scene with reveal, choice, and aftermath.',
+    emotionalArc: 'Unease -> confrontation -> consequence',
+    bestFor: ['micro drama', 'character moments', 'twists', 'relationship tension'],
+    minCharacters: 1,
+    panels: [
+      { sceneIndex: 0, shotType: 'quiet establish', purpose: 'setup', descriptionTemplate: 'Quiet establish: {characterA} enters {environment}, with tension visible in posture and silence.' },
+      { sceneIndex: 1, shotType: 'important detail', purpose: 'clue', descriptionTemplate: 'Important detail: close shot of the object, message, or gesture that changes the emotional stakes.' },
+      { sceneIndex: 2, shotType: 'reaction close-up', purpose: 'reaction', descriptionTemplate: 'Reaction close-up: {characterA} absorbs the discovery, holding emotion in the face and eyes.' },
+      { sceneIndex: 3, shotType: 'decision beat', purpose: 'choice', descriptionTemplate: 'Decision beat: {characterA} takes one decisive action in {environment}, shifting the scene forward.' },
+      { sceneIndex: 4, shotType: 'confrontation', purpose: 'pressure', descriptionTemplate: 'Confrontation: {characterA} faces {characterB} or the consequence directly, with clear spatial tension.' },
+      { sceneIndex: 5, shotType: 'aftermath', purpose: 'landing', descriptionTemplate: 'Aftermath: final quiet image shows what changed for {characterA}, restrained and emotionally legible.' },
+    ],
+  },
+  {
+    id: 'action-short-6',
+    name: 'Action Short — 6 scene',
+    description: 'Fast physical sequence with setup, obstacle, impact, and escape beat.',
+    emotionalArc: 'Threat -> acceleration -> release',
+    bestFor: ['action teasers', 'stunts', 'sports clips', 'escape scenes'],
+    minCharacters: 1,
+    panels: [
+      { sceneIndex: 0, shotType: 'threat setup', purpose: 'stakes', descriptionTemplate: 'Threat setup: {characterA} spots the danger or objective in {environment}, with stakes clear immediately.' },
+      { sceneIndex: 1, shotType: 'launch move', purpose: 'start', descriptionTemplate: 'Launch move: {characterA} commits to one fast physical action, framed for direction and momentum.' },
+      { sceneIndex: 2, shotType: 'obstacle beat', purpose: 'obstacle', descriptionTemplate: 'Obstacle beat: the path is blocked by a visible barrier, rival, or hazard in {environment}.' },
+      { sceneIndex: 3, shotType: 'impact detail', purpose: 'intensity', descriptionTemplate: 'Impact detail: close shot of contact, landing, grip, or equipment strain that sells the action safely.' },
+      { sceneIndex: 4, shotType: 'near miss', purpose: 'climax', descriptionTemplate: 'Near miss: {characterA} barely clears the danger or closes the distance with precise timing.' },
+      { sceneIndex: 5, shotType: 'escape wide', purpose: 'release', descriptionTemplate: 'Escape wide: final wide shot shows {characterA} reaching a new position or surviving the beat.' },
+    ],
+  },
+];
+
+export function listStoryboardTemplates(): StoryboardTemplate[] {
+  return STORYBOARD_TEMPLATES;
+}
+
+export function readStoryboardTemplate(id: string): StoryboardTemplate | null {
+  return STORYBOARD_TEMPLATES.find((template) => template.id === id) ?? null;
+}
+
+export function buildStoryboardScenesFromTemplate(
+  input: BuildStoryboardFromTemplateInput,
+): Array<{ sceneIndex: number; description: string }> {
+  const template = readStoryboardTemplate(input.templateId);
+  if (!template) {
+    throw new Error(`Storyboard template "${input.templateId}" not found.`);
+  }
+
+  const environment = input.environment?.trim() || 'a cinematic environment';
+  const characterA = input.characterA?.trim() || 'Character A';
+  const characterB = input.characterB?.trim() || 'Character B';
+
+  return template.panels.map((panel) => ({
+    sceneIndex: panel.sceneIndex,
+    description: fillTemplate(panel.descriptionTemplate, {
+      environment,
+      characterA,
+      characterB,
+    }),
+  }));
+}

package/src/video/studio/execute.ts

@@ -0,0 +1,401 @@
+/**
+ * Studio execution — a dry-by-default step runner for `vclaw studio --execute`.
+ *
+ * Studio's planner stays the source of truth: it emits a `StudioPlan` whose
+ * steps are fully-resolved `vclaw video ...` command strings. This module does
+ * NOT re-derive any orchestration decisions (readiness, route, approval) — it
+ * just runs the emitted plan step-by-step by delegating each command to an
+ * injectable {@link StudioStepRunner} (the CLI supplies a `spawnSync` wrapper;
+ * tests inject a stub, so the whole runner is offline/deterministic).
+ *
+ * Credit safety is structural, not behavioural:
+ *  1. Default `--execute` is dry: {@link classifyStep} REFUSES any spend/network
+ *     subcommand that lacks `--dry-run` (blocked-spend), and dry steps keep their
+ *     `--dry-run`. Real spend requires the explicit `--confirm-spend` (which strips
+ *     `--dry-run` from spend-dry steps); spend-live steps run only with it.
+ *  2. `--auto-approve-storyboard` (only with `--confirm-spend`) is the ONLY way the
+ *     runner sets `VIDEOCLAW_APPROVE_STORYBOARD`; otherwise it strips it from the
+ *     child env, so the director storyboard-approval gate keeps blocking a real
+ *     render — the gate is inherited verbatim, never reimplemented here.
+ *  3. FREE_SUBCOMMANDS is the ALLOW-LIST of verified-offline subcommands (local fs
+ *     reads/writes + pure logic only — no provider/Gemini/R2/credit call). The
+ *     classifier is FAIL-CLOSED: anything NOT on this allow-list is treated as a
+ *     spend step (and refused on a default dry `--execute` unless it carries
+ *     `--dry-run`). A new, unknown, or typo'd subcommand is therefore spend by
+ *     default — it can never silently run. To make a new subcommand free, verify
+ *     it is offline and add it here explicitly.
+ */
+import type { StudioGoal, StudioPlan, StudioPlanStep } from './types.js';
+
+/**
+ * Allow-list of subcommands verified to be fully offline: they only read/write
+ * local project files and run pure logic — no provider credits, remote storage
+ * pushes, or live external/paid API (Gemini/R2/network) calls. A step is only
+ * classified `free` when its subcommand is on this list; everything else is a
+ * spend step (fail-closed). Keep this list conservative — when in doubt, leave a
+ * subcommand OFF so it is treated as spend rather than silently run.
+ */
+const FREE_SUBCOMMANDS = new Set<string>([
+  // Read-only status / reporting
+  'status',
+  'readiness',
+  'next-actions',
+  'list',
+  'index',
+  'metrics',
+  'report',
+  'doctor-project',
+  'doctor-portfolio',
+  'candidates-list',
+  'candidates-show',
+  // Local HTML portal generation (the publish-* variants push to R2 and are NOT free)
+  'portal',
+  'portal-index',
+  'review-ui',
+  // Pure prompt/cinematography composers + deterministic local renders
+  'filmmaking-prompts',
+  'multi-shot',
+  'prompt-lint',
+  'cinema-profile',
+  'storyboard-grid',
+  // Template / clone-plan reads (local template store + artifacts)
+  'template-list',
+  'template-show',
+  'storyboard-template-list',
+  'storyboard-template-show',
+  'clone-plan',
+  // Character / reference-sheet local artifact reads & writes
+  'character-list',
+  'character-show',
+  'reference-sheet-add',
+  'reference-sheet-list',
+  'reference-sheet-show',
+  'reference-sheet-bind',
+  'reference-sheet-validate',
+  // Scene-candidate selection / chaining (local artifact + event writes)
+  'select-candidate',
+  'reject-candidate',
+  'reroll-scene',
+  'chain-from',
+  'unchain',
+  // Local exports (write to disk / local Obsidian vault, no network)
+  'export-csv',
+  'export-obsidian',
+  'sync-obsidian',
+  // Local batch-queue state rollup (batch-submit/monitor poll+download and are NOT free)
+  'batch-status',
+]);
+
+/** Env var that unblocks the director storyboard-approval gate. The runner must
+ * never set it, so the gate keeps blocking inside any spawned execute. */
+export const APPROVAL_ENV_VAR = 'VIDEOCLAW_APPROVE_STORYBOARD';
+
+export type StudioStepClassification = 'free' | 'spend-dry' | 'spend-live';
+
+export class StudioExecuteError extends Error {
+  constructor(
+    public readonly code: string,
+    message: string,
+  ) {
+    super(message);
+    this.name = 'StudioExecuteError';
+  }
+}
+
+/**
+ * Tokenizes a Studio command template into argv, honoring single/double quotes
+ * (recipe commands quote multi-word values, e.g. `--client "Acme Inc"`).
+ */
+export function parseStudioCommandArgv(command: string): string[] {
+  const argv: string[] = [];
+  let current = '';
+  let quote: '"' | "'" | null = null;
+  let started = false;
+  for (const ch of command) {
+    if (quote) {
+      if (ch === quote) quote = null;
+      else current += ch;
+      started = true;
+    } else if (ch === '"' || ch === "'") {
+      quote = ch;
+      started = true;
+    } else if (ch === ' ' || ch === '\t' || ch === '\n') {
+      if (started) {
+        argv.push(current);
+        current = '';
+        started = false;
+      }
+    } else {
+      current += ch;
+      started = true;
+    }
+  }
+  if (started) argv.push(current);
+  return argv;
+}
+
+/**
+ * Returns the argv with a leading `vclaw` token removed (recipe commands are
+ * written `vclaw video ...`; the spawned child is the vclaw binary itself).
+ */
+export function studioStepArgv(step: StudioPlanStep): string[] {
+  const argv = parseStudioCommandArgv(step.command);
+  return argv[0] === 'vclaw' ? argv.slice(1) : argv;
+}
+
+/** The subcommand of a `vclaw video <sub> ...` (or `vclaw <sub> ...`) command. */
+function subcommandOf(argv: string[]): string | undefined {
+  const rest = argv[0] === 'vclaw' ? argv.slice(1) : argv;
+  return rest[0] === 'video' ? rest[1] : rest[0];
+}
+
+/**
+ * Classifies a step by credit risk, FAIL-CLOSED. A step is only `free` when its
+ * subcommand is on the {@link FREE_SUBCOMMANDS} allow-list; everything else —
+ * including an unknown, typo'd, or missing subcommand — is a spend step:
+ * `spend-dry` when it carries `--dry-run`, else `spend-live` (refused by the
+ * runner on a default dry `--execute`). An empty/undefined subcommand is the
+ * safest classification, `spend-live`.
+ */
+export function classifyStep(step: StudioPlanStep): StudioStepClassification {
+  const argv = parseStudioCommandArgv(step.command);
+  const sub = subcommandOf(argv);
+  if (sub && FREE_SUBCOMMANDS.has(sub)) {
+    return 'free';
+  }
+  return argv.includes('--dry-run') ? 'spend-dry' : 'spend-live';
+}
+
+export interface StudioStepRunResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  /** Parsed child stdout JSON, when stdout was valid JSON. */
+  json?: unknown;
+}
+
+/** Injectable step runner. Receives child argv (no leading `vclaw`) + child env. */
+export type StudioStepRunner = (argv: string[], env: NodeJS.ProcessEnv) => StudioStepRunResult;
+
+export interface StudioExecuteOptions {
+  runStep: StudioStepRunner;
+  /** Base env the child env is derived from. */
+  baseEnv?: NodeJS.ProcessEnv;
+  /**
+   * Permit credit-spending steps to RUN for real. When set, spend-dry steps are
+   * promoted to live (their `--dry-run` is stripped) and spend-live steps run.
+   * Default false → fully dry (spend-live is refused; spend-dry runs as dry).
+   */
+  confirmSpend?: boolean;
+  /**
+   * Only meaningful with `confirmSpend`: set `VIDEOCLAW_APPROVE_STORYBOARD` in the
+   * child env so a real render proceeds unattended past the director gate. Without
+   * it the approval var is stripped, so the human storyboard-approval gate still
+   * blocks a real render unless it was approved out-of-band.
+   */
+  autoApproveStoryboard?: boolean;
+  /** Resume from this step id (earlier steps are recorded as skipped). */
+  fromStepId?: string;
+}
+
+export type StudioStepStatus =
+  | 'ran'
+  | 'skipped-before-resume'
+  | 'skipped-approval'
+  | 'blocked-spend'
+  | 'blocked'
+  | 'failed';
+
+export interface StudioStepResult {
+  id: string;
+  command: string;
+  classification: StudioStepClassification;
+  status: StudioStepStatus;
+  exitCode: number | null;
+  /** `status` field parsed from the child's JSON output, when present. */
+  childStatus?: string;
+  /** A storyboard markdown path surfaced by a director awaiting-approval child. */
+  markdownPath?: string;
+}
+
+export type StudioStopReason =
+  | 'approval'
+  | 'spend-guard'
+  | 'child-blocked'
+  | 'child-failed'
+  | 'missing-inputs';
+
+export type StudioExecutionMode = 'dry' | 'confirm-spend' | 'auto-render';
+
+export interface StudioExecutionReport {
+  schemaVersion: 1;
+  goal: StudioGoal;
+  /** dry = no credits; confirm-spend = real spend, human-gated; auto-render = real spend, gate auto-approved. */
+  mode: StudioExecutionMode;
+  executed: boolean;
+  ranCount: number;
+  stoppedAt?: string;
+  stopReason?: StudioStopReason;
+  /** Set in dry mode when the plan contains spend steps: how to render for real. */
+  hint?: string;
+  results: StudioStepResult[];
+  warnings: string[];
+}
+
+/**
+ * Builds the child env. By default the storyboard-approval var is STRIPPED so the
+ * director gate keeps blocking. Only when `autoApprove` is set (auto-render mode)
+ * is it set to '1' so a real render proceeds unattended.
+ */
+export function studioChildEnv(
+  base: NodeJS.ProcessEnv = {},
+  opts: { autoApprove?: boolean } = {},
+): NodeJS.ProcessEnv {
+  const env = { ...base };
+  if (opts.autoApprove) {
+    env[APPROVAL_ENV_VAR] = '1';
+  } else {
+    delete env[APPROVAL_ENV_VAR];
+  }
+  return env;
+}
+
+function interpretChild(result: StudioStepRunResult): {
+  stop: boolean;
+  status: StudioStepStatus;
+  reason?: StudioStopReason;
+  childStatus?: string;
+  markdownPath?: string;
+} {
+  if (result.exitCode !== 0) {
+    return { stop: true, status: 'failed', reason: 'child-failed' };
+  }
+  const json =
+    result.json && typeof result.json === 'object' && !Array.isArray(result.json)
+      ? (result.json as Record<string, unknown>)
+      : undefined;
+  const childStatus = json && typeof json.status === 'string' ? json.status : undefined;
+  const blocked =
+    childStatus === 'blocked' ||
+    childStatus === 'awaiting-approval' ||
+    json?.awaitingApproval === true ||
+    json?.state === 'awaiting-approval';
+  if (blocked) {
+    const markdownPath =
+      typeof json?.markdownPath === 'string'
+        ? json.markdownPath
+        : typeof json?.storyboardMarkdownPath === 'string'
+          ? (json.storyboardMarkdownPath as string)
+          : undefined;
+    return { stop: true, status: 'blocked', reason: 'child-blocked', childStatus, markdownPath };
+  }
+  return { stop: false, status: 'ran', childStatus };
+}
+
+/** Returns argv with any `--dry-run` flag removed — used to promote a spend-dry
+ * step to a real run under --confirm-spend.
+ *
+ * NOTE: the paid audio commands (`narrate`/`dialogue`/`sfx`/`soundtrack`) have
+ * their OWN fail-closed CLI gate (`requireSpendConfirmation` in vclaw.ts) that
+ * refuses a real run unless the argv carries `--dry-run` OR `--confirm-spend`.
+ * No STUDIO_RECIPE emits those subcommands today, so stripping `--dry-run` here
+ * is sufficient. If a recipe ever DOES emit one, this promotion must also append
+ * `--confirm-spend` (otherwise the promoted child hits the CLI gate and fails). */
+export function stripDryRunArgv(argv: string[]): string[] {
+  return argv.filter((arg) => arg !== '--dry-run');
+}
+
+/**
+ * Runs a Studio plan's steps in order, stopping (fail-fast, no partial spend) at
+ * the first spend-guard refusal, child block, or child failure. Pure control flow
+ * — all I/O is delegated to `opts.runStep`. Never mutates the input plan.
+ *
+ * Modes (by flags): default = dry (free + spend-dry-as-dry; spend-live refused);
+ * confirmSpend = real spend (spend-dry promoted by stripping --dry-run), still
+ * human-gated; confirmSpend + autoApproveStoryboard = real spend with the director
+ * storyboard gate auto-approved (unattended).
+ */
+export function runStudioPlan(plan: StudioPlan, opts: StudioExecuteOptions): StudioExecutionReport {
+  const confirmSpend = opts.confirmSpend === true;
+  const autoApprove = opts.autoApproveStoryboard === true;
+  if (autoApprove && !confirmSpend) {
+    throw new StudioExecuteError(
+      'studio_execute_auto_approve_requires_confirm_spend',
+      '--auto-approve-storyboard only applies together with --confirm-spend.',
+    );
+  }
+  const mode: StudioExecutionMode = !confirmSpend ? 'dry' : autoApprove ? 'auto-render' : 'confirm-spend';
+  const childEnv = studioChildEnv(opts.baseEnv, { autoApprove: confirmSpend && autoApprove });
+  const results: StudioStepResult[] = [];
+  const report: StudioExecutionReport = {
+    schemaVersion: 1,
+    goal: plan.goal,
+    mode,
+    executed: false,
+    ranCount: 0,
+    results,
+    warnings: plan.warnings,
+  };
+
+  if (plan.missingInputs.length > 0) {
+    report.stopReason = 'missing-inputs';
+    return report;
+  }
+
+  if (mode === 'dry' && plan.steps.some((step) => classifyStep(step) !== 'free')) {
+    report.hint =
+      'Dry run: spend steps used --dry-run. To render for real add --confirm-spend (storyboard approval still required), or --confirm-spend --auto-approve-storyboard for an unattended render.';
+  }
+
+  let resuming = opts.fromStepId !== undefined;
+  for (const step of plan.steps) {
+    const classification = classifyStep(step);
+
+    if (resuming) {
+      if (step.id === opts.fromStepId) {
+        resuming = false;
+      } else {
+        results.push({ id: step.id, command: step.command, classification, status: 'skipped-before-resume', exitCode: null });
+        continue;
+      }
+    }
+
+    // Spend guard: a spend-live step (spend subcommand without --dry-run) runs
+    // only under --confirm-spend; otherwise it is refused and the run stops.
+    if (classification === 'spend-live' && !confirmSpend) {
+      results.push({ id: step.id, command: step.command, classification, status: 'blocked-spend', exitCode: null });
+      report.stoppedAt = step.id;
+      report.stopReason = 'spend-guard';
+      return report;
+    }
+
+    // Free + spend-dry steps run (the real human checkpoint comes from the child's
+    // own director-approval gate, surfaced as a 'blocked' result — not a coarse
+    // pre-stop). Under --confirm-spend a spend-dry step is promoted to a real run
+    // by stripping its --dry-run.
+    const baseArgv = studioStepArgv(step);
+    const argv = confirmSpend && classification === 'spend-dry' ? stripDryRunArgv(baseArgv) : baseArgv;
+    const runResult = opts.runStep(argv, childEnv);
+    const verdict = interpretChild(runResult);
+    results.push({
+      id: step.id,
+      command: step.command,
+      classification,
+      status: verdict.status,
+      exitCode: runResult.exitCode,
+      ...(verdict.childStatus ? { childStatus: verdict.childStatus } : {}),
+      ...(verdict.markdownPath ? { markdownPath: verdict.markdownPath } : {}),
+    });
+    if (verdict.status === 'ran') {
+      report.ranCount += 1;
+      report.executed = true;
+    }
+    if (verdict.stop) {
+      report.stoppedAt = step.id;
+      report.stopReason = verdict.reason;
+      return report;
+    }
+  }
+
+  return report;
+}