Execution Runtime

This is the engine room: it checks a project is truly ready, picks the right provider, rehearses the whole run for free, then submits the real job, polls it to completion, and can cancel a live job mid-flight — every step machine-readable.

What it does

• readiness verifies a project can run: required artifacts present, character identity consistent, director-mode Identity Sheets bound, scene candidates selected, and input images the right aspect ratio and resolution. It returns hard blockers and softer warnings.
• plan (alias execution-plan) reads readiness, infers the operation kind (text-to-video, image-to-video, or edit), and recommends a provider route (Seedance / Veo) that supports it and is available — with a rationale explaining each pick or skip.
• produce (alias execute) builds the real provider payload and submits it. With --dry-run it rehearses everything for free — validates, picks the route, builds the adapter payload, and simulates the run without spending a credit or calling a provider.
• produce --scene <n> restricts the run to specific scene indices (and turns on candidate mode, so each take is tracked as a candidate you can later pick a winner from).
• execute-status polls the live provider job once, downloads finished outputs into the project, and advances the project to review when done.
• execute-cancel asks the provider to kill an in-flight job and marks the run blocked.

How to use it

All examples use the built CLI. The installed binary is simply vclaw ....

node dist/cli/vclaw.js video readiness --project my-project

Reports whether the project can run, listing every blocker and warning as JSON.

node dist/cli/vclaw.js video plan --project my-project

Picks the recommended provider route and operation kind, with a per-route rationale (alias: execution-plan).

node dist/cli/vclaw.js video produce --project my-project --dry-run

Rehearses the entire run for free — no provider call, no credits — and reports the taskCount it would submit.

node dist/cli/vclaw.js video produce --project my-project

Submits the real job to the provider adapter and records the returned externalJobId (alias: execute).

node dist/cli/vclaw.js video produce --project my-project --scene 0 --scene 2

Re-runs only scenes 0 and 2 as fresh candidates, leaving the rest untouched.

node dist/cli/vclaw.js video execute-status --project my-project

Polls the live job once, ingests any finished clips into the project, and updates the checkpoint.

node dist/cli/vclaw.js video execute-cancel --project my-project

Cancels the in-flight provider job (if the route supports it) and marks the run blocked.

TIP

For director mode, prefix the real produce with the approval gate: VIDEOCLAW_APPROVE_STORYBOARD=1 node dist/cli/vclaw.js video produce --project my-project --mode director.

How it flows

Diagram source (live Mermaid)

Artifacts & outputs

Everything lands under projects/<slug>/artifacts/ (plus checkpoints, events, and outputs):

• execution-report.json — the single source of truth for a run: status (dry-run-complete, live-submitted, or blocked), routeId, operationKind, taskCount, the submission (with externalJobId), and a poll block updated by execute-status.
• asset-manifest.json — finished clips are merged in here as execute-status ingests outputs; downloaded media lands in projects/<slug>/outputs/.
• scene-candidates.json / scene selection — in candidate mode (when --scene is used or the file already exists), each take is appended as a tracked candidate awaiting a winner.
• storyboard.md — in director mode, an approval review file written when the gate blocks submission.
• Per-run telemetry is appended via generation.telemetry.recorded, and every step writes to events/events.jsonl.

Tips & gotchas

Rehearse first, always

produce --dry-run walks the full pipeline — readiness, route selection, payload build, simulation — and never spends credits. Use it to confirm taskCount and the chosen route before the real run.

Director mode is gated

In director mode, produce blocks before any provider call unless VIDEOCLAW_APPROVE_STORYBOARD=1 is set, and a stale storyboard review blocks both produce and execute-status even when approval is set — refresh it with vclaw video storyboard-review first.

Status and cancel need a live job

execute-status and execute-cancel require a prior execute-report carrying a routeId and a live externalJobId. Run a real (non-dry-run) produce first, or they report missing-live-adapter-job-id. Not every route supports cancellation — an unsupported route returns status: unsupported.

Driving it from an agent

Run readiness → plan → produce --dry-run and parse the JSON: ready: false with a blockers array means stop and fix; dry-run-complete means go live. After a real produce, loop execute-status until report.poll.status is completed (outputs ingested) or failed. Director-mode runs return a blocked report at the approval gate — set VIDEOCLAW_APPROVE_STORYBOARD=1 to clear it.

Related: Readiness checks · Studio planning front door · Assemble & stitch · Scene candidates