@vfrey/vfrey 0.0.1 → 1.0.0-beta.0

package/src/cloud/executor.ts

@@ -0,0 +1,281 @@
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { mkdir, readFile, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+import type { RenderJobResult } from "./job.js";
+
+/**
+ * Executors run one render job in isolation (spec 019, section C). Agent-written scenes are untrusted code, and an
+ * executor is where they run: no network, a read-only root, resource limits, a wall-clock timeout.
+ *
+ * THE SEAM. The console's `RenderJob` queue (a Postgres table with a status and a lease) is what calls this:
+ *   1. a dispatcher leases a queued job and lays out two folders: an input folder (`job.json`, the scene, the voice
+ *      that was synthesised before this step) and an empty output folder;
+ *   2. it calls `executor.run({ jobId, inputDir, outputDir })`;
+ *   3. it reads the outputs (`video.mp4`, `transcript.txt`, `checks.json`, `result.json`), uploads them, and records
+ *      `renderSeconds` for metering and credits.
+ * Either the console calls this module in-process, or a thin worker process polls the queue and calls it. Nothing in
+ * here knows about the queue or the database. `local-docker` runs `docker run` on this machine; a `cloud-run-jobs`
+ * executor (slice C2) implements the same interface with Google Cloud Run Jobs.
+ */
+
+export interface ExecutorJob {
+  /** A short id for the container name and the logs: letters, digits, dot, dash, underscore. */
+  jobId: string;
+  /** Absolute path of the folder with `job.json`. Mounted read-only. */
+  inputDir: string;
+  /** Absolute path of the folder the outputs are written to. Mounted read-write. */
+  outputDir: string;
+}
+
+export interface ExecutorResult {
+  /** The worker's `result.json`, or a synthesised one when the container died, timed out, or wrote nothing. */
+  result: RenderJobResult;
+  /** Wall-clock seconds the container ran. This is what the job is metered by. */
+  renderSeconds: number;
+  exitCode: number | null;
+  timedOut: boolean;
+  /** The last lines the container printed to stderr, for a failure message. */
+  stderrTail: string;
+}
+
+export interface Executor {
+  readonly kind: string;
+  run(job: ExecutorJob): Promise<ExecutorResult>;
+}
+
+export interface LocalDockerOptions {
+  /** Image name and tag. Default: `VFREY_RENDER_IMAGE`, else `vfrey-render-worker:latest`. */
+  image?: string;
+  /** Wall-clock limit for one job, in seconds. The container is killed when it passes. Default 600. */
+  timeoutSec?: number;
+  cpus?: number;
+  /** Docker size string for the memory limit, for example `4g`. */
+  memory?: string;
+  /** Size of the /tmp tmpfs (the render's work folder). It counts against the memory limit. */
+  tmpfsSize?: string;
+  shmSize?: string;
+  pidsLimit?: number;
+  /** The user the container runs as, `uid` or `uid:gid`. Default: the caller's own, so the output folder is writable. */
+  user?: string;
+  /** Environment for the render, for example `TTS_PROVIDER=none`. Only these (and the fixed ones) reach the container. */
+  env?: Record<string, string>;
+  /** The docker binary. Default `docker`. */
+  docker?: string;
+  /** Replaces the worker command. For tests that probe the sandbox; the default is `vfrey render-job`. */
+  command?: string[];
+}
+
+export const DEFAULT_IMAGE = "vfrey-render-worker:latest";
+export const LIMIT_DEFAULTS = { timeoutSec: 600, cpus: 2, memory: "4g", tmpfsSize: "2g", shmSize: "256m", pidsLimit: 512 } as const;
+
+export class ExecutorError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ExecutorError";
+  }
+}
+
+const SIZE = /^[1-9]\d{0,5}[kmg]?$/i;
+const NAME = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/;
+// Docker splits -v on ":", and a newline or NUL has no place in a path we mount.
+const BAD_PATH_CHARS = /[:\0\r\n,]/;
+const IMAGE = /^[a-z0-9][a-z0-9._\-/:@]{0,255}$/i;
+
+/** A mount path: absolute, normalised, and free of the characters docker parses. */
+export function mountPath(value: string, field: string): string {
+  if (!path.isAbsolute(value)) throw new ExecutorError(`${field} must be an absolute path, not "${value}".`);
+  if (BAD_PATH_CHARS.test(value)) throw new ExecutorError(`${field} must not contain ":", ",", or a control character.`);
+  const clean = path.resolve(value);
+  if (clean === path.parse(clean).root) throw new ExecutorError(`${field} must not be the filesystem root.`);
+  return clean;
+}
+
+export function containerName(jobId: string): string {
+  if (!NAME.test(jobId)) throw new ExecutorError(`jobId must be letters, digits, ".", "-" or "_" (up to 64), not "${jobId}".`);
+  return `vfrey-render-${jobId}`;
+}
+
+function defaultUser(): string {
+  return typeof process.getuid === "function" ? `${process.getuid()}:${process.getgid?.() ?? process.getuid()}` : "10001:10001";
+}
+
+/**
+ * The `docker run` argument list, without the docker binary. Pure: it reads nothing and runs nothing.
+ *
+ *   --network none        no network device but loopback; nothing leaves the container
+ *   --read-only           the root filesystem cannot be written; /tmp is a tmpfs, /job/out the only other write
+ *   --cap-drop ALL, --security-opt no-new-privileges, --user <uid>   no root, no capabilities, no privilege gain
+ *   --cpus, --memory (swap = memory), --pids-limit, --shm-size, --tmpfs size    resource limits
+ *   -v <in>:/job/in:ro -v <out>:/job/out:rw    the only host paths the container sees
+ */
+export function buildDockerArgs(job: ExecutorJob, options: LocalDockerOptions = {}): string[] {
+  const image = options.image ?? process.env.VFREY_RENDER_IMAGE ?? DEFAULT_IMAGE;
+  if (!IMAGE.test(image) || image.startsWith("-")) throw new ExecutorError(`The image name "${image}" is not valid.`);
+  const inputDir = mountPath(job.inputDir, "inputDir");
+  const outputDir = mountPath(job.outputDir, "outputDir");
+  if (inputDir === outputDir || inputDir.startsWith(outputDir + path.sep) || outputDir.startsWith(inputDir + path.sep)) {
+    throw new ExecutorError("inputDir and outputDir must be separate folders, neither inside the other.");
+  }
+  const name = containerName(job.jobId);
+  const cpus = options.cpus ?? LIMIT_DEFAULTS.cpus;
+  if (!(cpus > 0 && cpus <= 64)) throw new ExecutorError(`cpus must be between 0 and 64, not ${cpus}.`);
+  const memory = options.memory ?? LIMIT_DEFAULTS.memory;
+  const tmpfs = options.tmpfsSize ?? LIMIT_DEFAULTS.tmpfsSize;
+  const shm = options.shmSize ?? LIMIT_DEFAULTS.shmSize;
+  for (const [field, value] of [["memory", memory], ["tmpfsSize", tmpfs], ["shmSize", shm]] as const) {
+    if (!SIZE.test(value)) throw new ExecutorError(`${field} must be a size such as 512m or 4g, not "${value}".`);
+  }
+  const pids = options.pidsLimit ?? LIMIT_DEFAULTS.pidsLimit;
+  if (!Number.isInteger(pids) || pids < 16) throw new ExecutorError(`pidsLimit must be an integer of at least 16, not ${pids}.`);
+  const user = options.user ?? defaultUser();
+  if (!/^\d+(:\d+)?$/.test(user) || /^0(:|$)/.test(user)) throw new ExecutorError(`user must be a non-root numeric uid or uid:gid, not "${user}".`);
+  const env = { HOME: "/tmp/home", TMPDIR: "/tmp", ...(options.env ?? {}) };
+  const envArgs: string[] = [];
+  for (const [key, value] of Object.entries(env)) {
+    if (!/^[A-Z_][A-Z0-9_]*$/.test(key) || /[\0\r\n]/.test(value)) throw new ExecutorError(`The environment entry "${key}" is not valid.`);
+    envArgs.push("--env", `${key}=${value}`);
+  }
+  return [
+    "run",
+    "--rm",
+    "--pull", "never",
+    "--name", name,
+    "--init",
+    "--network", "none",
+    "--read-only",
+    "--tmpfs", `/tmp:rw,exec,nosuid,nodev,size=${tmpfs},mode=1777`,
+    "--shm-size", shm,
+    "--cpus", String(cpus),
+    "--memory", memory,
+    "--memory-swap", memory,
+    "--pids-limit", String(pids),
+    "--cap-drop", "ALL",
+    "--security-opt", "no-new-privileges",
+    "--user", user,
+    "-v", `${inputDir}:/job/in:ro`,
+    "-v", `${outputDir}:/job/out:rw`,
+    ...envArgs,
+    image,
+    ...(options.command ?? ["vfrey", "render-job", "--input", "/job/in", "--output", "/job/out"]),
+  ];
+}
+
+function synthesized(status: "failed" | "timeout", code: string, message: string, seconds: number): RenderJobResult {
+  return {
+    version: 1,
+    status,
+    engine: null,
+    code,
+    message,
+    durations: { totalSec: seconds, renderSec: null, checksSec: null },
+    video: null,
+    sizes: { videoBytes: 0, transcriptBytes: 0 },
+    voice: "none",
+    warnings: [],
+    failedChecks: [],
+  };
+}
+
+function run(binary: string, args: string[], timeoutMs: number): Promise<{ code: number | null; stdout: string; stderr: string }> {
+  return new Promise((resolve) => {
+    const child = spawn(binary, args, { stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (c) => (stdout = (stdout + c).slice(-8000)));
+    child.stderr.on("data", (c) => (stderr = (stderr + c).slice(-8000)));
+    const timer = setTimeout(() => child.kill("SIGKILL"), timeoutMs);
+    child.on("error", (error) => {
+      clearTimeout(timer);
+      resolve({ code: null, stdout, stderr: `${stderr}${error.message}` });
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      resolve({ code, stdout, stderr });
+    });
+  });
+}
+
+/** Runs each job as one `docker run` on this machine. For development, tests, and a single-host deployment. */
+export class LocalDockerExecutor implements Executor {
+  readonly kind = "local-docker";
+  constructor(private readonly options: LocalDockerOptions = {}) {}
+
+  async run(job: ExecutorJob): Promise<ExecutorResult> {
+    const docker = this.options.docker ?? "docker";
+    const timeoutSec = this.options.timeoutSec ?? LIMIT_DEFAULTS.timeoutSec;
+    if (!(timeoutSec > 0)) throw new ExecutorError(`timeoutSec must be positive, not ${timeoutSec}.`);
+    // Validate everything before touching the disk or docker.
+    buildDockerArgs(job, this.options);
+    const input = await stat(job.inputDir).catch(() => null);
+    if (!input?.isDirectory()) throw new ExecutorError(`inputDir "${job.inputDir}" is not a folder.`);
+    await mkdir(job.outputDir, { recursive: true });
+    // A symlinked mount path is resolved so the path that was validated is the path that is mounted.
+    const real = { ...job, inputDir: await realpath(job.inputDir), outputDir: await realpath(job.outputDir) };
+    const final = buildDockerArgs(real, this.options);
+
+    const name = containerName(job.jobId);
+    const started = Date.now();
+    let timedOut = false;
+    const outcome = await new Promise<{ code: number | null; stderr: string }>((resolve) => {
+      const child = spawn(docker, final, { stdio: ["ignore", "ignore", "pipe"] });
+      let stderr = "";
+      child.stderr.on("data", (c) => (stderr = (stderr + c).slice(-8000)));
+      const timer = setTimeout(async () => {
+        timedOut = true;
+        // Killing the container ends `docker run` too; --rm removes it. The client is killed as a backstop.
+        await run(docker, ["kill", name], 20_000);
+        await run(docker, ["rm", "-f", name], 20_000);
+        child.kill("SIGKILL");
+      }, timeoutSec * 1000);
+      child.on("error", (error) => {
+        clearTimeout(timer);
+        resolve({ code: null, stderr: `${stderr}${error.message}` });
+      });
+      child.on("close", (code) => {
+        clearTimeout(timer);
+        resolve({ code, stderr });
+      });
+    });
+    const renderSeconds = Math.round(((Date.now() - started) / 1000) * 10) / 10;
+    const tail = outcome.stderr.trim().split(/\r?\n/).slice(-8).join("\n");
+    if (timedOut) {
+      // Make sure nothing is left running or on disk, whatever the kill raced with.
+      for (let attempt = 0; attempt < 20; attempt += 1) {
+        await run(docker, ["rm", "-f", name], 20_000);
+        if ((await run(docker, ["inspect", "--type", "container", name], 20_000)).code !== 0) break;
+        await new Promise((resolve) => setTimeout(resolve, 250));
+      }
+      return {
+        result: synthesized("timeout", "render_timeout", `The render ran past its ${timeoutSec} s limit and was stopped.`, renderSeconds),
+        renderSeconds,
+        exitCode: outcome.code,
+        timedOut: true,
+        stderrTail: tail,
+      };
+    }
+    let parsed: RenderJobResult | null = null;
+    try {
+      parsed = JSON.parse(await readFile(path.join(job.outputDir, "result.json"), "utf8")) as RenderJobResult;
+    } catch {
+      parsed = null;
+    }
+    const result =
+      parsed ??
+      synthesized(
+        "failed",
+        outcome.code === 137 ? "render_oom" : "worker_crashed",
+        outcome.code === 137
+          ? "The render was killed, most likely because it ran out of memory."
+          : `The worker exited with code ${outcome.code ?? "none"} and wrote no result.${tail ? ` ${tail.split("\n").slice(-2).join(" ")}` : ""}`,
+        renderSeconds,
+      );
+    return { result, renderSeconds, exitCode: outcome.code, timedOut: false, stderrTail: tail };
+  }
+}
+
+/** The executor for `kind`. Only `local-docker` exists in this slice; `cloud-run-jobs` is slice C2. */
+export function createExecutor(kind: string, options: LocalDockerOptions = {}): Executor {
+  if (kind === "local-docker") return new LocalDockerExecutor(options);
+  throw new ExecutorError(`There is no "${kind}" executor. Available: local-docker.`);
+}

package/src/cloud/job.ts

@@ -0,0 +1,106 @@
+import path from "node:path";
+
+/**
+ * The contract between whatever queues a render and the render worker (spec 019, section C).
+ *
+ * A job is a folder (`/job/in` in the container) holding `job.json`, the scene folder and, optionally, the voice track
+ * that was synthesised before the container started (the cloud image has no `say`). The worker writes `video.mp4`,
+ * `transcript.txt`, `checks.json` and `result.json` into another folder (`/job/out`).
+ */
+
+export const JOB_FILE = "job.json";
+export const JOB_VERSION = 1;
+export const JOB_ENGINES = ["vfrey-framey", "hyperframes", "remotion"] as const;
+export type JobEngine = (typeof JOB_ENGINES)[number];
+
+/** The most lines a job script may carry; the product's own limit for a script (src/generate/script.ts). */
+export const JOB_LIMITS = { titleMax: 200, linesMax: 40, lineMax: 400 } as const;
+
+export interface RenderJob {
+  version: 1;
+  engine: JobEngine;
+  /** The scene folder, relative to the input folder. `index.html` for the HTML engines, `index.tsx` for Remotion. */
+  scene: string;
+  script: { title: string; lines: string[] };
+  /** The voice track, relative to the input folder, already synthesised. Null renders a silent, estimated-timing video. */
+  voice: string | null;
+}
+
+export class JobError extends Error {
+  constructor(
+    message: string,
+    readonly code: string = "job_invalid",
+  ) {
+    super(message);
+    this.name = "JobError";
+  }
+}
+
+/**
+ * A path inside the input folder: relative, no `..`, no NUL. Returns the cleaned relative path.
+ * (Where the path resolves is checked again against the real folder at run time, so a symlink cannot lead out.)
+ */
+export function insidePath(value: unknown, field: string): string {
+  if (typeof value !== "string" || value.trim() === "") throw new JobError(`${field} must be a non-empty relative path.`);
+  if (value.includes("\0")) throw new JobError(`${field} must not contain a NUL byte.`);
+  if (path.isAbsolute(value) || /^[a-zA-Z]:/.test(value)) throw new JobError(`${field} must be relative to the input folder, not "${value}".`);
+  const clean = path.posix.normalize(value.split(path.sep).join("/"));
+  if (clean === ".." || clean.startsWith("../")) throw new JobError(`${field} must stay inside the input folder, not "${value}".`);
+  return clean === "." ? "." : clean;
+}
+
+/** Checks the parsed `job.json`. Throws a JobError naming the field; never returns a half-valid job. */
+export function parseJob(raw: unknown): RenderJob {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new JobError("job.json must be a JSON object.");
+  const job = raw as Record<string, unknown>;
+  if (job.version !== JOB_VERSION) throw new JobError(`job.json version must be ${JOB_VERSION}, not ${JSON.stringify(job.version)}.`);
+  if (typeof job.engine !== "string" || !(JOB_ENGINES as readonly string[]).includes(job.engine)) {
+    throw new JobError(`engine must be one of ${JOB_ENGINES.join(", ")}, not ${JSON.stringify(job.engine)}.`);
+  }
+  const script = job.script as Record<string, unknown> | undefined;
+  if (!script || typeof script !== "object") throw new JobError("script must be an object with a title and lines.");
+  if (typeof script.title !== "string" || !script.title.trim() || script.title.length > JOB_LIMITS.titleMax) {
+    throw new JobError(`script.title must be 1 to ${JOB_LIMITS.titleMax} characters.`);
+  }
+  const lines = script.lines;
+  if (!Array.isArray(lines) || lines.length === 0 || lines.length > JOB_LIMITS.linesMax) {
+    throw new JobError(`script.lines must hold 1 to ${JOB_LIMITS.linesMax} lines.`);
+  }
+  for (const [i, line] of lines.entries()) {
+    if (typeof line !== "string" || !line.trim() || line.length > JOB_LIMITS.lineMax) throw new JobError(`script.lines[${i}] must be 1 to ${JOB_LIMITS.lineMax} characters.`);
+  }
+  const voice = job.voice === undefined || job.voice === null ? null : insidePath(job.voice, "voice");
+  return {
+    version: JOB_VERSION,
+    engine: job.engine as JobEngine,
+    scene: insidePath(job.scene, "scene"),
+    script: { title: script.title.trim(), lines: (lines as string[]).map((line) => line.trim()) },
+    voice,
+  };
+}
+
+export type JobStatus = "succeeded" | "rejected" | "failed" | "timeout";
+
+export interface CheckSummary {
+  id: string;
+  status: "pass" | "fail" | "skipped";
+  severity: string;
+  message: string;
+}
+
+/** `result.json`. The worker writes every field except `timeout`, which only the executor can know. */
+export interface RenderJobResult {
+  version: 1;
+  /** `succeeded`: the video exists and every check passed. `rejected`: it rendered but a check failed (do not publish). `failed`: no video. `timeout`: the executor killed it. */
+  status: JobStatus;
+  engine: JobEngine | null;
+  /** A stable code and a sentence for the person, set when the status is not `succeeded`. */
+  code: string | null;
+  message: string | null;
+  durations: { totalSec: number; renderSec: number | null; checksSec: number | null };
+  video: { width: number; height: number; durationSec: number; bytes: number } | null;
+  sizes: { videoBytes: number; transcriptBytes: number };
+  voice: "provided" | "none";
+  warnings: string[];
+  failedChecks: CheckSummary[];
+}

package/src/cloud/render-job.ts

@@ -0,0 +1,187 @@
+import { copyFile, mkdir, mkdtemp, readFile, realpath, rm, stat, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { linesToBeats } from "../generate/script.js";
+import { realTools, reviewRendered, wordTotal, type CheckResult } from "../pipeline/review.js";
+import { renderScene, type SceneEngine } from "../scene/render.js";
+import { checkScene, SceneError, storeScene } from "../scene/scene.js";
+import { JOB_FILE, JobError, parseJob, type CheckSummary, type RenderJob, type RenderJobResult } from "./job.js";
+
+type Env = Record<string, string | undefined>;
+
+export interface RenderJobIo {
+  /** The folder the job was mounted at. It is only read. */
+  inputDir: string;
+  /** The folder the outputs are written to. */
+  outputDir: string;
+  env?: Env;
+  stderr?: (text: string) => void;
+}
+
+const round1 = (n: number) => Math.round(n * 10) / 10;
+
+/** Resolves `rel` inside `root` and proves, with real paths, that it did not leave it (a symlink cannot lead out). */
+async function resolveInside(root: string, rel: string, field: string): Promise<string> {
+  const base = await realpath(root);
+  const target = await realpath(path.resolve(base, rel)).catch(() => {
+    throw new JobError(`${field} "${rel}" does not exist in the input folder.`, "job_missing_file");
+  });
+  if (target !== base && !target.startsWith(base + path.sep)) throw new JobError(`${field} "${rel}" resolves outside the input folder.`, "job_path_escape");
+  return target;
+}
+
+function summarize(checks: CheckResult[]): CheckSummary[] {
+  return checks.filter((c) => c.status === "fail").map((c) => ({ id: c.id, status: c.status, severity: c.severity, message: c.message }));
+}
+
+/**
+ * The worker's job: read `job.json`, render the scene with the product's own render path, run the after-render checks,
+ * and write the outputs. It makes no network request and reads no project or `~/.vfrey` state. A failure is reported in
+ * `result.json`; the returned result is what was written.
+ */
+export async function runRenderJob(io: RenderJobIo): Promise<RenderJobResult> {
+  const started = Date.now();
+  const env: Env = { ...(io.env ?? process.env) };
+  const log = io.stderr ?? (() => undefined);
+  const warnings: string[] = [];
+  const result: RenderJobResult = {
+    version: 1,
+    status: "failed",
+    engine: null,
+    code: null,
+    message: null,
+    durations: { totalSec: 0, renderSec: null, checksSec: null },
+    video: null,
+    sizes: { videoBytes: 0, transcriptBytes: 0 },
+    voice: "none",
+    warnings,
+    failedChecks: [],
+  };
+  const finish = async (): Promise<RenderJobResult> => {
+    result.durations.totalSec = round1((Date.now() - started) / 1000);
+    await mkdir(io.outputDir, { recursive: true });
+    await writeFile(path.join(io.outputDir, "result.json"), `${JSON.stringify(result, null, 2)}\n`);
+    return result;
+  };
+  const fail = (status: "failed", code: string, message: string) => {
+    result.status = status;
+    result.code = code;
+    result.message = message;
+  };
+  const work = await mkdtemp(path.join(os.tmpdir(), "vfrey-job-"));
+  try {
+    let job: RenderJob;
+    try {
+      job = parseJob(JSON.parse(await readFile(path.join(io.inputDir, JOB_FILE), "utf8")));
+    } catch (error) {
+      if (error instanceof JobError) fail("failed", error.code, error.message);
+      else fail("failed", "job_unreadable", `job.json could not be read: ${error instanceof Error ? error.message : String(error)}`);
+      return await finish();
+    }
+    result.engine = job.engine;
+    const transcript = `${job.script.lines.join("\n")}\n`;
+    await mkdir(io.outputDir, { recursive: true });
+    await writeFile(path.join(io.outputDir, "transcript.txt"), transcript);
+    result.sizes.transcriptBytes = Buffer.byteLength(transcript);
+
+    // A silent job: TTS_PROVIDER=none, or no voice in the job. The timing is then estimated from the script.
+    const silent = env.TTS_PROVIDER === "none" || job.voice === null;
+    let voicePath: string | null = null;
+    let sceneRoot: string;
+    try {
+      sceneRoot = await resolveInside(io.inputDir, job.scene, "scene");
+      if (!silent) voicePath = await resolveInside(io.inputDir, job.voice!, "voice");
+      if (voicePath && !(await stat(voicePath)).isFile()) throw new JobError("voice must be a file.", "job_missing_file");
+    } catch (error) {
+      if (error instanceof JobError) {
+        fail("failed", error.code, error.message);
+        return await finish();
+      }
+      throw error;
+    }
+    result.voice = voicePath ? "provided" : "none";
+
+    const rendered = path.join(work, "out", "video.mp4");
+    const renderStart = Date.now();
+    try {
+      // The scene is copied (and its SVGs sanitised, symlinks refused) before anything reads it.
+      await checkScene(sceneRoot, job.engine);
+      const stored = await storeScene(sceneRoot, path.join(work, "scene"));
+      warnings.push(...stored.warnings);
+      env.HOME = env.HOME || path.join(work, "home");
+      await renderScene({
+        engine: job.engine as SceneEngine,
+        sceneDir: path.join(work, "scene"),
+        title: job.script.title,
+        lines: job.script.lines,
+        beats: linesToBeats(job.script.lines).map((b) => ({ role: b.role, text: b.text, caption: b.caption })),
+        voiceoverPath: voicePath,
+        outputPath: rendered,
+        workDir: path.join(work, "render"),
+        env,
+        cwd: work,
+        warn: (message) => {
+          warnings.push(message);
+          log(`! ${message}\n`);
+        },
+      });
+    } catch (error) {
+      if (error instanceof SceneError) fail("failed", error.code, `${error.message} Fix: ${error.fix}`);
+      else fail("failed", "render_failed", `The render failed: ${error instanceof Error ? error.message : String(error)}`.slice(0, 600));
+      result.durations.renderSec = round1((Date.now() - renderStart) / 1000);
+      return await finish();
+    }
+    result.durations.renderSec = round1((Date.now() - renderStart) / 1000);
+
+    const checksStart = Date.now();
+    const checks = await reviewRendered({
+      file: rendered,
+      voicePath,
+      words: wordTotal(job.script.lines.join(" ")),
+      // The label is always burned by vfrey's render path for an agent-written scene.
+      labelBurned: true,
+      tools: realTools(env),
+    });
+    result.durations.checksSec = round1((Date.now() - checksStart) / 1000);
+    await writeFile(path.join(io.outputDir, "checks.json"), `${JSON.stringify(checks, null, 2)}\n`);
+    result.failedChecks = summarize(checks);
+
+    const dest = path.join(io.outputDir, "video.mp4");
+    await copyFile(rendered, dest);
+    const bytes = (await stat(dest)).size;
+    result.sizes.videoBytes = bytes;
+    const { probeVideo } = await import("../render/probe.js");
+    const probe = await probeVideo(dest, env);
+    result.video = probe ? { width: probe.width, height: probe.height, durationSec: probe.durationSec, bytes } : null;
+    if (result.failedChecks.length > 0) {
+      result.status = "rejected";
+      result.code = result.failedChecks[0]!.id;
+      result.message = `The finished video failed ${result.failedChecks.length} check${result.failedChecks.length === 1 ? "" : "s"}: ${result.failedChecks[0]!.message}`;
+    } else if (!probe) {
+      fail("failed", "video_unreadable", "The rendered file is not a readable video.");
+    } else {
+      result.status = "succeeded";
+    }
+    return await finish();
+  } finally {
+    await rm(work, { recursive: true, force: true });
+  }
+}
+
+/** `vfrey render-job --input DIR --output DIR`: the container's command. Exit 0 only for a succeeded job; the result file has the rest. */
+export async function runRenderJobCommand(argv: string[], io: { env: NodeJS.ProcessEnv; stdout: (t: string) => void; stderr: (t: string) => void }): Promise<number> {
+  const flag = (name: string) => {
+    const at = argv.indexOf(name);
+    const value = at === -1 ? undefined : argv[at + 1];
+    return value && !value.startsWith("--") ? value : null;
+  };
+  const input = flag("--input");
+  const output = flag("--output");
+  if (!input || !output) {
+    io.stderr("✗ render-job needs --input DIR and --output DIR.\nFix: run `vfrey render-job --input /job/in --output /job/out`.\n");
+    return 2;
+  }
+  const result = await runRenderJob({ inputDir: path.resolve(input), outputDir: path.resolve(output), env: io.env, stderr: io.stderr });
+  io.stdout(`${JSON.stringify({ status: result.status, code: result.code, message: result.message })}\n`);
+  return result.status === "succeeded" ? 0 : 1;
+}