@vfrey/vfrey 1.0.0-beta.0 → 1.0.0-beta.1

package/src/cloud/cloudrun-executor.ts

@@ -0,0 +1,237 @@
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { packFolder } from "./bundle.js";
+import { containerName, ExecutorError, synthesized, type Executor, type ExecutorJob, type ExecutorResult } from "./executor.js";
+import { signUrl, type FetchLike, type Signer, type TokenProvider } from "./gcs-sign.js";
+import type { RenderJobResult } from "./job.js";
+
+/**
+ * The `cloud-run-jobs` executor (spec 019, section C2): one Cloud Run Job execution per render, over plain REST.
+ *
+ *   Cloud Run Jobs  https://docs.cloud.google.com/run/docs/reference/rest/v2/projects.locations.jobs/run
+ *   Executions      https://docs.cloud.google.com/run/docs/reference/rest/v2/projects.locations.jobs.executions
+ *   Storage JSON    https://docs.cloud.google.com/storage/docs/json_api
+ *
+ * The flow for a job id `J`:
+ *   1. the input folder is packed and uploaded to `gs://BUCKET/PREFIX/J/in.bundle.gz`;
+ *   2. one GET signed URL (the bundle) and one PUT signed URL per output file are made;
+ *   3. `jobs.run` starts an execution with overrides: args `render-job --remote`, the signed URLs in env, `timeout`;
+ *   4. the execution is polled until it completes (or the wall-clock limit passes and it is cancelled);
+ *   5. `result.json` and the other outputs are read from `gs://BUCKET/PREFIX/J/out/` into the output folder.
+ *
+ * The job's own service account holds NO bucket permission; it works only through the signed URLs. The job is deployed
+ * with Direct VPC egress (all traffic) into a VPC that has no Cloud NAT, so the scene has no route to the internet.
+ * `start`, `poll` and `collect` are the three steps for a caller (the console's cron) that cannot wait; `run` does all.
+ */
+
+export const OUTPUT_FILES = ["result.json", "video.mp4", "transcript.txt", "checks.json"] as const;
+export const REMOTE_ARGS = ["render-job", "--remote"] as const;
+
+export interface CloudRunOptions {
+  projectId: string;
+  /** For example `us-central1`. */
+  region: string;
+  /** The Cloud Run Job's name. It must run the render-worker image with `--command=vfrey`. */
+  jobName: string;
+  bucket: string;
+  /** An OAuth access token with the cloud-platform scope. Injected: a service account, or workload identity federation. */
+  token: TokenProvider;
+  /** Signs the URLs the container uses. */
+  signer: Signer;
+  fetch?: FetchLike;
+  /** Object prefix. Default `render-jobs`. */
+  prefix?: string;
+  /** Wall-clock limit for one execution, in seconds. Default 600. Sent as the task timeout. */
+  timeoutSec?: number;
+  /** Extra environment for the render. Only these (and the signed URLs) reach the container. */
+  env?: Record<string, string>;
+  /** The container's name in the job, when it has more than one. */
+  containerName?: string;
+  pollIntervalMs?: number;
+  /** Extra seconds past `timeoutSec` before the executor gives up on Cloud Run and cancels. Default 120. */
+  graceSec?: number;
+  sleep?: (ms: number) => Promise<void>;
+  now?: () => Date;
+}
+
+export interface CloudRunHandle {
+  jobId: string;
+  /** `projects/P/locations/R/jobs/J/executions/E`. */
+  executionName: string;
+  startedAt: number;
+  timeoutSec: number;
+}
+
+export type CloudRunPoll =
+  | { state: "running" }
+  | { state: "done"; succeeded: boolean; timedOut: boolean; renderSeconds: number; message: string };
+
+interface Execution {
+  name?: string;
+  startTime?: string;
+  completionTime?: string;
+  succeededCount?: number;
+  failedCount?: number;
+  cancelledCount?: number;
+  conditions?: { type?: string; state?: string; reason?: string; message?: string }[];
+}
+
+const GCS_ID = /^[a-z0-9][a-z0-9._-]{1,220}$/;
+const round1 = (n: number) => Math.round(n * 10) / 10;
+
+export class CloudRunExecutor implements Executor {
+  readonly kind = "cloud-run-jobs";
+  private readonly fetchImpl: FetchLike;
+  private readonly timeoutSec: number;
+
+  constructor(private readonly options: CloudRunOptions) {
+    for (const [field, value] of [["projectId", options.projectId], ["region", options.region], ["jobName", options.jobName], ["bucket", options.bucket]] as const) {
+      if (!value || !/^[A-Za-z0-9._-]+$/.test(value)) throw new ExecutorError(`${field} must be set to a plain name, not "${value}".`);
+    }
+    if (!GCS_ID.test(options.bucket)) throw new ExecutorError(`bucket "${options.bucket}" is not a valid bucket name.`);
+    this.timeoutSec = options.timeoutSec ?? 600;
+    if (!(this.timeoutSec > 0 && this.timeoutSec <= 3600)) throw new ExecutorError(`timeoutSec must be between 1 and 3600, not ${this.timeoutSec}.`);
+    this.fetchImpl = options.fetch ?? fetch;
+  }
+
+  private objectPrefix(jobId: string): string {
+    containerName(jobId); // validates the id: letters, digits, dot, dash, underscore
+    return `${(this.options.prefix ?? "render-jobs").replace(/^\/+|\/+$/g, "")}/${jobId}`;
+  }
+
+  private async api(url: string, init: RequestInit = {}): Promise<Response> {
+    const headers = new Headers(init.headers);
+    headers.set("authorization", `Bearer ${await this.options.token()}`);
+    return this.fetchImpl(url, { ...init, headers });
+  }
+
+  private async json<T>(url: string, init: RequestInit, what: string): Promise<T> {
+    const response = await this.api(url, init);
+    if (!response.ok) throw new ExecutorError(`${what} failed with HTTP ${response.status}.`);
+    return (await response.json()) as T;
+  }
+
+  private objectUrl(object: string): string {
+    return `https://storage.googleapis.com/storage/v1/b/${this.options.bucket}/o/${encodeURIComponent(object)}`;
+  }
+
+  private async putObject(object: string, data: Buffer, type: string): Promise<void> {
+    const url = `https://storage.googleapis.com/upload/storage/v1/b/${this.options.bucket}/o?uploadType=media&name=${encodeURIComponent(object)}`;
+    const response = await this.api(url, { method: "POST", headers: { "content-type": type }, body: new Uint8Array(data) });
+    if (!response.ok) throw new ExecutorError(`Uploading ${object} failed with HTTP ${response.status}.`);
+  }
+
+  private async getObject(object: string): Promise<Buffer | null> {
+    const response = await this.api(`${this.objectUrl(object)}?alt=media`);
+    if (response.status === 404) return null;
+    if (!response.ok) throw new ExecutorError(`Reading ${object} failed with HTTP ${response.status}.`);
+    return Buffer.from(await response.arrayBuffer());
+  }
+
+  /** Stages the inputs and starts the execution. Returns at once with a handle to poll. */
+  async start(job: ExecutorJob): Promise<CloudRunHandle> {
+    const { projectId, region, jobName, bucket } = this.options;
+    const prefix = this.objectPrefix(job.jobId);
+    const input = await stat(job.inputDir).catch(() => null);
+    if (!input?.isDirectory()) throw new ExecutorError(`inputDir "${job.inputDir}" is not a folder.`);
+    await this.putObject(`${prefix}/in.bundle.gz`, await packFolder(job.inputDir), "application/gzip");
+
+    const now = this.options.now?.() ?? new Date();
+    const expiresSec = this.timeoutSec + (this.options.graceSec ?? 120) + 900;
+    const inUrl = await signUrl(this.options.signer, { method: "GET", bucket, object: `${prefix}/in.bundle.gz`, expiresSec, now });
+    const outUrls: Record<string, string> = {};
+    for (const name of OUTPUT_FILES) outUrls[name] = await signUrl(this.options.signer, { method: "PUT", bucket, object: `${prefix}/out/${name}`, expiresSec, now });
+
+    const env = { ...(this.options.env ?? {}), VFREY_JOB_IN_URL: inUrl, VFREY_JOB_OUT_URLS: JSON.stringify(outUrls) };
+    const override: Record<string, unknown> = {
+      args: [...REMOTE_ARGS],
+      env: Object.entries(env).map(([name, value]) => ({ name, value })),
+    };
+    if (this.options.containerName) override.name = this.options.containerName;
+    const jobPath = `projects/${projectId}/locations/${region}/jobs/${jobName}`;
+    const operation = await this.json<{ name?: string; metadata?: { name?: string } }>(
+      `https://run.googleapis.com/v2/${jobPath}:run`,
+      { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ overrides: { containerOverrides: [override], taskCount: 1, timeout: `${this.timeoutSec}s` } }) },
+      "Starting the Cloud Run job",
+    );
+    // The run operation's metadata is the Execution. If it is not there yet, ask the operation for it.
+    let executionName = operation.metadata?.name;
+    for (let attempt = 0; !executionName && operation.name && attempt < 10; attempt += 1) {
+      await this.sleep(500);
+      const again = await this.json<{ metadata?: { name?: string } }>(`https://run.googleapis.com/v2/${operation.name}`, {}, "Reading the Cloud Run operation");
+      executionName = again.metadata?.name;
+    }
+    if (!executionName || !executionName.startsWith(`${jobPath}/executions/`)) throw new ExecutorError("Cloud Run did not return an execution name.");
+    return { jobId: job.jobId, executionName, startedAt: (this.options.now?.() ?? new Date()).getTime(), timeoutSec: this.timeoutSec };
+  }
+
+  private sleep(ms: number): Promise<void> {
+    return this.options.sleep ? this.options.sleep(ms) : new Promise((resolve) => setTimeout(resolve, ms));
+  }
+
+  /** One look at the execution. */
+  async poll(handle: CloudRunHandle): Promise<CloudRunPoll> {
+    const execution = await this.json<Execution>(`https://run.googleapis.com/v2/${handle.executionName}`, {}, "Reading the execution");
+    const elapsed = ((this.options.now?.() ?? new Date()).getTime() - handle.startedAt) / 1000;
+    const completed = execution.conditions?.find((c) => c.type === "Completed");
+    const finished = Boolean(execution.completionTime) || completed?.state === "CONDITION_SUCCEEDED" || completed?.state === "CONDITION_FAILED";
+    if (!finished) {
+      if (elapsed > handle.timeoutSec + (this.options.graceSec ?? 120)) {
+        // Cloud Run should have stopped it by now. Cancel, and report a timeout.
+        await this.api(`https://run.googleapis.com/v2/${handle.executionName}:cancel`, { method: "POST", headers: { "content-type": "application/json" }, body: "{}" }).catch(() => undefined);
+        return { state: "done", succeeded: false, timedOut: true, renderSeconds: round1(elapsed), message: "Cloud Run did not stop the execution in time and it was cancelled." };
+      }
+      return { state: "running" };
+    }
+    const start = execution.startTime ? Date.parse(execution.startTime) : NaN;
+    const end = execution.completionTime ? Date.parse(execution.completionTime) : NaN;
+    const renderSeconds = round1(Number.isFinite(start) && Number.isFinite(end) ? Math.max(0, (end - start) / 1000) : elapsed);
+    const message = (completed?.message ?? completed?.reason ?? "").slice(0, 300);
+    const succeeded = (execution.succeededCount ?? 0) > 0 && (execution.failedCount ?? 0) === 0 && (execution.cancelledCount ?? 0) === 0;
+    // A task that passed its timeout is failed by Cloud Run; its condition says so.
+    const timedOut = !succeeded && /timed? ?out|deadline|exceeded the (maximum|task)/i.test(`${completed?.reason ?? ""} ${completed?.message ?? ""}`);
+    return { state: "done", succeeded, timedOut, renderSeconds, message };
+  }
+
+  /** Reads the outputs into `outputDir` and maps everything to the shared result shape. Then removes the job's objects. */
+  async collect(handle: CloudRunHandle, finished: Extract<CloudRunPoll, { state: "done" }>, outputDir: string): Promise<ExecutorResult> {
+    const prefix = this.objectPrefix(handle.jobId);
+    await mkdir(outputDir, { recursive: true });
+    let parsed: RenderJobResult | null = null;
+    if (!finished.timedOut) {
+      for (const name of OUTPUT_FILES) {
+        const data = await this.getObject(`${prefix}/out/${name}`);
+        if (data) await writeFile(path.join(outputDir, name), data);
+      }
+      try {
+        parsed = JSON.parse(await readFile(path.join(outputDir, "result.json"), "utf8")) as RenderJobResult;
+      } catch {
+        parsed = null;
+      }
+    }
+    await this.cleanup(handle);
+    const tail = finished.message;
+    const result: RenderJobResult =
+      finished.timedOut
+        ? synthesized("timeout", "render_timeout", `The render ran past its ${handle.timeoutSec} s limit and was stopped.`, finished.renderSeconds)
+        : parsed ?? synthesized("failed", "worker_crashed", `The Cloud Run job ended without a result.${tail ? ` ${tail}` : ""}`, finished.renderSeconds);
+    return { result, renderSeconds: finished.renderSeconds, exitCode: finished.succeeded ? 0 : 1, timedOut: finished.timedOut, stderrTail: tail };
+  }
+
+  /** Best effort: the bucket's lifecycle rule is the backstop. */
+  async cleanup(handle: CloudRunHandle): Promise<void> {
+    const prefix = this.objectPrefix(handle.jobId);
+    for (const object of [`${prefix}/in.bundle.gz`, ...OUTPUT_FILES.map((name) => `${prefix}/out/${name}`)]) {
+      await this.api(this.objectUrl(object), { method: "DELETE" }).catch(() => undefined);
+    }
+  }
+
+  async run(job: ExecutorJob): Promise<ExecutorResult> {
+    const handle = await this.start(job);
+    for (;;) {
+      const state = await this.poll(handle);
+      if (state.state === "done") return this.collect(handle, state, job.outputDir);
+      await this.sleep(this.options.pollIntervalMs ?? 5000);
+    }
+  }
+}

package/src/cloud/executor.ts

@@ -15,8 +15,7 @@ import type { RenderJobResult } from "./job.js";
  *   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.
+ * here knows about the queue or the database. `local-docker` runs `docker run` on this machine; `cloud-run-jobs` (./cloudrun-executor.ts, slice C2) implements the same interface with Google Cloud Run Jobs.
  */
 
 export interface ExecutorJob {
@@ -161,7 +160,7 @@ export function buildDockerArgs(job: ExecutorJob, options: LocalDockerOptions =
   ];
 }
 
-function synthesized(status: "failed" | "timeout", code: string, message: string, seconds: number): RenderJobResult {
+export function synthesized(status: "failed" | "timeout", code: string, message: string, seconds: number): RenderJobResult {
   return {
     version: 1,
     status,
@@ -274,8 +273,9 @@ export class LocalDockerExecutor implements Executor {
   }
 }
 
-/** The executor for `kind`. Only `local-docker` exists in this slice; `cloud-run-jobs` is slice C2. */
+/** The executor for `kind`. `cloud-run-jobs` needs a project, a bucket and credentials: build it with `CloudRunExecutor` (./cloudrun-executor.ts). */
 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.`);
+  if (kind === "cloud-run-jobs") throw new ExecutorError('The "cloud-run-jobs" executor needs a project, region, job, bucket and credentials. Build it with new CloudRunExecutor(options).');
+  throw new ExecutorError(`There is no "${kind}" executor. Available: local-docker, cloud-run-jobs.`);
 }

package/src/cloud/gcs-sign.ts

@@ -0,0 +1,76 @@
+import { createHash, createSign } from "node:crypto";
+
+/**
+ * Cloud Storage V4 signed URLs, with no SDK (spec 019, section C2).
+ * https://docs.cloud.google.com/storage/docs/access-control/signed-urls
+ * https://docs.cloud.google.com/storage/docs/authentication/signatures
+ *
+ * Why signed URLs: the Cloud Run job container needs NO permission on the bucket. It is handed one GET URL for its input
+ * bundle and one PUT URL per output file, each good for one object and a short time. A scene that took the container's
+ * credentials could therefore not read another job's files. The signer is either a service account key (`keySigner`) or,
+ * with no key on the machine, the IAM Credentials `signBlob` call (`iamSigner`), which works with workload identity federation.
+ */
+
+/** Signs the string to sign and returns the signature as lower-case hex. */
+export type Signer = { email: string; sign(stringToSign: string): Promise<string> };
+export type TokenProvider = () => Promise<string>;
+export type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+
+const HOST = "storage.googleapis.com";
+const MAX_EXPIRES_SEC = 7 * 24 * 3600;
+
+/** Signs locally with the private key of a service account (PEM, as in the key file's `private_key`). */
+export function keySigner(email: string, privateKeyPem: string): Signer {
+  return {
+    email,
+    async sign(stringToSign) {
+      return createSign("RSA-SHA256").update(stringToSign).sign(privateKeyPem, "hex");
+    },
+  };
+}
+
+/** Signs through `iamcredentials.googleapis.com` as `email`. The caller needs roles/iam.serviceAccountTokenCreator on it. */
+export function iamSigner(email: string, token: TokenProvider, fetchImpl: FetchLike = fetch): Signer {
+  return {
+    email,
+    async sign(stringToSign) {
+      const response = await fetchImpl(`https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/${encodeURIComponent(email)}:signBlob`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${await token()}`, "content-type": "application/json" },
+        body: JSON.stringify({ payload: Buffer.from(stringToSign, "utf8").toString("base64") }),
+      });
+      if (!response.ok) throw new Error(`signBlob failed with HTTP ${response.status}.`);
+      const body = (await response.json()) as { signedBlob?: string };
+      if (!body.signedBlob) throw new Error("signBlob returned no signature.");
+      return Buffer.from(body.signedBlob, "base64").toString("hex");
+    },
+  };
+}
+
+const encode = (value: string) => encodeURIComponent(value).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+const encodePath = (value: string) => value.split("/").map(encode).join("/");
+const stamp = (now: Date) => now.toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z");
+
+/** The V4 string to sign for a GET or PUT on one object. Exported for tests. */
+export function v4Request(opts: { method: "GET" | "PUT"; bucket: string; object: string; email: string; expiresSec: number; now: Date }) {
+  if (!(opts.expiresSec > 0 && opts.expiresSec <= MAX_EXPIRES_SEC)) throw new Error("A signed URL lives 1 second to 7 days.");
+  const datetime = stamp(opts.now);
+  const scope = `${datetime.slice(0, 8)}/auto/storage/goog4_request`;
+  const query: [string, string][] = [
+    ["X-Goog-Algorithm", "GOOG4-RSA-SHA256"],
+    ["X-Goog-Credential", `${opts.email}/${scope}`],
+    ["X-Goog-Date", datetime],
+    ["X-Goog-Expires", String(Math.floor(opts.expiresSec))],
+    ["X-Goog-SignedHeaders", "host"],
+  ];
+  const canonicalQuery = query.map(([k, v]) => `${encode(k)}=${encode(v)}`).sort().join("&");
+  const resource = `/${opts.bucket}/${encodePath(opts.object)}`;
+  const canonical = [opts.method, resource, canonicalQuery, `host:${HOST}`, "", "host", "UNSIGNED-PAYLOAD"].join("\n");
+  const stringToSign = ["GOOG4-RSA-SHA256", datetime, scope, createHash("sha256").update(canonical).digest("hex")].join("\n");
+  return { canonical, stringToSign, canonicalQuery, resource };
+}
+
+export async function signUrl(signer: Signer, opts: { method: "GET" | "PUT"; bucket: string; object: string; expiresSec: number; now?: Date }): Promise<string> {
+  const { stringToSign, canonicalQuery, resource } = v4Request({ ...opts, email: signer.email, now: opts.now ?? new Date() });
+  return `https://${HOST}${resource}?${canonicalQuery}&X-Goog-Signature=${await signer.sign(stringToSign)}`;
+}

package/src/cloud/remote-job.ts

@@ -0,0 +1,67 @@
+import { mkdir, mkdtemp, readFile, rm, stat } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { unpackBundle } from "./bundle.js";
+import type { FetchLike } from "./gcs-sign.js";
+import type { RenderJobResult } from "./job.js";
+import { runRenderJob, type RenderJobIo } from "./render-job.js";
+
+type Env = Record<string, string | undefined>;
+
+/** The variables the cloud executor sets. They are removed from the environment the scene's render sees. */
+export const REMOTE_ENV = ["VFREY_JOB_IN_URL", "VFREY_JOB_OUT_URLS"] as const;
+const OUTPUT_NAMES = ["video.mp4", "transcript.txt", "checks.json", "result.json"] as const;
+
+/** A signed URL is only ever used if it points at Cloud Storage. */
+function storageUrl(value: unknown, field: string): string {
+  if (typeof value !== "string") throw new Error(`${field} is not set.`);
+  const url = new URL(value);
+  if (url.protocol !== "https:" || url.hostname !== "storage.googleapis.com") throw new Error(`${field} must be an https://storage.googleapis.com URL.`);
+  return url.toString();
+}
+
+/**
+ * `vfrey render-job --remote`: the Cloud Run Job's command (spec 019, section C2). It downloads the input bundle through
+ * a signed URL, renders with the same code as the local container, and uploads each output through its signed URL. It holds
+ * no credentials: the URLs are the only access, and they are removed from the environment before the render starts.
+ *
+ * Exit 0 when the outputs (above all `result.json`) were uploaded, even if the scene failed: the result file says so, and
+ * a non-zero exit would only make Cloud Run retry. Exit 1 when a download or an upload failed, which the executor reads
+ * as an infrastructure failure.
+ */
+export async function runRemoteJob(io: { env: Env; stdout: (t: string) => void; stderr: (t: string) => void; fetch?: FetchLike; workRoot?: string; render?: (io: RenderJobIo) => Promise<RenderJobResult> }): Promise<number> {
+  const fetchImpl = io.fetch ?? fetch;
+  const work = await mkdtemp(path.join(io.workRoot ?? os.tmpdir(), "vfrey-remote-"));
+  try {
+    const inUrl = storageUrl(io.env.VFREY_JOB_IN_URL, "VFREY_JOB_IN_URL");
+    const outUrls = JSON.parse(io.env.VFREY_JOB_OUT_URLS ?? "null") as Record<string, string> | null;
+    if (!outUrls) throw new Error("VFREY_JOB_OUT_URLS is not set.");
+    const targets = Object.fromEntries(OUTPUT_NAMES.map((name) => [name, storageUrl(outUrls[name], `VFREY_JOB_OUT_URLS.${name}`)]));
+
+    const response = await fetchImpl(inUrl);
+    if (!response.ok) throw new Error(`Downloading the input bundle failed with HTTP ${response.status}.`);
+    const inputDir = path.join(work, "in");
+    const outputDir = path.join(work, "out");
+    await mkdir(outputDir, { recursive: true });
+    await unpackBundle(Buffer.from(await response.arrayBuffer()), inputDir);
+
+    const env: Env = { ...io.env };
+    for (const name of REMOTE_ENV) delete env[name];
+    const result = await (io.render ?? runRenderJob)({ inputDir, outputDir, env, stderr: io.stderr });
+    io.stdout(`${JSON.stringify({ status: result.status, code: result.code, message: result.message })}\n`);
+
+    // result.json goes last: when it exists, every other output already does.
+    for (const name of [...OUTPUT_NAMES].sort((a) => (a === "result.json" ? 1 : -1))) {
+      const file = path.join(outputDir, name);
+      if (!(await stat(file).catch(() => null))) continue;
+      const put = await fetchImpl(targets[name]!, { method: "PUT", body: new Uint8Array(await readFile(file)) });
+      if (!put.ok) throw new Error(`Uploading ${name} failed with HTTP ${put.status}.`);
+    }
+    return 0;
+  } catch (error) {
+    io.stderr(`✗ render-job --remote: ${error instanceof Error ? error.message : String(error)}\n`);
+    return 1;
+  } finally {
+    await rm(work, { recursive: true, force: true });
+  }
+}

package/src/cloud/render-job.ts

@@ -170,6 +170,10 @@ export async function runRenderJob(io: RenderJobIo): Promise<RenderJobResult> {
 
 /** `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> {
+  if (argv.includes("--remote")) {
+    const { runRemoteJob } = await import("./remote-job.js");
+    return runRemoteJob(io);
+  }
   const flag = (name: string) => {
     const at = argv.indexOf(name);
     const value = at === -1 ? undefined : argv[at + 1];

package/src/help.ts

@@ -97,6 +97,25 @@ export const HELP: Record<string, CommandHelp> = {
       ["--api URL", "the vfrey server (default: VFREY_API_URL)"],
     ],
   },
+  cloud: {
+    summary: "Sync this project with a hosted one in your org: scenes, scripts, run details and (optionally) videos.",
+    usage: [
+      "npx vfrey cloud link",
+      "npx vfrey cloud push [--videos] [--dry-run] [--json]",
+      "npx vfrey cloud pull [--json]",
+      "npx vfrey cloud status [--json]",
+    ],
+    flags: [
+      ["link", "connect this project (by its vfrey.json id) to a cloud project in the org you are signed in to; records cloudProjectId in vfrey.json"],
+      ["push", "upload the scenes and scripts that changed, and the run details (stages, checks, what was published). Only changed files are sent"],
+      ["--videos", "with push: also upload finished videos and transcripts (large; counted against your plan's cloud storage)"],
+      ["--dry-run", "with push: show what would be sent and send nothing"],
+      ["pull", "download scenes and scripts changed in the cloud. If a file changed in both places the newest wins and the other is kept as <file>.conflict-<time>"],
+      ["status", "what is in sync, what to push, what to pull, and conflicts"],
+      ["--json", "print one JSON document"],
+      ["--api URL", "the vfrey server (default: VFREY_API_URL)"],
+    ],
+  },
   tick: {
     summary: "Run the pipeline once: source, generate, render, publish. Without --now it follows each series' cadence.",
     usage: [
@@ -205,7 +224,7 @@ export const HELP: Record<string, CommandHelp> = {
   },
 };
 
-const ORDER = ["doctor", "tick", "worker", "service", "engage", "analytics", "render", "scene", "engine", "dashboard", "open", "push", "update", "desk", "skill", "init", "videos", "projects", "login", "logout", "whoami", "org", "topics", "creators", "mail"];
+const ORDER = ["doctor", "tick", "worker", "service", "engage", "analytics", "render", "scene", "engine", "dashboard", "open", "push", "update", "desk", "skill", "init", "videos", "projects", "login", "logout", "whoami", "org", "topics", "creators", "mail", "cloud"];
 
 export function generalHelp(): string {
   const lines = ["vfrey: make short videos from your agent or the command line.", "", "Usage: npx vfrey <command> [flags]", "", "Commands:"];

package/src/project/marker.ts

@@ -13,6 +13,8 @@ export interface ProjectMarker {
   id: string;
   /** This project's preferred render engine: beats the machine default, loses to `--engine` and a series engine. */
   engine?: string;
+  /** The hosted project this one syncs with (spec 019 B), set by `vfrey cloud link`. */
+  cloudProjectId?: string;
 }
 
 /** A vfrey project: the folder that holds `vfrey.json`. */
@@ -21,6 +23,8 @@ export interface Project {
   id: string;
   /** The engine named in vfrey.json, if any. */
   engine?: string;
+  /** The hosted project id from `vfrey cloud link`, if linked. */
+  cloudProjectId?: string;
   root: string;
   /** `<root>/.vfrey`, where the database, logs and per-job copies live. */
   dataDir: string;
@@ -46,6 +50,7 @@ export function validateMarker(value: unknown): ProjectMarker | string {
   if (marker.engine !== undefined && !(typeof marker.engine === "string" && (ENGINE_IDS as readonly string[]).includes(marker.engine))) {
     return `"engine" must be one of ${ENGINE_IDS.join(", ")}`;
   }
+  if (marker.cloudProjectId !== undefined && !(typeof marker.cloudProjectId === "string" && marker.cloudProjectId.trim())) return `"cloudProjectId" must be a non-empty string`;
   return { ...marker, version: 1, name: marker.name.trim(), id: marker.id.trim() } as ProjectMarker;
 }
 
@@ -83,5 +88,5 @@ export function hasMarker(root: string): boolean {
 export function projectAt(rootPath: string): Project {
   const root = canonicalPath(rootPath);
   const marker = readMarker(root);
-  return { name: marker.name, id: marker.id, ...(marker.engine ? { engine: marker.engine } : {}), root, dataDir: path.join(root, ".vfrey") };
+  return { name: marker.name, id: marker.id, ...(marker.engine ? { engine: marker.engine } : {}), ...(marker.cloudProjectId ? { cloudProjectId: marker.cloudProjectId } : {}), root, dataDir: path.join(root, ".vfrey") };
 }

package/src/project/templates.ts

@@ -10,9 +10,9 @@ This folder makes short videos. The person talks to you; you run \`npx vfrey\`.
 Use the vfrey skill (\`.claude/skills/vfrey\` or \`.agents/skills/vfrey\`) if you have it. If not, this is the flow:
 
 1. Write the script yourself: \`scripts/<idea>.json\` (\`npx vfrey tick --script-template\` prints an example). Plain and accurate, 6 to 10 short lines, nothing invented.
-2. Design a scene for the idea in \`scenes/<idea>/\` (\`npx vfrey scene init scenes/<idea>\`). No fixed templates: two ideas should not look alike. Preview with \`npx vfrey render --scene scenes/<idea> --engine ${engine ?? "<engine>"} --script scripts/<idea>.json --frame 2.5 out.png\`.
+2. Always design a scene (the default template is only for an explicit quick text-only video; say so). Design it for the idea in \`scenes/<idea>/\` (\`npx vfrey scene init scenes/<idea>\`). No fixed templates: two ideas should not look alike. Preview with \`npx vfrey render --scene scenes/<idea> --engine ${engine ?? "<engine>"} --script scripts/<idea>.json --frame 2.5 out.png\`.
 3. \`npx vfrey tick --now --about "<subject>" --script scripts/<idea>.json --scene scenes/<idea> --engine ${engine ?? "<engine>"}\`
-4. Tell the person the path of the video in \`videos/\` and the \`See it:\` link.
+4. Tell the person the path of the video in \`videos/\` and the \`See it:\` link as printed: it is live (the tick starts the dashboard), so do not hedge; only if \`curl\` to it fails, run \`npx vfrey open\`.
 
 ## Commands
 

package/src/tick-report.ts

@@ -178,7 +178,7 @@ export function formatTickReport(report: TickReport, view: TickReportView = {}):
       const facts = job.durationSec !== null ? ` (${job.durationSec} s${job.width && job.height ? `, ${job.width}×${job.height}` : ""})` : "";
       lines.push(`✓ Video ready: ${job.mp4}${facts}`);
       if (job.engine) lines.push(`  Engine: ${job.engine.label}${job.engine.source === "project" ? " (from vfrey.json)" : ""}`);
-      if (job.scene) lines.push(`  Scene: ${job.scene.source === "agent" ? "agent-written" : "default template"}`);
+      if (job.scene) lines.push(`  Scene: ${job.scene.source === "agent" ? "agent-written" : "default template (plain text). Design one next time: npx vfrey scene init scenes/<idea>"}`);
       if (job.transcript) lines.push(`  Transcript: ${job.transcript}`);
       const ran = job.checks.filter((check) => check.status !== "skipped").length;
       if (ran > 0) lines.push(`  Checks: ${ran} passed`);