crew-runner 0.0.0-stage → 0.2.0

package/src/studio-mcp.ts

@@ -0,0 +1,38 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { openStudio, type StudioGrant } from "./studio.ts";
+
+export const MEDIA_TOOLS = ["probe", "capabilities", "render", "preview", "cancel"] as const;
+export async function createStudioMcp(grant: StudioGrant) {
+  const studio = await openStudio(grant);
+  const server = new McpServer({ name: "crew-studio", version: "0.1.0" });
+  let current: AbortController | undefined;
+  const text = (value: unknown) => ({ content: [{ type: "text" as const, text: JSON.stringify(value) }] });
+  const span = z.object({ start: z.number(), end: z.number() }).strict();
+  const timedText = span.extend({ text: z.string() }).strict();
+  const plan = z.object({ source: z.string(), cuts: z.array(span).max(12), captions: z.array(timedText).max(24), callouts: z.array(timedText).max(24), supportingAsset: span.extend({ id: z.string() }).strict().optional() }).strict();
+  server.registerTool("probe", { description: "Inspect a project-relative MP4. No file contents or network access.", inputSchema: { path: z.string() } }, async ({ path }) => text(await studio.probe(path)));
+  server.registerTool("capabilities", { description: "Report installed CPU encoder and unverified advertised hardware encoders.", inputSchema: {} }, async () => text(await studio.capabilities()));
+  for (const name of ["render", "preview"] as const) {
+    server.registerTool(name, { description: "Versioned local MP4 with original cuts/audio, timed captions and animated branded callouts. Never uploads.", inputSchema: { plan } }, async ({ plan: edit }, extra) => {
+      if (current) throw new Error("Studio busy");
+      const controller = new AbortController(); current = controller;
+      const cancel = () => controller.abort();
+      extra.signal.addEventListener("abort", cancel, { once: true });
+      if (extra.signal.aborted) cancel();
+      try { return text(await studio.render(edit, { preview: name === "preview", signal: controller.signal })); }
+      finally { extra.signal.removeEventListener("abort", cancel); current = undefined; }
+    });
+  }
+  server.registerTool("cancel", { description: "Cancel only this local studio's active render.", inputSchema: {} }, async () => { current?.abort(); return text({ cancellationRequested: !!current }); });
+  return { server, close: async () => { current?.abort(); await server.close(); } };
+}
+export async function serveStudio(grant: StudioGrant): Promise<void> {
+  const bridge = await createStudioMcp(grant);
+  const stop = () => { void bridge.close(); };
+  process.once("SIGINT", stop); process.once("SIGTERM", stop);
+  process.stdin.once("end", stop);
+  const timer = setTimeout(stop, Math.max(1, grant.expiresAt - Date.now())); timer.unref();
+  await bridge.server.connect(new StdioServerTransport());
+}

package/src/studio-source.ts

@@ -0,0 +1,77 @@
+// Source-space contract only. Execution stays in the existing Studio owner.
+export type SourceSpan = { start: number; end: number };
+export type SourcePlan = {
+  version: 2; source: string; sourceDuration: number;
+  remove: SourceSpan[]; mute: SourceSpan[];
+  holds: (SourceSpan & { frame: number })[];
+  crop?: { x: number; y: number; width: number; height: number };
+  // One existing project MP4 chosen by the member, prepended whole. Never generated.
+  intro?: string;
+};
+export type SourceSegment = SourceSpan & { outputStart: number; mute: boolean; frame?: number };
+export const SOURCE_FPS = 30;
+export const SOURCE_SECONDS = 5400;
+export const SOURCE_BYTES = 2 * 1024 ** 3;
+// Every other media file the engine reads (an intro, a supporting asset).
+export const MEDIA_BYTES = 100 * 1024 * 1024;
+export const EXPORT_BYTES = 512 * 1024 ** 2;
+function fields(v: unknown, keys: string[], required = keys): Record<string, unknown> {
+  if (!v || typeof v !== "object" || Array.isArray(v)) throw new Error("Invalid source plan object");
+  const o = v as Record<string, unknown>;
+  if (Object.keys(o).some((k) => !keys.includes(k)) || required.some((k) => !(k in o))) throw new Error("Unknown or missing source plan field");
+  return o;
+}
+function time(v: unknown): number {
+  if (typeof v !== "number" || !Number.isFinite(v) || v < 0 || v > SOURCE_SECONDS || Math.abs(v * SOURCE_FPS - Math.round(v * SOURCE_FPS)) > 0.000001) throw new Error("Source times must lie on the 30fps output grid within 90 minutes");
+  return v;
+}
+export function validateSourcePlan(value: unknown, mediaName: (v: unknown) => string): SourcePlan {
+  const o = fields(value, ["version", "source", "sourceDuration", "remove", "mute", "holds", "crop", "intro"], ["version", "source", "sourceDuration", "remove", "mute", "holds"]);
+  if (o.version !== 2) throw new Error("Unsupported plan version");
+  const duration = time(o.sourceDuration);
+  if (!duration) throw new Error("Empty source duration");
+  const spans = (value: unknown, hold = false) => {
+    if (!Array.isArray(value) || value.length > 32) throw new Error("Source edit entry limit");
+    let previous = 0;
+    return value.map((entry) => {
+      const s = fields(entry, hold ? ["start", "end", "frame"] : ["start", "end"]);
+      const start = time(s.start), end = time(s.end);
+      if (end <= start || start < previous || end > duration) throw new Error("Invalid, overlapping or unsorted source interval");
+      previous = end;
+      if (!hold) return { start, end };
+      const frame = time(s.frame);
+      if (frame >= duration) throw new Error("Hold frame outside source");
+      return { start, end, frame };
+    });
+  };
+  const remove = spans(o.remove), mute = spans(o.mute), holds = spans(o.holds, true) as SourcePlan["holds"];
+  if (remove.reduce((n, s) => n + s.end - s.start, 0) >= duration) throw new Error("Empty output timeline");
+  let crop: SourcePlan["crop"];
+  if (o.crop !== undefined) {
+    const c = fields(o.crop, ["x", "y", "width", "height"]);
+    for (const v of Object.values(c)) if (typeof v !== "number" || !Number.isSafeInteger(v) || v < 0 || v > 3840 || v % 2) throw new Error("Crop requires bounded even source pixels");
+    crop = { x: c.x as number, y: c.y as number, width: c.width as number, height: c.height as number };
+    if (!crop!.width || !crop!.height) throw new Error("Empty crop");
+  }
+  const plan: SourcePlan = { version: 2, source: mediaName(o.source), sourceDuration: duration, remove, mute, holds, ...(crop ? { crop } : {}), ...(o.intro !== undefined ? { intro: mediaName(o.intro) } : {}) };
+  compileSourcePlan(plan); // admission includes segment count, before any media work
+  return plan;
+}
+// introFrames: whole 30fps output frames of a prepended intro; source mapping is unchanged.
+export function compileSourcePlan(p: SourcePlan, introFrames = 0): SourceSegment[] {
+  const boundaries = [...new Set([0, p.sourceDuration, ...[...p.remove, ...p.mute, ...p.holds].flatMap((s) => [s.start, s.end])])].sort((a,b) => a-b);
+  const result: SourceSegment[] = [];
+  let outputFrames = introFrames;
+  for (let i=0; i<boundaries.length-1; i++) {
+    const start = boundaries[i]!, end = boundaries[i+1]!;
+    if (p.remove.some((s) => s.start <= start && s.end >= end)) continue;
+    const hold = p.holds.find((s) => s.start <= start && s.end >= end);
+    for (let from = start; from < end; from += 30) {
+      const to = Math.min(end, from+30);
+      result.push({ start: from, end: to, outputStart: outputFrames/30, mute: p.mute.some((s) => s.start <= from && s.end >= to), ...(hold ? { frame: hold.frame } : {}) });
+      outputFrames += Math.round((to-from)*30);
+    }
+  }
+  if (result.length > 384) throw new Error("Source plan segment budget exceeded");
+  return result;
+}

package/src/studio.ts

@@ -0,0 +1,402 @@
+import { spawn } from "node:child_process";
+import { constants } from "node:fs";
+import { lstat, mkdir, open, realpath, rm, writeFile, statfs } from "node:fs/promises";
+import { isAbsolute, join, resolve, relative } from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { killTree } from "./spawn.ts";
+import { sourceAudioAdmission, AUDIO_CLOCK_HZ, AUDIO_SCAN_BYTES } from "./studio-audio-admission.ts";
+import { validateSourcePlan, compileSourcePlan, SOURCE_SECONDS, SOURCE_BYTES, EXPORT_BYTES, MEDIA_BYTES, type SourcePlan } from "./studio-source.ts";
+
+export type StudioGrant = Readonly<{ root: string; enabled: boolean; expiresAt: number }>;
+// The local CLI and MCP bridge always use LOCAL_LIMITS. A hosted edit runs alone on a disposable machine that is
+// destroyed after the job, so it may pass larger limits, never beyond HOSTED_MAX_JOB_MS or the 512 MiB export cap.
+export type StudioLimits = Readonly<{ jobMs: number; unitMs: number; threads: number; height: 720 | 1080; intermediateBytes: number; exportBytes: number }>;
+export const LOCAL_LIMITS: StudioLimits = Object.freeze({ jobMs: 900_000, unitMs: 90_000, threads: 2, height: 720, intermediateBytes: EXPORT_BYTES, exportBytes: EXPORT_BYTES });
+export const HOSTED_MAX_JOB_MS = 2 * 3_600_000;
+const int = (v: unknown, min: number, max: number) => typeof v === "number" && Number.isSafeInteger(v) && v >= min && v <= max;
+function checkLimits(l: StudioLimits): StudioLimits {
+  if (!int(l.jobMs, 60_000, HOSTED_MAX_JOB_MS) || !int(l.unitMs, 10_000, 600_000) || !int(l.threads, 1, 8) || (l.height !== 720 && l.height !== 1080)
+    || !int(l.intermediateBytes, 1, 4 * 1024 ** 3) || !int(l.exportBytes, 1, EXPORT_BYTES)) throw new Error("Invalid studio limits");
+  return Object.freeze({ jobMs: l.jobMs, unitMs: l.unitMs, threads: l.threads, height: l.height, intermediateBytes: l.intermediateBytes, exportBytes: l.exportBytes });
+}
+type Span = { start: number; end: number };
+type TextSpan = Span & { text: string };
+export type EditPlan = { source: string; cuts: Span[]; captions: TextSpan[]; callouts: TextSpan[]; supportingAsset?: Span & { id: string } };
+type Media = { duration: number; videoDuration: number; width: number; height: number; hasAudio: boolean; fps: number };
+type Asset = { id: string; path: string; origin: "higgsfield" | "local"; reference: string; sha256: string; verifiedByProvider: false; charged: false };
+const MAX_BYTES = MEDIA_BYTES;
+const MAX_SECONDS = 120;
+const TIMEOUT = 90_000;
+const BASE = ".crew-studio";
+
+// maxMs is set only by openStudio from checked limits: one hour, or a hosted job's longer deadline.
+export function assertGrant(g: StudioGrant & { maxMs?: number }): void {
+  if (g.enabled !== true) throw new Error("Studio disabled: explicit local opt-in required");
+  if (!Number.isFinite(g.expiresAt) || g.expiresAt <= Date.now() || g.expiresAt > Date.now() + (g.maxMs ?? 3_600_000)) throw new Error("Studio consent expired or exceeds its allowed window");
+}
+function objectFields(v: unknown, keys: string[], required = keys): Record<string, unknown> {
+  if (!v || typeof v !== "object" || Array.isArray(v)) throw new Error("Invalid object");
+  const o = v as Record<string, unknown>;
+  if (Object.keys(o).some((k) => !keys.includes(k)) || required.some((k) => !(k in o))) throw new Error("Unknown or missing field");
+  return o;
+}
+function number(v: unknown): number {
+  if (typeof v !== "number" || !Number.isFinite(v) || v < 0 || v > MAX_SECONDS) throw new Error("Invalid time");
+  return v;
+}
+function span(v: unknown, text = false): Span | TextSpan {
+  const o = objectFields(v, text ? ["start", "end", "text"] : ["start", "end"]);
+  const start = number(o.start), end = number(o.end);
+  if (end <= start || end - start < 0.1) throw new Error("Invalid span");
+  if (!text) return { start, end };
+  if (typeof o.text !== "string" || !/^[\p{L}\p{N} .,!?/:+&()%-]{1,80}$/u.test(o.text)) throw new Error("Use plain caption/callout text (80 characters maximum)");
+  return { start, end, text: o.text };
+}
+function mediaName(v: unknown): string {
+  if (typeof v !== "string" || isAbsolute(v) || !/^[a-zA-Z0-9_./ -]+\.mp4$/.test(v) || v.split("/").some((s) => !s || s === "." || s === "..") || v.length > 240) throw new Error("Only project-relative MP4 media paths allowed");
+  return v;
+}
+export function validatePlan(v: unknown): EditPlan | SourcePlan {
+  if (v && typeof v === "object" && "version" in v) return validateSourcePlan(v, mediaName);
+  const o = objectFields(v, ["source", "cuts", "captions", "callouts", "supportingAsset"], ["source", "cuts", "captions", "callouts"]);
+  const list = (x: unknown, max: number) => { if (!Array.isArray(x) || x.length > max) throw new Error("Too many edit entries"); return x; };
+  const cuts = list(o.cuts, 12).map((c) => span(c) as Span);
+  if (!cuts.length) throw new Error("At least one original cut required");
+  let total = cuts.reduce((n, c) => n + c.end - c.start, 0);
+  let supportingAsset: EditPlan["supportingAsset"];
+  if (o.supportingAsset !== undefined) {
+    const a = objectFields(o.supportingAsset, ["id", "start", "end"]);
+    if (typeof a.id !== "string" || !/^[a-f0-9-]{36}$/.test(a.id)) throw new Error("Invalid asset ID");
+    supportingAsset = { ...span({ start: a.start, end: a.end }), id: a.id };
+    total += supportingAsset.end - supportingAsset.start;
+  }
+  if (total > MAX_SECONDS) throw new Error("Timeline exceeds 120 seconds");
+  const texts = (v: unknown) => list(v, 24).map((x) => { const s = span(x, true) as TextSpan; if (s.end > total) throw new Error("Text exceeds timeline"); return s; });
+  return { source: mediaName(o.source), cuts, captions: texts(o.captions), callouts: texts(o.callouts), ...(supportingAsset ? { supportingAsset } : {}) };
+}
+
+// All executable names, filters, codecs and resource arguments are owned here, never by the model.
+async function command(bin: "ffmpeg" | "ffprobe", args: string[], cwd: string, g: StudioGrant, signal?: AbortSignal, timeout = TIMEOUT, stderrLine?: (line: string) => void): Promise<string> {
+  assertGrant(g);
+  if (signal?.aborted) throw new Error("Studio cancelled");
+  return new Promise((resolvePromise, reject) => {
+    // Inherit the adapter/bridge group so an abrupt owner shutdown cannot orphan an encoder.
+    // FFmpeg/ffprobe do not spawn children; killTree falls back to killing this owned PID.
+    const child = spawn(bin, args, { cwd, stdio: ["ignore", "pipe", "pipe"], detached: false, windowsHide: true });
+    let stdout = "", stderr = "", reason = "", pending = "", stderrBytes = 0;
+    let force: NodeJS.Timeout | undefined;
+    const stop = (why: string) => {
+      if (reason) return;
+      reason = why;
+      // Kill only this owned media process. Wait for close before deleting files.
+      killTree(child);
+      force = setTimeout(() => killTree(child), 500);
+    };
+    const abort = () => stop("Studio cancelled");
+    signal?.addEventListener("abort", abort, { once: true });
+    const timer = setTimeout(() => stop("Studio timeout or expired consent"), Math.min(timeout, g.expiresAt - Date.now()));
+    child.stdout.on("data", (b: Buffer) => { if (reason) return; stdout += b.toString(); if (stdout.length > 512_000) stop("Media output limit"); });
+    child.stderr.on("data", (b: Buffer) => {
+      if (reason) return;
+      stderr = (stderr + b.toString()).slice(-16_000);
+      if (!stderrLine) return;
+      stderrBytes += b.length;
+      if (stderrBytes > AUDIO_SCAN_BYTES) return stop("Source audio scan byte limit");
+      pending += b.toString();
+      try {
+        let newline: number;
+        while ((newline = pending.indexOf("\n")) >= 0) {
+          if (newline > 8192) throw new Error("Source audio scan line limit");
+          stderrLine(pending.slice(0, newline)); pending = pending.slice(newline + 1);
+        }
+        if (pending.length > 8192) throw new Error("Source audio scan line limit");
+      } catch (e) { stop((e as Error).message); }
+    });
+    child.on("error", () => { reason = `${bin} unavailable: install FFmpeg/ffprobe locally; no automatic download`; });
+    child.on("close", (code) => {
+      clearTimeout(timer); clearTimeout(force); signal?.removeEventListener("abort", abort);
+      if (!reason && stderrLine && pending) { try { stderrLine(pending); } catch (e) { reason = (e as Error).message; } }
+      if (reason || code !== 0) reject(new Error(reason || `Media process failed: ${stderr.slice(-4000)}`));
+      else resolvePromise(stdout);
+    });
+  });
+}
+
+export async function openStudio(input: StudioGrant, limitsInput: StudioLimits = LOCAL_LIMITS) {
+  // Copy authority once, never retain mutable caller/model-owned objects.
+  const limits = checkLimits(limitsInput);
+  const t = String(limits.threads);
+  // Source decode and the final encode may use the job deadline less five minutes (10 of the local 15).
+  const longMs = limits.jobMs - 300_000;
+  const g = Object.freeze({ root: input.root, enabled: input.enabled, expiresAt: input.expiresAt, maxMs: Math.max(3_600_000, limits.jobMs) });
+  assertGrant(g);
+  if (!isAbsolute(g.root) || resolve(g.root) !== g.root) throw new Error("Select a canonical absolute project root explicitly");
+  const canonical = await realpath(g.root);
+  if (canonical !== g.root || !(await lstat(g.root)).isDirectory()) throw new Error("Project root must not use symlinks");
+  const safe = async (name: string, directory = false, maxBytes = MAX_BYTES) => {
+    assertGrant(g);
+    if (isAbsolute(name) || name.split("/").some((s) => !s || s === "." || s === "..") || !/^[a-zA-Z0-9_./ -]+$/.test(name)) throw new Error("Unsafe project path");
+    if (await realpath(g.root) !== canonical) throw new Error("Project root changed");
+    let path = g.root;
+    for (const part of name.split("/")) {
+      path = join(path, part);
+      const info = await lstat(path);
+      if (info.isSymbolicLink()) throw new Error("Symlink denied");
+    }
+    const info = await lstat(path);
+    if (directory ? !info.isDirectory() : !info.isFile()) throw new Error("Not a regular project file/directory");
+    if (!directory && info.size > maxBytes) throw new Error("Media size limit");
+    return path;
+  };
+  const data = async (name: string): Promise<Buffer> => {
+    const path = await safe(name);
+    const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+      const s = await file.stat();
+      if (!s.isFile() || s.size > MAX_BYTES) throw new Error("Media size limit");
+      const b = await file.readFile();
+      if (b.length > MAX_BYTES) throw new Error("Media size limit");
+      return b;
+    } finally { await file.close(); }
+  };
+  const privateDir = async () => {
+    await mkdir(join(g.root, BASE), { mode: 0o700 }).catch((e: NodeJS.ErrnoException) => { if (e.code !== "EEXIST") throw e; });
+    return safe(BASE, true);
+  };
+  const probeFile = async (path: string, signal?: AbortSignal, expected?: number, long = false, grant = g, expectedAudio = true): Promise<Media> => {
+    const maxBytes = long ? (expected === undefined ? SOURCE_BYTES : EXPORT_BYTES) : MAX_BYTES;
+    const maxSeconds = long ? SOURCE_SECONDS : MAX_SECONDS;
+    const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+      const info = await file.stat();
+      if (!info.isFile() || info.size <= 0 || info.size > maxBytes) throw new Error("Media size limit");
+      const header = Buffer.alloc(12); await file.read(header, 0, 12, 0);
+      if (header.toString("ascii", 4, 8) !== "ftyp") throw new Error("Invalid MP4 media bytes");
+    } finally { await file.close(); }
+    const raw = await command("ffprobe", ["-v", "error", "-protocol_whitelist", "file", "-format_whitelist", "mov", "-show_entries", "format=duration,format_name:stream=codec_type,codec_name,profile,channels,width,height,duration,start_time,avg_frame_rate,sample_rate,nb_frames", "-of", "json", path], g.root, grant, signal);
+    type Stream = { codec_type: string; codec_name?: string; profile?: string; channels?: number; width?: number; height?: number; duration?: string; start_time?: string; avg_frame_rate?: string; sample_rate?: string; nb_frames?: string };
+    const parsed = JSON.parse(raw) as { format?: { duration?: string }; streams?: Stream[] };
+    const duration = Number(parsed.format?.duration);
+    const video = parsed.streams?.find((s) => s.codec_type === "video");
+    const audio = parsed.streams?.filter((s) => s.codec_type === "audio") ?? [];
+    if (!video?.width || !video.height || video.width > 3840 || video.height > 2160 || !Number.isFinite(duration) || duration <= 0 || (parsed.streams?.length ?? 0) > 8) throw new Error("Unsupported media metadata/size/duration");
+    const [num, den] = (video.avg_frame_rate ?? "").split("/").map(Number);
+    const fps = (num ?? NaN) / (den ?? NaN);
+    if (long && (!Number.isFinite(fps) || fps < 1 || fps > 120)) throw new Error("Unsupported source frame cadence (1-120 fps)");
+    // Never turn low/malformed source frame rates into an unbounded duration allowance.
+    const frame = Number.isFinite(fps) && fps >= 24 ? 1 / fps : 0;
+    const audioSlack = (s: Stream) => {
+      const rate = Number(s.sample_rate);
+      return Number.isFinite(rate) && rate >= 8000 ? Math.min(1024 / rate, 1024 / 48000) : 0;
+    };
+    const videoDuration = Number(video.duration);
+    if (!Number.isFinite(videoDuration) || videoDuration <= 0 || videoDuration > maxSeconds) throw new Error("Unsupported video duration");
+    for (const s of [video, ...audio]) {
+      const length = Number(s.duration), start = Number(s.start_time ?? 0);
+      const slack = s.codec_type === "video" ? frame : frame + 2 * audioSlack(s);
+      if (!Number.isFinite(length) || length <= 0 || !Number.isFinite(start) || Math.abs(start) > slack + 0.001 || length > maxSeconds + slack + 0.001) throw new Error("Unsupported stream duration");
+      if (expected !== undefined && Math.abs(length - expected) > slack + 0.001) throw new Error(`Incomplete media: ${path.split("/").at(-1)} ${s.codec_type} duration ${length} does not match timeline ${expected}`);
+    }
+    const muxSlack = frame + Math.max(0, ...audio.map(audioSlack));
+    const streamEnd = Math.max(...[video, ...audio].map((s) => Number(s.duration) + Number(s.start_time ?? 0)));
+    if (duration > maxSeconds + muxSlack + 0.001 || Math.abs(duration - streamEnd) > muxSlack + 0.001 || (expected !== undefined && audio.length !== (expectedAudio ? 1 : 0))) throw new Error("Incomplete media: unsupported container duration/completion");
+    if (long && expected !== undefined && (video.avg_frame_rate !== "30/1" || Number(video.nb_frames) !== Math.round(expected * 30))) throw new Error("Incomplete media: frame cadence/count mismatch");
+    // A valid header and probeable index do not establish that packets can actually decode.
+    const admission = long && expected === undefined && audio.length ? sourceAudioAdmission(audio) : undefined;
+    // This is the existing strict full decode, with bounded streamed metadata
+    // only. No async/resampling here: inspect the actual decoder clock before
+    // aresample can allocate gap-sized silence. Same input origin as final pass.
+    await command("ffmpeg", ["-hide_banner", "-loglevel", admission ? "info" : "error", "-nostats", "-nostdin", "-xerror", "-err_detect", "explode", "-threads", t, "-filter_threads", t, "-protocol_whitelist", "file", "-format_whitelist", "mov", "-i", path, "-map", "0:v:0", "-map", "0:a?", ...(admission ? ["-af", `asettb=1/${AUDIO_CLOCK_HZ},ashowinfo`] : []), "-f", "null", "-"], g.root, grant, signal, long ? longMs : TIMEOUT, admission?.line);
+    admission?.finish();
+    return { duration, videoDuration, width: video.width, height: video.height, hasAudio: audio.length > 0, fps };
+  };
+  const sha = (b: Buffer) => createHash("sha256").update(b).digest("hex");
+  const probe = async (name: string) => probeFile(await safe(mediaName(name)));
+  const readPlan = async (name: string) => {
+    if (!name.endsWith(".json")) throw new Error("Select a JSON edit plan");
+    const b = await data(name); if (b.length > 64_000) throw new Error("Plan size limit");
+    return validatePlan(JSON.parse(b.toString("utf8")));
+  };
+  const importAsset = async (value: unknown): Promise<Asset> => {
+    const o = objectFields(value, ["path", "origin", "reference"]);
+    const path = mediaName(o.path);
+    if (o.origin !== "higgsfield" && o.origin !== "local") throw new Error("Unknown asset origin");
+    if (typeof o.reference !== "string" || !/^[a-zA-Z0-9 _.:/-]{1,160}$/.test(o.reference)) throw new Error("Include a plain provenance reference");
+    await probe(path);
+    const bytes = await data(path);
+    const asset: Asset = { id: randomUUID(), path, origin: o.origin, reference: o.reference, sha256: sha(bytes), verifiedByProvider: false, charged: false };
+    const dir = await privateDir();
+    await writeFile(join(dir, `asset-${asset.id}.json`), JSON.stringify(asset, null, 2), { flag: "wx", mode: 0o600 });
+    return asset;
+  };
+  const render = async (value: unknown, options: { signal?: AbortSignal; preview?: boolean } = {}) => {
+    assertGrant(g);
+    if (options.signal?.aborted) throw new Error("Studio cancelled");
+    const validated = validatePlan(value);
+    const sourcePlan = "version" in validated ? validated : undefined;
+    const mapping = sourcePlan ? compileSourcePlan(sourcePlan) : undefined;
+    const p: EditPlan = sourcePlan ? { source: sourcePlan.source, cuts: mapping!, captions: [], callouts: [] } : validated as EditPlan;
+    const jobGrant = Object.freeze({ ...g, expiresAt: Math.min(g.expiresAt, Date.now() + limits.jobMs) });
+    const budget = sourcePlan ? limits.intermediateBytes : MAX_BYTES, exportBudget = sourcePlan ? limits.exportBytes : MAX_BYTES;
+    const base = await privateDir();
+    const lock = join(base, "lock");
+    try { await mkdir(lock, { mode: 0o700 }); } catch { throw new Error("Studio busy: inspect the owned lock after a crash before removing it"); }
+    const job = `job-${randomUUID()}`;
+    const dir = join(base, job);
+    try {
+      await mkdir(dir, { mode: 0o700 });
+      // The member's selected intro: snapshot it like a supporting asset, then admit the
+      // copy with the same strict v2 decode and audio-clock rules as the source, before
+      // spending time on the long source. Only whole 30fps frames of its picture are used.
+      let intro: { path: string; sha256: string; frames: number; media: Media } | undefined;
+      if (sourcePlan?.intro) {
+        const bytes = await data(sourcePlan.intro);
+        const disk = await statfs(base);
+        if (disk.bavail * disk.bsize < bytes.length + 256 * 1024 ** 2) throw new Error("Insufficient local disk budget for the intro");
+        await writeFile(join(dir, "intro.mp4"), bytes, { flag: "wx", mode: 0o600 });
+        // Short-form metadata limits (<=120s) refuse a long intro before any full decode.
+        await probeFile(join(dir, "intro.mp4"), options.signal, undefined, false, jobGrant).catch((e: Error) => { throw new Error(`Intro must be an MP4 of at most 120 seconds: ${e.message}`); });
+        const media = await probeFile(join(dir, "intro.mp4"), options.signal, undefined, true, jobGrant);
+        const frames = Math.floor(media.videoDuration * 30 + 1e-6);
+        if (!frames) throw new Error("Intro has no whole output frame");
+        if (mapping!.reduce((n, s) => n + s.end - s.start, 0) + frames / 30 > SOURCE_SECONDS) throw new Error("Edited programme plus intro exceeds 90 minutes");
+        intro = { path: sourcePlan.intro, sha256: sha(bytes), frames, media };
+      }
+      // Snapshot in bounded chunks, hash exactly the bytes the encoder will read.
+      const sourcePath = await safe(p.source, false, sourcePlan ? SOURCE_BYTES : MAX_BYTES);
+      const input = await open(sourcePath, constants.O_RDONLY | constants.O_NOFOLLOW);
+      let sourceHash: string;
+      let sourceMedia: Media | undefined;
+      try {
+        const info = await input.stat();
+        if (!info.isFile() || info.size > (sourcePlan ? SOURCE_BYTES : MAX_BYTES)) throw new Error("Media size limit");
+        const disk = await statfs(base);
+        if (disk.bavail * disk.bsize < info.size + budget + exportBudget + 256 * 1024 ** 2) throw new Error("Insufficient local disk budget for snapshot, intermediates and export");
+        if (sourcePlan) sourceMedia = await probeFile(sourcePath, options.signal, undefined, true, jobGrant);
+        const copy = await open(join(dir, "source.mp4"), "wx", 0o600);
+        const hash = createHash("sha256");
+        try {
+          const buffer = Buffer.alloc(1024 * 1024);
+          let total = 0;
+          for (;;) {
+            assertGrant(jobGrant);
+            if (options.signal?.aborted) throw new Error("Studio cancelled");
+            const { bytesRead } = await input.read(buffer, 0, buffer.length, null);
+            if (!bytesRead) break;
+            total += bytesRead;
+            if (total > info.size) throw new Error("Source changed during snapshot");
+            const chunk = buffer.subarray(0, bytesRead);
+            hash.update(chunk);
+            let written = 0;
+            while (written < bytesRead) written += (await copy.write(chunk, written, bytesRead-written)).bytesWritten;
+          }
+          const after = await input.stat();
+          const selected = await lstat(sourcePath);
+          if (selected.isSymbolicLink() || selected.dev !== info.dev || selected.ino !== info.ino || total !== info.size || after.mtimeMs !== info.mtimeMs || after.ctimeMs !== info.ctimeMs) throw new Error("Source changed during admission/snapshot");
+          sourceHash = hash.digest("hex");
+        } finally { await copy.close(); }
+      } finally { await input.close(); }
+      sourceMedia ??= await probeFile(join(dir, "source.mp4"), options.signal, undefined, false, jobGrant);
+      if (sourcePlan && Math.abs(sourceMedia.duration-sourcePlan.sourceDuration) > 0.05) throw new Error("Declared source duration does not match selected recording");
+      if (sourcePlan?.crop && (sourcePlan.crop.x + sourcePlan.crop.width > sourceMedia.width || sourcePlan.crop.y + sourcePlan.crop.height > sourceMedia.height)) throw new Error("Crop outside source picture");
+      let asset: Asset | undefined;
+      if (p.supportingAsset) {
+        const b = await data(`${BASE}/asset-${p.supportingAsset.id}.json`);
+        asset = JSON.parse(b.toString()) as Asset;
+        const extra = await data(mediaName(asset.path));
+        if (sha(extra) !== asset.sha256) throw new Error("Imported asset changed: reimport explicitly");
+        await writeFile(join(dir, "asset.mp4"), extra, { flag: "wx" });
+      }
+      const introUnits = intro ? Array.from({ length: Math.ceil(intro.frames / 900) }, (_, i) => ({ start: i * 30, end: Math.min(intro!.frames, (i + 1) * 900) / 30, mute: false, frame: undefined, file: "intro.mp4", media: intro!.media, intro: true })) : [];
+      const segments = [...introUnits, ...p.cuts.map((cut, i) => ({ ...cut, mute: mapping?.[i]?.mute ?? false, frame: mapping?.[i]?.frame, file: "source.mp4", media: sourceMedia, intro: false }))];
+      if (segments.length > 384) throw new Error("Source plan segment budget exceeded");
+      if (p.supportingAsset) segments.push({ start: p.supportingAsset.start, end: p.supportingAsset.end, mute: false, frame: undefined, file: "asset.mp4", media: await probeFile(join(dir, "asset.mp4"), options.signal), intro: false });
+      const height = options.preview ? 360 : limits.height, width = height * 16 / 9;
+      let intermediateBytes = 0;
+      for (const [i, s] of segments.entries()) {
+        if (s.end > s.media.duration + 0.03) throw new Error("Cut exceeds original media duration");
+        const length = s.end - s.start;
+        const args = ["-hide_banner", "-loglevel", "error", "-nostdin", "-n", "-xerror", "-threads", t, "-filter_threads", t, "-protocol_whitelist", "file", "-format_whitelist", "mov", "-ss", String(s.frame ?? s.start), "-i", s.file];
+        let audioMap = "0:a:0";
+        if (!sourcePlan && (!s.media.hasAudio || s.mute)) { args.push("-f", "lavfi", "-i", "anullsrc=r=48000:cl=stereo"); audioMap = "1:a:0"; }
+        else if (!sourcePlan && s.frame !== undefined) { args.push("-threads", t, "-protocol_whitelist", "file", "-format_whitelist", "mov", "-ss", String(s.start), "-i", s.file); audioMap = "1:a:0"; }
+        const crop = s.intro ? undefined : sourcePlan?.crop;
+        // fps needs the final source frame's display interval at EOF (e.g. 0.5s at 2fps).
+        // Source has already strictly decoded; never use padding to accept corrupt bytes.
+        const picture = [s.frame !== undefined ? "trim=end_frame=1,loop=loop=-1:size=1:start=0,setpts=N/(30*TB)" : "", crop ? `crop=${crop.width}:${crop.height}:${crop.x}:${crop.y}` : "", `scale=${width}:${height}:force_original_aspect_ratio=decrease,pad=${width}:${height}:(ow-iw)/2:(oh-ih)/2,setsar=1`, ...(sourcePlan ? [`tpad=stop_mode=clone:stop_duration=${1/s.media.fps},fps=30,setpts=N/(30*TB)`] : [])].filter(Boolean).join(",");
+        args.push("-t", String(length), "-map", "0:v:0", ...(sourcePlan ? ["-an"] : ["-map", audioMap]), "-vf", picture, "-r", "30", "-fps_mode", "cfr", "-c:v", "libx264", "-threads", t, "-preset", "veryfast", "-crf", "22", "-pix_fmt", "yuv420p", ...(sourcePlan ? [] : ["-c:a", "aac", "-ar", "48000", "-ac", "2", "-b:a", "128k"]), "-fs", String(budget-intermediateBytes), `seg-${i}.mp4`);
+        await command("ffmpeg", args, dir, jobGrant, options.signal, limits.unitMs);
+        await probeFile(join(dir, `seg-${i}.mp4`), options.signal, length, !!sourcePlan, jobGrant, !sourcePlan);
+        intermediateBytes += (await lstat(join(dir, `seg-${i}.mp4`))).size;
+        if (intermediateBytes >= budget) throw new Error("Intermediate storage budget exceeded");
+        await writeFile(join(dir, "progress.json"), JSON.stringify({ completedSegments: i+1, totalSegments: segments.length, intermediateBytes, expiresAt: jobGrant.expiresAt }), { mode: 0o600 });
+      }
+      // Pin concat offsets to requested cuts, not each muxer's rounded frame/AAC duration.
+      // Otherwise per-cut rounding accumulates beyond the final single-frame budget.
+      const timeline = segments.reduce((sum, s) => sum + s.end - s.start, 0);
+      await writeFile(join(dir, "concat.txt"), segments.map((s, i) => `file 'seg-${i}.mp4'\nduration ${s.end - s.start}`).join("\n"), { flag: "wx" });
+      const filters = ["setpts=PTS-STARTPTS,fps=30:start_time=0", ...(sourcePlan ? [] : [`drawbox=x=0:y=0:w=iw:h=8:color=0x55F5BD:t=fill`])];
+      for (const [i, t] of p.captions.entries()) {
+        await writeFile(join(dir, `caption-${i}.txt`), t.text, { flag: "wx" });
+        filters.push(`drawtext=textfile=caption-${i}.txt:expansion=none:fontcolor=white:fontsize=${Math.round(height * 0.045)}:box=1:boxcolor=black@0.8:boxborderw=14:x=(w-tw)/2:y=h-th-40:enable='between(t,${t.start},${t.end})'`);
+      }
+      for (const [i, t] of p.callouts.entries()) {
+        await writeFile(join(dir, `callout-${i}.txt`), t.text, { flag: "wx" });
+        const y = Math.round(height * 0.24);
+        filters.push(`drawbox=x=0:y=${y - 20}:w=iw*0.92:h=${Math.round(height * 0.19)}:color=0x091C28@0.92:t=fill:enable='between(t,${t.start},${t.end})'`);
+        filters.push(`drawtext=textfile=callout-${i}.txt:expansion=none:fontcolor=0x55F5BD:fontsize=${Math.round(height * 0.065)}:x='40-w*pow(max(0,1-(t-${t.start})/0.45),3)':y=${y}:alpha='min(1,(t-${t.start})/0.2)*min(1,(${t.end}-t)/0.2)':enable='between(t,${t.start},${t.end})'`);
+      }
+      // V2 never joins encoded audio. Admission bounds positive decoded-clock
+      // gaps (including start) to 2s before snapshot; swresample may buffer that
+      // silence, not a whole unbounded source gap. Decode one source audio input,
+      // place it by source PTS (fill gaps/drop overlaps), then select exact
+      // 1600-sample (1/30s at 48kHz) blocks in SOURCE coordinates,
+      // then renumber samples. No split/concat queues or full-recording PCM cache.
+      // All expression numbers come from the copied, grid-validated SourcePlan.
+      const audioInput: string[] = [];
+      let audioFilter = "aresample=async=1:first_pts=0";
+      if (sourcePlan) {
+        audioInput.push(...(sourceMedia.hasAudio
+          ? ["-threads", t, "-protocol_whitelist", "file", "-format_whitelist", "mov", "-i", "source.mp4"]
+          : ["-f", "lavfi", "-i", "anullsrc=r=48000:cl=stereo"]));
+        const intervals = (spans: { start: number; end: number }[]) => spans.map(s => `gte(n,${Math.round(s.start*30)})*lt(n,${Math.round(s.end*30)})`).join("+");
+        const last = mapping![mapping!.length-1]!.end;
+        audioFilter = ["aresample=48000:async=1:min_hard_comp=0.001:first_pts=0", `atrim=end_sample=${Math.round(last*48000)}`, "asetpts=N/SR/TB", "asetnsamples=n=1600:p=0",
+          ...(sourcePlan.mute.length ? [`volume=0:enable='${intervals(sourcePlan.mute)}'`] : []),
+          ...(sourcePlan.remove.length ? [`aselect='not(${intervals(sourcePlan.remove)})'`] : []),
+          "asetpts=N/SR/TB"].join(",");
+      }
+      let graph = ["-af", audioFilter, "-vf", filters.join(","), "-map", "0:v:0", "-map", sourcePlan ? "1:a:0" : "0:a:0"];
+      if (intro) {
+        // Intro audio (or fixed silence) is placed by PTS, converted to 48kHz stereo,
+        // padded/trimmed to exactly its picture's samples and joined once before the
+        // unchanged source chain. No music or generated sound is ever added.
+        const samples = intro.frames * 1600, stereo = "aformat=sample_fmts=fltp:sample_rates=48000:channel_layouts=stereo";
+        audioInput.push(...(intro.media.hasAudio ? ["-threads", t, "-protocol_whitelist", "file", "-format_whitelist", "mov", "-i", "intro.mp4"] : ["-f", "lavfi", "-i", "anullsrc=r=48000:cl=stereo"]));
+        graph = ["-filter_complex_threads", t, "-filter_complex", `[0:v]${filters.join(",")}[v];[2:a]aresample=48000:async=1:min_hard_comp=0.001:first_pts=0,${stereo},apad=whole_len=${samples},atrim=end_sample=${samples},asetpts=N/SR/TB[i];[1:a]${audioFilter},${stereo}[s];[i][s]concat=n=2:v=0:a=1[a]`, "-map", "[v]", "-map", "[a]"];
+      }
+      await command("ffmpeg", ["-hide_banner", "-loglevel", "error", "-nostdin", "-n", "-threads", t, "-filter_threads", t, "-protocol_whitelist", "file", "-f", "concat", "-safe", "1", "-reinit_filter", "0", "-i", "concat.txt", ...audioInput, ...(sourcePlan ? [] : ["-t", String(timeline)]), ...graph, "-r", "30", "-fps_mode", "cfr", "-c:v", "libx264", "-threads", t, "-preset", "veryfast", "-crf", "20", "-pix_fmt", "yuv420p", "-c:a", "aac", "-ar", "48000", "-ac", "2", "-b:a", "128k", "-movflags", "+faststart", "-fs", String(exportBudget), "export.mp4"], dir, jobGrant, options.signal, sourcePlan ? longMs : TIMEOUT);
+      const output = await probeFile(join(dir, "export.mp4"), options.signal, timeline, !!sourcePlan, jobGrant);
+      const outputFile = await open(join(dir, "export.mp4"), constants.O_RDONLY | constants.O_NOFOLLOW);
+      const outputHash = createHash("sha256");
+      try { for await (const chunk of outputFile.createReadStream({ autoClose: false })) outputHash.update(chunk); } finally { await outputFile.close(); }
+      assertGrant(jobGrant);
+      if (options.signal?.aborted) throw new Error("Studio cancelled");
+      const manifest = { version: sourcePlan ? 2 : 1, source: { path: p.source, sha256: sourceHash }, supportingAsset: asset ?? null, plan: validated, ...(intro ? { intro: { path: intro.path, sha256: intro.sha256, frames: intro.frames, outputStart: 0, outputEnd: intro.frames / 30 } } : {}), ...(mapping ? { mapping: intro ? compileSourcePlan(sourcePlan!, intro.frames) : mapping } : {}), output: { ...output, sha256: outputHash.digest("hex") }, encoder: "libx264", acceleration: "cpu", gpuVerified: false, createdAt: new Date().toISOString() };
+      await writeFile(join(dir, "manifest.json"), JSON.stringify(manifest, null, 2), { flag: "wx", mode: 0o600 });
+      // Keep finished output and provenance only, not temporary copies of member recordings.
+      for (const file of ["source.mp4", "intro.mp4", "asset.mp4", "concat.txt", ...segments.map((_, i) => `seg-${i}.mp4`), ...p.captions.map((_, i) => `caption-${i}.txt`), ...p.callouts.map((_, i) => `callout-${i}.txt`)]) await rm(join(dir, file), { force: true });
+      return { path: relative(g.root, join(dir, "export.mp4")).split("\\").join("/"), manifest: `${BASE}/${job}/manifest.json`, ...output };
+    } catch (e) {
+      await rm(dir, { force: true, recursive: true }); throw e;
+    } finally { await rm(lock, { force: true, recursive: true }); }
+  };
+  return Object.freeze({ probe, importAsset, render, readPlan,
+    transcribe: async (name: string): Promise<never> => { void name; assertGrant(g); throw new Error("Speech model not installed. Supply a timed transcript in the edit plan; no automatic model download."); },
+    capabilities: async () => {
+      const encoders = await command("ffmpeg", ["-hide_banner", "-encoders"], g.root, g);
+      if (!encoders.includes("libx264")) throw new Error("FFmpeg libx264 encoder unavailable");
+      return { encoder: "libx264", acceleration: "cpu", gpuVerified: false, hardwareEncodersAdvertised: ["h264_nvenc", "h264_qsv", "h264_videotoolbox"].filter((e) => encoders.includes(e)), maxDuration: MAX_SECONDS, maxBytes: MAX_BYTES, threads: limits.threads };
+    },
+  });
+}