flowviant 0.125.22 → 0.125.24

package/bin/lib/videoRender.mjs

@@ -0,0 +1,529 @@
+/**
+ * THE VIDEO CARD'S RENDER TOOL — `card_video.render_video` (2026-10-26, the
+ * owner: video gets "own kind" that hands back real files).
+ *
+ * Neither Claude Code nor Codex makes video. Each WRITES CODE that draws an
+ * animation — an HTML page of CSS, canvas, SVG or WebGL — and this tool turns
+ * that page into the file the card hands back: a GIF, an MP4 or a WebM, under
+ * `.flowviant/artifacts/`. The agent calls it, reads what it made (the answer
+ * carries a contact sheet of its first, middle and last frames), and renders
+ * again until it is right.
+ *
+ * WHY A DAEMON TOOL AND NOT A WIDER FENCE. The card runs under the design
+ * posture on both CLIs — read the repo, write only the artifacts directory and
+ * scratch — and that posture stays exactly what it is. Letting the turn run a
+ * browser and an encoder itself would have meant an OS sandbox on Claude
+ * (whose default leaves the worktree writable, and which native Windows does
+ * not have) and a Chrome inside Codex's bubblewrap. Here the browser runs in
+ * the daemon, under the capture that already holds a model-written page to
+ * one URL with its network fenced (`pinnedCapture.mjs`), the same one the
+ * mockup thumbnail and the 3D model's export use, and the page it renders is
+ * the SCRUBBED source (`uplinkScrub.mjs`), as the thumbnail is, so a value
+ * from this machine's environment never reaches a pixel.
+ *
+ * HOW A FRAME IS TAKEN. The page runs in real time but on a clock of its own
+ * (`VIDEO_CLOCK`, installed before its scripts): `performance.now()`, `Date`,
+ * timers and requestAnimationFrame read and fire on it, and CSS, Web and SVG
+ * (SMIL) animations are pinned to it, so each frame is the page exactly one
+ * step after the last, whatever the machine's speed, at about 30–60 ms of
+ * wall time a frame (Chrome 149, 2026-10-26). Chrome's own virtual time was
+ * measured unusable for this (pinnedCapture.mjs): screenshots hung once a
+ * finite animation ended, and CSS time ran ahead of the step.
+ *
+ * HOW A FILE IS MADE (videoEncode.mjs). A GIF is encoded here. An MP4 (H.264)
+ * or WebM (VP9, else VP8) is encoded by the browser's own WebCodecs, in a
+ * second browser holding a page of the daemon's own, and muxed here. MEASURED
+ * the same day: no ffmpeg on the machine, and none needed.
+ *
+ * WHAT STOPS A RENDER, IN WORDS: no browser on the machine (the turn says so
+ * and stops — the contract forbids handing back a still or the page in place
+ * of the file), a page that leaves itself, an encoder this browser lacks, and
+ * a file over its ceiling (GIF 2 MB, MP4/WebM 32 MB — the artifact policy's).
+ *
+ * THE HELD-TOOL SHAPE is uiReview.mjs's: the daemon listens on loopback for
+ * this one run behind a capability, and `flowviant __video-render-mcp` is the
+ * thin stdio MCP the CLI mounts as `card_video` (workAgentTools.mjs).
+ */
+import { createHash } from 'node:crypto';
+import { lstatSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { deflateSync } from 'node:zlib';
+import { isAbsolute, join, resolve } from 'node:path';
+import { ARTIFACT_MAX_BYTES, ARTIFACT_VIDEO_MAX_BYTES } from './artifactPolicy.mjs';
+import { ARTIFACT_DIR, FENCE_TMP_DIR, ensureArtifactDir } from './artifacts.mjs';
+import { capturePinnedPage } from './pinnedCapture.mjs';
+import { previewSubresourceAllowed, serveArtifactPage } from './artifactPreview.mjs';
+import { createGifEncoder, decodePng, muxMp4, muxWebm, sniffVideo, toRgb } from './videoEncode.mjs';
+import { scrub } from './uplinkScrub.mjs';
+import { listenHeldTool, heldToolArgv } from './heldTool.mjs';
+import { serveMcpStdio } from './mcpStdio.mjs';
+
+/** The MCP server's name on a video turn, and its one tool. */
+export const VIDEO_SERVER = 'card_video';
+export const VIDEO_TOOL = 'render_video';
+
+/** The bounds of one render. A runaway bound, never a budget: inside them the
+ *  agent chooses. GIF's are tighter — every frame is encoded here, in the
+ *  daemon, and browsers clamp a GIF delay under 2 cs to 10 cs. */
+export const VIDEO_LIMITS = Object.freeze({
+  minSide: 16,
+  maxSide: 1920,
+  maxGifSide: 1280,
+  maxFps: 60,
+  maxGifFps: 50,
+  maxSeconds: 60,
+  maxFrames: 1800,
+  maxGifFrames: 400,
+  maxPageBytes: 2 * 1024 * 1024,
+});
+/** How long one render may take, and so the tool call's timeout on Codex
+ *  (whose MCP default is 60 s). */
+export const VIDEO_RENDER_TIMEOUT_MS = 300_000;
+
+/**
+ * THE PAGE'S OWN CLOCK (2026-10-26), installed before the page's scripts —
+ * the shape frame-exact capture tools use, because stepping Chrome's virtual
+ * time hung and drifted (pinnedCapture.mjs). Time is virtual milliseconds
+ * since the page started, and stands still until the render moves it:
+ *
+ *  · `performance.now()`, `Date.now()` and `new Date()` read it;
+ *  · `setTimeout`/`setInterval` fire on it, in time order, as it passes;
+ *  · requestAnimationFrame callbacks run once per frame, handed the frame's
+ *    time;
+ *  · every CSS animation or transition, Web Animation and SVG (SMIL)
+ *    animation is paused the first time it is seen and held to the time
+ *    since — one the page paused itself is left alone.
+ *
+ * MEASURED on Chrome 149 (2026-10-26) at 40 ms steps: performance.now(), the
+ * rAF time, a CSS animation's time and Date.now() each moved exactly 40 ms a
+ * frame and a 10 ms interval fired exactly four times; a 1 s CSS animation
+ * of 0→100 px drew at 0, 10, 20 … 100 px at 100 ms steps. Its screenshots
+ * run on real time, where an occasional one waits ~2.7 s for Chrome's next
+ * frame — slower, never stuck.
+ *
+ * `__flowviantFrame(ms)` moves the clock `ms` and draws one frame; the render
+ * screenshots after it. A callback that throws is reported as the page's own
+ * error, never as the render's. Loops are bounded per frame.
+ */
+export const VIDEO_CLOCK = `(() => {
+  'use strict';
+  let now = 0;
+  const epoch = Date.now();
+  const RealDate = Date;
+  const timers = new Map();
+  const frames = new Map();
+  let seq = 0;
+  const report = (e) => queueMicrotask(() => { throw e; });
+  const call = (fn, args) => { try { (typeof fn === 'function' ? fn : new Function(String(fn)))(...args); } catch (e) { report(e); } };
+  performance.now = () => now;
+  function FDate(...a) {
+    if (!new.target) return new RealDate(epoch + now).toString();
+    return a.length ? new RealDate(...a) : new RealDate(epoch + now);
+  }
+  FDate.prototype = RealDate.prototype;
+  FDate.now = () => epoch + now;
+  FDate.parse = RealDate.parse;
+  FDate.UTC = RealDate.UTC;
+  window.Date = FDate;
+  window.setTimeout = (fn, ms, ...args) => { const id = ++seq; timers.set(id, { at: now + Math.max(0, Number(ms) || 0), fn, args, every: 0 }); return id; };
+  window.setInterval = (fn, ms, ...args) => { const every = Math.max(1, Number(ms) || 0); const id = ++seq; timers.set(id, { at: now + every, fn, args, every }); return id; };
+  window.clearTimeout = window.clearInterval = (id) => { timers.delete(id); };
+  window.requestAnimationFrame = (cb) => { const id = ++seq; frames.set(id, cb); return id; };
+  window.cancelAnimationFrame = (id) => { frames.delete(id); };
+  const held = new WeakMap();
+  const svgs = new WeakMap();
+  // An animation's time starts when it is first seen: whatever real
+  // milliseconds it ran while the page loaded are not the page's time.
+  const pin = () => {
+    for (const a of document.getAnimations()) {
+      if (!held.has(a)) {
+        if (a.playState === 'paused') continue;
+        held.set(a, now);
+        a.pause();
+      }
+      a.currentTime = now - held.get(a);
+    }
+    for (const svg of document.querySelectorAll('svg')) {
+      if (typeof svg.setCurrentTime !== 'function') continue;
+      if (!svgs.has(svg)) { svgs.set(svg, now / 1000); svg.pauseAnimations(); }
+      svg.setCurrentTime(now / 1000 - svgs.get(svg));
+    }
+  };
+  Object.defineProperty(window, '__flowviantFrame', { value: (ms) => {
+    const until = now + Math.max(0, Number(ms) || 0);
+    for (let n = 0; n < 100000; n++) {
+      let next = null;
+      for (const [id, t] of timers) if (t.at <= until && (!next || t.at < next[1].at || (t.at === next[1].at && id < next[0]))) next = [id, t];
+      if (!next) break;
+      const [id, t] = next;
+      now = Math.max(now, t.at);
+      if (t.every) t.at += t.every; else timers.delete(id);
+      call(t.fn, t.args);
+      // What it started starts now, not at the frame's end.
+      pin();
+    }
+    now = until;
+    const due = [...frames.values()];
+    frames.clear();
+    for (const cb of due) call(cb, [now]);
+    pin();
+    return now;
+  } });
+})();`;
+
+const FORMATS = Object.freeze({ gif: 'gif', mp4: 'mp4', webm: 'webm' });
+const SCRATCH_ROOTS = [ARTIFACT_DIR, FENCE_TMP_DIR];
+
+/** A relative path inside `wt`, under the artifacts directory or the turn's
+ *  scratch, of a regular file reached through no symlink — or a refusal. */
+function pagePath(wt, raw) {
+  const rel = String(raw ?? '').replace(/^\.\//, '');
+  if (!rel || isAbsolute(rel) || rel.split(/[\\/]/).includes('..')) throw new Error(`page must be a relative path under ${ARTIFACT_DIR}/ or ${FENCE_TMP_DIR}/`);
+  if (!SCRATCH_ROOTS.some((root) => rel.startsWith(`${root}/`))) throw new Error(`page must be under ${ARTIFACT_DIR}/ or ${FENCE_TMP_DIR}/ — write the animation page there first`);
+  if (!/\.html?$/i.test(rel)) throw new Error('page must be an .html file');
+  const abs = resolve(wt, rel);
+  let stat;
+  try { stat = lstatSync(abs); } catch { throw new Error(`no page at ${rel}`); }
+  if (stat.isSymbolicLink()) throw new Error(`${rel} is a symlink; write the page itself there`);
+  if (!stat.isFile()) throw new Error(`${rel} is not a regular file`);
+  if (realpathSync(abs) !== abs) throw new Error(`${rel} is reached through a symlink`);
+  if (stat.size > VIDEO_LIMITS.maxPageBytes) throw new Error(`${rel} is over 2 MB`);
+  return { rel, abs };
+}
+
+/**
+ * One render request, checked and normalised — or a refusal in words. `out`
+ * is a bare file name whose extension is the format; it is written under the
+ * artifacts directory.
+ */
+export function validateRenderRequest(input) {
+  const req = input && typeof input === 'object' ? input : {};
+  const out = String(req.out ?? '');
+  const match = /^([A-Za-z0-9][A-Za-z0-9._-]{0,99})\.(gif|mp4|webm)$/i.exec(out);
+  if (!match) throw new Error('out must be a file name ending .gif, .mp4 or .webm (letters, digits, dot, dash, underscore; no folders)');
+  const format = FORMATS[match[2].toLowerCase()];
+  const gif = format === 'gif';
+  const int = (name, v, lo, hi) => {
+    if (!Number.isInteger(v) || v < lo || v > hi) throw new Error(`${name} must be a whole number from ${lo} to ${hi}`);
+    return v;
+  };
+  const maxSide = gif ? VIDEO_LIMITS.maxGifSide : VIDEO_LIMITS.maxSide;
+  const width = int('width', req.width, VIDEO_LIMITS.minSide, maxSide);
+  const height = int('height', req.height, VIDEO_LIMITS.minSide, maxSide);
+  if (!gif && (width % 2 || height % 2)) throw new Error('width and height must be even for MP4 and WebM');
+  const fps = int('fps', req.fps, 1, gif ? VIDEO_LIMITS.maxGifFps : VIDEO_LIMITS.maxFps);
+  const seconds = Number(req.seconds);
+  if (!Number.isFinite(seconds) || seconds <= 0 || seconds > VIDEO_LIMITS.maxSeconds) throw new Error(`seconds must be more than 0 and at most ${VIDEO_LIMITS.maxSeconds}`);
+  const start = req.start === undefined ? 0 : Number(req.start);
+  if (!Number.isFinite(start) || start < 0 || start > VIDEO_LIMITS.maxSeconds) throw new Error(`start must be from 0 to ${VIDEO_LIMITS.maxSeconds} seconds`);
+  const frames = Math.round(seconds * fps);
+  const maxFrames = gif ? VIDEO_LIMITS.maxGifFrames : VIDEO_LIMITS.maxFrames;
+  if (frames < 2) throw new Error('a render needs at least two frames (seconds × fps ≥ 2) — one frame is a still, not an animation');
+  if (frames > maxFrames) throw new Error(`${frames} frames is over the ${maxFrames}-frame bound for ${format.toUpperCase()} — lower fps or seconds`);
+  return { page: req.page, out: `${match[1]}.${format}`, format, width, height, fps, seconds, start, frames };
+}
+
+// ── The contact sheet the answer carries ────────────────────────────────
+
+/** Packed RGB → a PNG (filter 0, one IDAT). */
+export function encodePng(rgb, width, height) {
+  const raw = Buffer.alloc(height * (width * 3 + 1));
+  for (let y = 0; y < height; y++) rgb.copy(raw, y * (width * 3 + 1) + 1, y * width * 3, (y + 1) * width * 3);
+  const crcTable = encodePng.crc ??= Array.from({ length: 256 }, (_, n) => {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    return c >>> 0;
+  });
+  const chunk = (type, body) => {
+    const head = Buffer.alloc(8); head.writeUInt32BE(body.length); head.write(type, 4, 'latin1');
+    let c = 0xffffffff;
+    for (const b of Buffer.concat([head.subarray(4), body])) c = crcTable[(c ^ b) & 255] ^ (c >>> 8);
+    const tail = Buffer.alloc(4); tail.writeUInt32BE((c ^ 0xffffffff) >>> 0);
+    return Buffer.concat([head, body, tail]);
+  };
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(width); ihdr.writeUInt32BE(height, 4); ihdr[8] = 8; ihdr[9] = 2;
+  return Buffer.concat([Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]), chunk('IHDR', ihdr), chunk('IDAT', deflateSync(raw)), chunk('IEND', Buffer.alloc(0))]);
+}
+
+/** Frames side by side, each scaled (nearest) to at most 320 wide, on a white
+ *  strip with a gap — what the agent looks at to judge its own render. */
+export function contactSheet(frames) {
+  const scale = Math.min(1, 320 / frames[0].width);
+  const w = Math.max(1, Math.round(frames[0].width * scale)), h = Math.max(1, Math.round(frames[0].height * scale));
+  const gap = 8, width = frames.length * w + (frames.length - 1) * gap;
+  const rgb = Buffer.alloc(width * h * 3, 255);
+  frames.forEach((f, n) => {
+    for (let y = 0; y < h; y++) {
+      const sy = Math.min(f.height - 1, Math.floor(y / scale));
+      for (let x = 0; x < w; x++) {
+        const sx = Math.min(f.width - 1, Math.floor(x / scale));
+        f.rgb.copy(rgb, (y * width + n * (w + gap) + x) * 3, (sy * f.width + sx) * 3, (sy * f.width + sx) * 3 + 3);
+      }
+    }
+  });
+  return encodePng(rgb, width, h);
+}
+
+// ── The encoder page (the daemon's own, real time, no network) ──────────
+
+const ENCODER_CSP = "default-src 'none'; script-src 'unsafe-inline'; img-src blob: data:";
+export const ENCODER_PAGE = `<!doctype html><meta charset="utf-8"><title>encoder</title><script>
+'use strict';
+const b64 = (bytes) => { let s = ''; for (let i = 0; i < bytes.length; i += 8192) s += String.fromCharCode(...bytes.subarray(i, i + 8192)); return btoa(s); };
+const unb64 = (s) => { const bin = atob(s); const out = new Uint8Array(bin.length); for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i); return out; };
+let enc = null, failed = null, chunks = [], description = null, frameUs = 0, keyEvery = 1;
+window.__enc = {
+  async start({ candidates, width, height, fps, bitrate }) {
+    for (const codec of candidates) {
+      const config = { codec, width, height, bitrate, framerate: fps, latencyMode: 'quality', ...(codec.startsWith('avc1') ? { avc: { format: 'avc' } } : {}) };
+      let ok = false;
+      try { ok = (await VideoEncoder.isConfigSupported(config)).supported; } catch {}
+      if (!ok) continue;
+      enc = new VideoEncoder({
+        output: (chunk, meta) => {
+          const data = new Uint8Array(chunk.byteLength); chunk.copyTo(data);
+          chunks.push({ key: chunk.type === 'key', timestamp: chunk.timestamp, duration: chunk.duration ?? frameUs, data: b64(data) });
+          if (meta?.decoderConfig?.description) description = b64(new Uint8Array(meta.decoderConfig.description instanceof ArrayBuffer ? meta.decoderConfig.description : meta.decoderConfig.description.buffer));
+        },
+        error: (e) => { failed = String(e?.message ?? e); },
+      });
+      enc.configure(config);
+      frameUs = Math.round(1e6 / fps); keyEvery = Math.max(1, Math.round(fps * 2));
+      return codec;
+    }
+    return null;
+  },
+  async push(png, i) {
+    if (failed) throw new Error(failed);
+    const bitmap = await createImageBitmap(new Blob([unb64(png)], { type: 'image/png' }));
+    const frame = new VideoFrame(bitmap, { timestamp: i * frameUs, duration: frameUs });
+    enc.encode(frame, { keyFrame: i % keyEvery === 0 });
+    frame.close(); bitmap.close();
+    while (enc.encodeQueueSize > 4) await new Promise((r) => enc.addEventListener('dequeue', r, { once: true }));
+    const out = chunks; chunks = []; return out;
+  },
+  async finish() {
+    await enc.flush();
+    if (failed) throw new Error(failed);
+    const out = chunks; chunks = []; enc.close();
+    return { chunks: out, description };
+  },
+};
+</script>`;
+
+/** H.264 levels by macroblocks a frame and a second: Baseline first (the
+ *  widest playback), then Main and High at the same level. */
+export function h264Candidates(width, height, fps) {
+  const mbs = Math.ceil(width / 16) * Math.ceil(height / 16);
+  const levels = [[0x1f, 3600, 108000], [0x20, 5120, 216000], [0x28, 8192, 245760], [0x2a, 8704, 522240], [0x32, 22080, 589824]];
+  const level = (levels.find(([, frame, rate]) => mbs <= frame && mbs * fps <= rate) ?? levels.at(-1))[0].toString(16).padStart(2, '0');
+  return [`avc1.42E0${level}`, `avc1.4D00${level}`, `avc1.6400${level}`];
+}
+
+const bitrateFor = (width, height, fps) => Math.round(Math.min(12_000_000, Math.max(400_000, width * height * fps * 0.1)));
+
+/**
+ * RENDER ONE PAGE TO ONE FILE. Resolves the receipt the agent is answered
+ * with, or throws in words. `capture` is injectable for the tests; nothing in
+ * the daemon passes it.
+ */
+export async function renderVideo({ wt, request, signal, capture = capturePinnedPage }) {
+  const r = validateRenderRequest(request);
+  const { rel, abs } = pagePath(wt, r.page);
+  if (!ensureArtifactDir(wt)) throw new Error(`${ARTIFACT_DIR}/ is not a real directory in this worktree, so no file can be written`);
+  const source = Buffer.from(scrub(readFileSync(abs, 'utf8')), 'utf8');
+  const stepMs = 1000 / r.fps;
+  const keep = new Set([0, Math.floor((r.frames - 1) / 2), r.frames - 1]);
+  const sheetFrames = [];
+  const capFor = r.format === 'gif' ? ARTIFACT_MAX_BYTES : ARTIFACT_VIDEO_MAX_BYTES;
+  const capWords = `${Math.round(capFor / (1024 * 1024))} MB`;
+
+  /** Step the agent's page through every frame, handing each PNG to `onFrame`. */
+  const stepPage = async (onFrame) => {
+    const page = await serveArtifactPage(source);
+    try {
+      const result = await capture({
+        url: page.url, width: r.width, height: r.height, timeoutMs: VIDEO_RENDER_TIMEOUT_MS,
+        allowSubresource: previewSubresourceAllowed, signal, initScript: VIDEO_CLOCK,
+        work: async (held) => {
+          // Its web fonts, so frame 0 is not drawn in a fallback face.
+          await held.evaluate('document.fonts ? document.fonts.ready.then(() => true) : true');
+          await held.evaluate(`window.__flowviantFrame(${r.start * 1000})`);
+          for (let i = 0; i < r.frames; i++) {
+            signal?.throwIfAborted();
+            if (i > 0) await held.evaluate(`window.__flowviantFrame(${stepMs})`);
+            const png = await held.screenshot();
+            if (keep.has(i)) sheetFrames.push(toRgb(decodePng(png)));
+            await onFrame(png, i);
+            if (held.left()) return null;
+          }
+          return { pageError: held.pageError() };
+        },
+      });
+      if (!result.ok) {
+        if (result.reason === 'no-browser') throw new Error('No Chrome, Chromium or Edge browser was found on this machine, and rendering a video needs one. Nothing was written.');
+        throw new Error(`The page could not be rendered: ${result.message ?? result.reason}`);
+      }
+      return result.value;
+    } finally { page.close(); }
+  };
+
+  let bytes;
+  let codec = null;
+  let pageError = null;
+  if (r.format === 'gif') {
+    const gif = createGifEncoder(r.width, r.height);
+    let shown = 0;
+    ({ pageError } = await stepPage(async (png, i) => {
+      // Cumulative rounding, so the whole GIF lasts as long as was asked.
+      const until = Math.round(((i + 1) * 100) / r.fps);
+      gif.add(toRgb(decodePng(png)).rgb, Math.max(2, until - shown));
+      shown = until;
+      if (gif.bytes() > capFor) throw new Error(`The GIF passed ${capWords} at frame ${i + 1} of ${r.frames}. Lower the size, frame rate or length, use fewer colours, or render an MP4 or WebM instead. Nothing was written.`);
+    }) ?? {});
+    bytes = gif.finish();
+  } else {
+    const encoderPage = await serveArtifactPage(ENCODER_PAGE, { csp: ENCODER_CSP });
+    try {
+      const encoded = await capture({
+        url: encoderPage.url, width: 64, height: 64, timeoutMs: VIDEO_RENDER_TIMEOUT_MS, signal,
+        work: async (encoder) => {
+          const candidates = r.format === 'mp4' ? h264Candidates(r.width, r.height, r.fps) : ['vp09.00.10.08', 'vp8'];
+          codec = await encoder.evaluate(`window.__enc.start(${JSON.stringify({ candidates, width: r.width, height: r.height, fps: r.fps, bitrate: bitrateFor(r.width, r.height, r.fps) })})`);
+          if (!codec) throw new Error(`This machine's browser cannot encode ${r.format === 'mp4' ? 'H.264 for MP4' : 'VP9 or VP8 for WebM'}. Render a ${r.format === 'mp4' ? 'WebM' : 'MP4'} or a GIF instead. Nothing was written.`);
+          const chunks = [];
+          let size = 0;
+          const take = (list) => {
+            for (const c of list) {
+              const data = Buffer.from(c.data, 'base64');
+              size += data.length;
+              chunks.push({ ...c, data });
+            }
+            if (size > capFor) throw new Error(`The ${r.format.toUpperCase()} passed ${capWords}. Lower the size, frame rate or length. Nothing was written.`);
+          };
+          ({ pageError } = await stepPage(async (png, i) => take(await encoder.evaluate(`window.__enc.push(${JSON.stringify(png.toString('base64'))}, ${i})`))) ?? {});
+          const done = await encoder.evaluate('window.__enc.finish()');
+          take(done.chunks);
+          return { chunks, description: done.description ? Buffer.from(done.description, 'base64') : null };
+        },
+      });
+      if (!encoded.ok) {
+        if (encoded.reason === 'no-browser') throw new Error('No Chrome, Chromium or Edge browser was found on this machine, and rendering a video needs one. Nothing was written.');
+        throw new Error(encoded.message ?? `The encoder failed (${encoded.reason}).`);
+      }
+      const { chunks, description } = encoded.value;
+      bytes = r.format === 'mp4'
+        ? muxMp4({ width: r.width, height: r.height, description, chunks })
+        : muxWebm({ width: r.width, height: r.height, codec: codec.startsWith('vp8') ? 'V_VP8' : 'V_VP9', chunks });
+    } finally { encoderPage.close(); }
+  }
+  if (sniffVideo(bytes) !== r.format) throw new Error(`The ${r.format.toUpperCase()} came out malformed. Nothing was written.`);
+  if (bytes.length > capFor) throw new Error(`The ${r.format.toUpperCase()} is ${bytes.length} bytes, over ${capWords}. Lower the size, frame rate or length. Nothing was written.`);
+
+  const dest = join(wt, ARTIFACT_DIR, r.out);
+  try {
+    const st = lstatSync(dest);
+    if (!st.isFile()) throw new Error(`${ARTIFACT_DIR}/${r.out} exists and is not a regular file`);
+  } catch (e) { if (e.code !== 'ENOENT') throw e; }
+  const tmp = `${dest}.${process.pid}.partial`;
+  writeFileSync(tmp, bytes, { flag: 'wx' });
+  try { renameSync(tmp, dest); } catch (e) { rmSync(tmp, { force: true }); throw e; }
+  return {
+    file: `${ARTIFACT_DIR}/${r.out}`,
+    page: rel,
+    format: r.format,
+    ...(codec ? { codec } : {}),
+    width: r.width,
+    height: r.height,
+    fps: r.fps,
+    frames: r.frames,
+    seconds: r.frames / r.fps,
+    bytes: bytes.length,
+    sha256: createHash('sha256').update(bytes).digest('hex'),
+    ...(pageError ? { pageError } : {}),
+    sheet: sheetFrames.length ? contactSheet(sheetFrames).toString('base64') : null,
+  };
+}
+
+// ── The held tool and its MCP ───────────────────────────────────────────
+
+export const VIDEO_TOOL_SCHEMA = Object.freeze({
+  name: VIDEO_TOOL,
+  description: `Render an animation page you wrote into a GIF, MP4 or WebM file under ${ARTIFACT_DIR}/, in this machine's own headless browser. The page runs on a clock of its own that moves exactly one frame per step — performance.now(), Date, timers, requestAnimationFrame (handed the frame time), CSS, Web and SVG animations all read it — and is photographed at width × height. Its clock starts at 0 when the page loads. The answer names the file written and shows its first, middle and last frames; look at them before you hand the file back.`,
+  inputSchema: {
+    type: 'object',
+    properties: {
+      page: { type: 'string', description: `Relative path of the self-contained .html animation page, under ${ARTIFACT_DIR}/ or ${FENCE_TMP_DIR}/.` },
+      out: { type: 'string', description: `Output file name (no folders) ending .gif, .mp4 or .webm; written to ${ARTIFACT_DIR}/<out>, replacing a file of that name.` },
+      width: { type: 'integer', description: `Viewport and video width in pixels (${VIDEO_LIMITS.minSide}–${VIDEO_LIMITS.maxSide}; GIF at most ${VIDEO_LIMITS.maxGifSide}; even for MP4/WebM).` },
+      height: { type: 'integer', description: `Viewport and video height in pixels (same bounds as width).` },
+      fps: { type: 'integer', description: `Frames per second (1–${VIDEO_LIMITS.maxFps}; GIF at most ${VIDEO_LIMITS.maxGifFps}).` },
+      seconds: { type: 'number', description: `Length in seconds (at most ${VIDEO_LIMITS.maxSeconds}; at least two frames).` },
+      start: { type: 'number', description: 'Seconds of the page’s clock to skip before the first frame (default 0).' },
+    },
+    required: ['page', 'out', 'width', 'height', 'fps', 'seconds'],
+    additionalProperties: false,
+  },
+});
+
+/** The run-scoped tool, daemon side. Returns `{ env, config, close }`; the
+ *  lane mounts `config` as `card_video` and closes it when the turn ends. */
+export async function createVideoRender({ wt, signal, render = renderVideo }) {
+  let closed = false, busy = false;
+  const controller = new AbortController();
+  const abort = () => controller.abort();
+  signal?.addEventListener('abort', abort, { once: true });
+  const held = await listenHeldTool({
+    envPrefix: 'FLOWVIANT_VIDEO_RENDER', verb: '__video-render', requestTimeoutMs: VIDEO_RENDER_TIMEOUT_MS + 10_000,
+    isClosed: () => closed || controller.signal.aborted,
+    respond: async (req, res) => {
+      try {
+        let body = '';
+        for await (const chunk of req) { body += chunk; if (body.length > 16 * 1024) throw new Error('The render request exceeds 16 KiB.'); }
+        if (busy) throw new Error('A render is already running on this turn; wait for it to finish.');
+        busy = true;
+        try {
+          const receipt = await render({ wt, request: JSON.parse(body), signal: controller.signal });
+          res.writeHead(200, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' }).end(JSON.stringify(receipt));
+        } finally { busy = false; }
+      } catch (error) {
+        res.writeHead(409, { 'Content-Type': 'application/json' }).end(JSON.stringify({ error: scrub(String(error?.message ?? error)).slice(0, 1000) }));
+      }
+    },
+  });
+  return {
+    env: held.env,
+    // `toolTimeoutSec` is read by the Codex mount (codexFencedMount.mjs) and
+    // never written to Claude's mcp.json (projectTools.mjs).
+    config: { command: process.execPath, args: heldToolArgv('__video-render-mcp'), env: held.env, toolTimeoutSec: Math.ceil(VIDEO_RENDER_TIMEOUT_MS / 1000) + 30 },
+    async close() {
+      closed = true; controller.abort(); held.server.close(); held.server.closeAllConnections();
+      signal?.removeEventListener('abort', abort);
+    },
+  };
+}
+
+/** `flowviant __video-render-mcp`: the stdio MCP a video turn's CLI mounts. */
+export async function videoRenderMain() {
+  await serveMcpStdio({
+    serverInfo: { name: 'card-video', version: '1.0.0' }, rawResult: true, tools: [VIDEO_TOOL_SCHEMA],
+    call: async (_name, args) => {
+      const { sheet, ...receipt } = await callVideoRender(args);
+      return { content: [{ type: 'text', text: JSON.stringify(receipt) }, ...(sheet ? [{ type: 'image', mimeType: 'image/png', data: sheet }] : [])] };
+    },
+  });
+}
+
+async function callVideoRender(input) {
+  const url = new URL(process.env.FLOWVIANT_VIDEO_RENDER_URL ?? '');
+  if (url.protocol !== 'http:' || url.hostname !== '127.0.0.1' || url.pathname !== '/' || url.username || url.password) throw new Error('No video render tool is held for this turn.');
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${process.env.FLOWVIANT_VIDEO_RENDER_CAPABILITY}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify(input),
+    signal: AbortSignal.timeout(VIDEO_RENDER_TIMEOUT_MS + 15_000),
+  });
+  const result = await response.json();
+  if (!response.ok) throw new Error(result.error ?? 'The render failed.');
+  return result;
+}

package/bin/lib/work.mjs

@@ -450,6 +450,7 @@ export function createWorkManager({
   // Retirement asks the agent lane which CLI to stop.
   const { heldSessionIds, retireWorkSessions, freshenManualPlaces } = createWorkRetire({
     repositoryPlaces, repoRoot,
+    sessionMetaPath,
     baseDir,
     baseRef,
     placeOf,

package/bin/lib/workAgentTools.mjs

@@ -26,12 +26,14 @@ import { TURN_PROFILES } from './turnProfile.mjs';
 import { postureToolsNote } from './postureTools.mjs';
 import { machineMcpServers } from './claudeMachineMcp.mjs';
 import { ORCHESTRATOR_SERVER } from './orchestratorProtocol.mjs';
+import { VIDEO_SERVER } from './videoRender.mjs';
 
 /** The servers the daemon itself mounts on a card turn, by the names the
- *  agent calls them: a multi-repository card's add_repository, and an
- *  orchestrated card's routing. Never a project server's, whatever the base
+ *  agent calls them: a multi-repository card's add_repository, an
+ *  orchestrated card's routing, a build's UI review and a video card's
+ *  render_video (2026-10-26). Never a project server's, whatever the base
  *  `.mcp.json` names. */
-export const CARD_TURN_SERVERS = Object.freeze({ repositories: 'card_repositories', orchestrator: ORCHESTRATOR_SERVER, uiReview: 'card_ui_review' });
+export const CARD_TURN_SERVERS = Object.freeze({ repositories: 'card_repositories', orchestrator: ORCHESTRATOR_SERVER, uiReview: 'card_ui_review', video: VIDEO_SERVER });
 
 /**
  * The card turn's tools, prepared, and what it is told of them.
@@ -44,7 +46,7 @@ export const CARD_TURN_SERVERS = Object.freeze({ repositories: 'card_repositorie
  * from here), the note, the mount's part of the CLI's `mcpEnv` and whether it
  * needs one, and the keys the runner takes the mount as.
  */
-export function prepareCardTools({ rt, posture, wt, repoRoot, baseRef, sources = [], repositoryTool = null, orchestratorConfig = null, uiReviewConfig = null, orchestrated = false, codexHome = null, env = process.env, machineServers = machineMcpServers }) {
+export function prepareCardTools({ rt, posture, wt, repoRoot, baseRef, sources = [], repositoryTool = null, orchestratorConfig = null, uiReviewConfig = null, videoConfig = null, orchestrated = false, codexHome = null, env = process.env, machineServers = machineMcpServers }) {
   // A turn reads the base ref afresh. Changes the agent has made to its
   // own worktree cannot silently change the next turn's tools.
   const source = sources.find((r) => r.wt === wt);
@@ -57,6 +59,8 @@ export function prepareCardTools({ rt, posture, wt, repoRoot, baseRef, sources =
     ...(repositoryTool ? { [CARD_TURN_SERVERS.repositories]: repositoryTool.config } : {}),
     ...(orchestratorConfig ? { [CARD_TURN_SERVERS.orchestrator]: orchestratorConfig } : {}),
     ...(posture === 'build' && uiReviewConfig ? { [CARD_TURN_SERVERS.uiReview]: uiReviewConfig } : {}),
+    // A video card's render tool rides its fenced posture (videoRender.mjs).
+    ...(videoConfig ? { [CARD_TURN_SERVERS.video]: videoConfig } : {}),
   } });
   try {
     const mountsProjectMcp = TURN_PROFILES[posture]?.projectMcp === true && runnerToolCapabilities(rt).mcp;

package/bin/lib/workAgentTurnBegun.mjs

@@ -13,6 +13,7 @@
  * through the one turn-done wire (workAgentTurnReports.mjs). Null means go on.
  */
 import { existsSync } from 'node:fs';
+import { join } from 'node:path';
 import { git, sessionBranchRef } from './git.mjs';
 import { worktreePath } from './workPlaces.mjs';
 
@@ -49,6 +50,9 @@ export function begunTurnRefusal(job, place, { baseDir, repoRoot, fetchPublished
   // null directory AND a null ref below, and the null ref stands the guard
   // down — the same fail-open direction as an unreadable repo.
   const wtDir = worktreePath(baseDir, place);
+  // A shell left by an interrupted setup is not the agent's git worktree.
+  // The launch path validates ownership and readability before using it.
+  const hasWorktree = Boolean(wtDir && existsSync(join(wtDir, '.git')));
   const ref = sessionBranchRef(place);
   let hasBranch = false;
   /**
@@ -76,7 +80,7 @@ export function begunTurnRefusal(job, place, { baseDir, repoRoot, fetchPublished
       else branchMeasured = false;
     }
   }
-  if (branchMeasured && !existsSync(wtDir) && !hasBranch) {
+  if (branchMeasured && !hasWorktree && !hasBranch) {
     /**
      * …UNLESS THE WORK IS ON THE REMOTE (0.86.0).
      *
@@ -110,6 +114,6 @@ export function begunTurnRefusal(job, place, { baseDir, repoRoot, fetchPublished
     // opens a worktree on it below — the same path a directory somebody
     // cleaned up already takes, on commits this box now genuinely holds.
   }
-  if (hasBranch || (wtDir && existsSync(wtDir))) onAvailable();
+  if (hasBranch || hasWorktree) onAvailable();
   return null;
 }