Feature/video artifact verification (#537)

* fix(release): CI wait polls the prod rung; escape the header tooltip apostrophe

get_latest_ci_conclusion defaults to the ladder's head rung, so
wait_for_ci searched slave for a release commit that lives on master
and timed out after 40 minutes with the run already green. The wait
now passes the prod branch explicitly. Also fixes the
react/no-unescaped-entities error that turned master's Panel CI red.

* fix(panel,video): dead dialog triggers behind tooltips; dotted composition ids render

HelpTip nested inside a Dialog/AlertDialog trigger puts the trigger's
click handler on the Tooltip root, which renders no DOM — the agents
Spawn item and the KB Reindex-All / Delete-index confirms were dead.
Tooltips now wrap the triggers. The video renderer accepts interior
single dots in composition ids (release-0.25.0) with '..' still
unrepresentable, and propose_video refuses an unrenderable id at
authoring time.

* fix(dispatch): restart-safe PM review turns

A leaf task in awaiting_pm_review had no periodic pickup: the closure
dispatcher bailed on childless tasks and skipped PR-bearing review
tasks as already-promoted, assuming the submit-time PM session was
still alive — an assumption every restart breaks. Proven live on the
docs-sync leaf after the 0.25.0 redeploy, which also dependency-blocked
its sibling dev task. Childless awaiting_pm_review tasks now flow to
the PM's review turn, and the merge turn respawns its PM when none is
active.

* feat(video): verify the rendered artifact, not the source

The 14s release-0.25.0 cut shipped with only one of four scenes visibly
registering: the dev authored DOM, the smoke asserted DOM, QA read code —
nobody consumed the rendered MP4 before the CEO did. Close that loop, and
the reject loop behind it:

- sidecar frames mode: POST /render with frames=1..32 renders the cut,
  ffprobes the REAL duration, extracts midpoint-sampled keyframe PNGs
  (timestamps in filenames), streams a tar.gz back with X-Video-Duration
- request_render do-verb (developer/QA, request_sandbox's shape): renders
  the caller's ACTUAL composition — dev's own worktree (head_sha/dirty
  provenance), QA a read-only git-archive export of the assembled branch —
  extracts frames to the container-shared .previews/ path, stamps the
  render_preview marker, returns the paths as envelope evidence
- gate: i_am_done on a source=video task refuses without a stamped
  render_preview (Requirement.RENDER_VERIFIED; canonical source string
  moved to foundation as markers.VIDEO_TASK_SOURCE; mirrored in the
  possibilities-matrix fast path so it cannot bypass the check)
- QA claim_review evidence carries video_context (composition id, the
  dev's preview, a re-render instruction) so review checks output
- dev spawn prompt block + a 4th authoring AC order Read-every-frame
  verification before submitting
- reject -> re-author: a CEO reject with a reason opens a fresh authoring
  task carrying the verbatim feedback + a revise-in-place pointer at the
  existing composition (best-effort, never fails the reject) — rejection
  feedback no longer dies on the cancelled draft

E2E: rendered the committed release-0.25.0 composition through the new
frames mode locally — the returned keyframes show exactly the reported
failure (blank frame at 5.8s, only 'Env ladder' by 12.8s), the check the
fleet was missing.

---------

Co-authored-by: Renn F <rennf93@users.noreply.github.com>

video-renderer/render.js

@@ -8,13 +8,17 @@
 // render call produces its own temp file the caller cleans up once it has
 // streamed the response.
 import { createRenderJob, executeRenderJob } from "@hyperframes/producer";
+import { execFile } from "node:child_process";
 import { existsSync } from "node:fs";
 import { cp, mkdtemp, readdir, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { Readable } from "node:stream";
+import { promisify } from "node:util";
 import * as tar from "tar";
 
+const execFileP = promisify(execFile);
+
 // @hyperframes/producer reads each cut's dimensions from the composition HTML
 // itself (data-width/data-height on the stage), so the sidecar no longer
 // passes width/height — it only picks the quality tier.
@@ -247,4 +251,85 @@ export async function renderComposition({
     }
     throw err;
   }
+}
+
+export const MAX_PREVIEW_FRAMES = 32;
+
+// Downscaled so agents reading the frames as images get a small file that
+// still keeps on-screen copy legible (720 wide ≈ half of a 1080 cut).
+const PREVIEW_FRAME_WIDTH = 720;
+
+/**
+ * Render one cut and extract `frameCount` evenly spaced keyframes from it —
+ * the preview surface behind the fleet's `request_render` verb, so an agent
+ * can verify the actual artifact instead of the composition source. Samples
+ * scene MIDPOINTS (duration * (i + 0.5) / N), never t=0 or t=duration, so a
+ * fade-in first frame or an EOF seek can't produce a blank/missing frame.
+ * Returns the frames tarball path, the probed real duration, and a cleanup
+ * callback the caller MUST invoke after streaming.
+ */
+export async function renderFrames({
+  tarBuffer,
+  compositionId,
+  inputProps,
+  orientation,
+  frameCount,
+}) {
+  const { outputLocation, cleanup: cleanupRender } = await renderComposition({
+    tarBuffer,
+    compositionId,
+    inputProps,
+    orientation,
+  });
+  let framesDir;
+  try {
+    // ffprobe the RENDERED file rather than trusting the composition's
+    // data-duration attribute — the whole point is ground truth.
+    const { stdout } = await execFileP("ffprobe", [
+      "-v", "error",
+      "-show_entries", "format=duration",
+      "-of", "csv=p=0",
+      outputLocation,
+    ]);
+    const duration = Number(stdout.trim());
+    if (!Number.isFinite(duration) || duration <= 0) {
+      throw new Error("could not probe rendered video duration");
+    }
+
+    framesDir = await mkdtemp(path.join(tmpdir(), "hyperframes-frames-"));
+    const files = [];
+    for (let i = 0; i < frameCount; i++) {
+      const t = (duration * (i + 0.5)) / frameCount;
+      // Timestamp in the filename — self-describing, no manifest needed.
+      const name = `frame-${String(i + 1).padStart(2, "0")}-of-${frameCount}-at-${t.toFixed(1)}s.png`;
+      await execFileP("ffmpeg", [
+        "-v", "error",
+        "-ss", t.toFixed(3),
+        "-i", outputLocation,
+        "-frames:v", "1",
+        "-vf", `scale=${PREVIEW_FRAME_WIDTH}:-2`,
+        "-y",
+        path.join(framesDir, name),
+      ]);
+      files.push(name);
+    }
+
+    const tarPath = path.join(framesDir, "frames.tar.gz");
+    await tar.create({ gzip: true, cwd: framesDir, file: tarPath }, files);
+    return {
+      tarPath,
+      duration,
+      cleanup: () =>
+        Promise.all([
+          cleanupRender(),
+          rm(framesDir, { recursive: true, force: true }).catch(() => {}),
+        ]),
+    };
+  } catch (err) {
+    await cleanupRender();
+    if (framesDir) {
+      await rm(framesDir, { recursive: true, force: true }).catch(() => {});
+    }
+    throw err;
+  }
 }