fix(cli): long projects check to completion: boxed resumable copies, --prepare-media, idle deadline

docs/packages/cli.mdx

@@ -1047,6 +1047,13 @@ cover every finding from the full check.
 | `--layout`                                   | Layout knobs, currently `proseCoverageFloor=0.05` (0–1, default 0.15)                                                       |
 | `--browser-gpu` / `--no-browser-gpu`         | Hardware GPU capture, or deterministic SwiftShader (default: auto-detect)                                                   |
 | `--proxy` / `--no-proxy`                     | Auto-transcode browser-hostile codecs before checking (default: on)                                                        |
+| `--prepare-media`                            | Only make the browser-playable video copies, then exit: no browser, no report. `--json` lists each file as `ready`, `cached` or `failed`; exit 1 if any failed |
+
+A video Chrome cannot decode (HEVC, ProRes) is copied once, and the first check waits
+for it. A source longer than a few minutes is copied in one-minute pieces that are kept,
+so a copy that is stopped continues from its finished pieces on the next run. For a long
+project, run `hyperframes check --prepare-media` first, then the check itself finds every
+copy ready.
 
 `--caption-zone` and `--frame-check` refuse a ranged check when none of their
 configured seek samples falls inside `--range`; a requested gate never silently

packages/cli/src/commands/check.test.ts

@@ -369,13 +369,77 @@ describe("contrast sample selection", () => {
   });
 });
 
+describe("check --prepare-media", () => {
+  async function runPrepare(
+    files: Array<{ file: string; state: "ready" | "cached" | "failed"; reason?: string }>,
+    rawArgs: string[],
+  ) {
+    const { report } = await runScenario(fakeDriver());
+    const runPipeline = vi.fn(async (_project: ProjectDir, _options: CheckOptions) => report);
+    const prepareMedia = vi.fn(async (_project: ProjectDir, _options: CheckOptions) => files);
+    const log = vi.spyOn(console, "log").mockImplementation(() => undefined);
+    await runCommand(
+      createCheckCommand({
+        resolveProject: () => PROJECT,
+        runPipeline,
+        prepareMedia,
+        withMeta: (value) => value,
+      }),
+      { rawArgs },
+    );
+    return { runPipeline, prepareMedia, log };
+  }
+
+  it("makes the copies without running the check, and reports every file", async () => {
+    const files = [
+      { file: "a.mov", state: "ready" as const },
+      { file: "b.mov", state: "cached" as const },
+    ];
+    const { runPipeline, prepareMedia, log } = await runPrepare(files, [
+      "--prepare-media",
+      "--json",
+      "--no-proxy",
+    ]);
+
+    expect(runPipeline).not.toHaveBeenCalled();
+    expect(prepareMedia).toHaveBeenCalledWith(
+      PROJECT,
+      expect.objectContaining({ autoProxy: false }),
+    );
+    expect(JSON.parse(String(log.mock.calls[0]?.[0]))).toEqual({
+      ok: true,
+      prepared: files,
+      total: 2,
+      ready: 2,
+      failed: 0,
+    });
+    expect(consumeCommandResult().exitCode).toBe(0);
+  });
+
+  it("exits 1 and names the reason when a copy failed", async () => {
+    const { log } = await runPrepare(
+      [{ file: "a.mov", state: "failed", reason: "ffmpeg exited with code 1" }],
+      ["--prepare-media", "--json"],
+    );
+
+    expect(JSON.parse(String(log.mock.calls[0]?.[0]))).toMatchObject({
+      ok: false,
+      ready: 0,
+      failed: 1,
+      prepared: [{ file: "a.mov", state: "failed", reason: "ffmpeg exited with code 1" }],
+    });
+    expect(consumeCommandResult().exitCode).toBe(1);
+  });
+});
+
 it("parses the caption-zone grammar and enables the frame gate", async () => {
   const { report } = await runScenario(fakeDriver());
   const runPipeline = vi.fn(async (_project: ProjectDir, _options: CheckOptions) => report);
   vi.spyOn(console, "log").mockImplementation(() => undefined);
   const command = createCheckCommand({
     resolveProject: () => PROJECT,
     runPipeline,
+    prepareMedia: vi.fn(async () => []),
     withMeta: (value) => value,
   });
 
@@ -411,6 +475,7 @@ it("preserves caption-zone after bare --frame-check", async () => {
   const command = createCheckCommand({
     resolveProject: () => PROJECT,
     runPipeline,
+    prepareMedia: vi.fn(async () => []),
     withMeta: (value) => value,
   });
 
@@ -446,6 +511,7 @@ it("preserves --json after bare --frame-check", async () => {
   const command = createCheckCommand({
     resolveProject: () => PROJECT,
     runPipeline,
+    prepareMedia: vi.fn(async () => []),
     withMeta: (value) => value,
   });
 
@@ -472,6 +538,7 @@ it("prints a dash-prefixed --frame-check value's parse failure exactly once, not
   const command = createCheckCommand({
     resolveProject: () => PROJECT,
     runPipeline,
+    prepareMedia: vi.fn(async () => []),
     withMeta: (value) => value,
   });
 
@@ -491,6 +558,7 @@ it("no longer swallows --json after a --layout value (the wider bug class beyond
   const command = createCheckCommand({
     resolveProject: () => PROJECT,
     runPipeline,
+    prepareMedia: vi.fn(async () => []),
     withMeta: (value) => value,
   });
 
@@ -517,6 +585,7 @@ it("includes local HDR auto-promotion attribution in --json output", async () =>
   const command = createCheckCommand({
     resolveProject: () => PROJECT,
     runPipeline: vi.fn(async () => report),
+    prepareMedia: vi.fn(async () => []),
     withMeta: (value) => value,
   });
 
@@ -548,6 +617,7 @@ it("threads --no-proxy into the browser check options", async () => {
   const command = createCheckCommand({
     resolveProject: () => PROJECT,
     runPipeline,
+    prepareMedia: vi.fn(async () => []),
     withMeta: (value) => value,
   });
 
@@ -571,6 +641,7 @@ it("waits for the project lock declared in HF_TOOL_CONTEXT before running the pi
   const command = createCheckCommand({
     resolveProject: () => ({ ...PROJECT, dir }),
     runPipeline,
+    prepareMedia: vi.fn(async () => []),
     withMeta: (value) => value,
   });
   try {
@@ -591,6 +662,7 @@ it("rejects malformed caption-zone specs instead of silently disabling the gate"
   const command = createCheckCommand({
     resolveProject: () => PROJECT,
     runPipeline,
+    prepareMedia: vi.fn(async () => []),
     withMeta: (value) => ({ ...value, _meta: { version: "test" } }),
   });
 
@@ -1164,6 +1236,7 @@ describe("check pipeline", () => {
     const command = createCheckCommand({
       resolveProject: () => PROJECT,
       runPipeline: vi.fn(async () => report),
+      prepareMedia: vi.fn(async () => []),
       withMeta: (value) => ({ ...value, _meta: { version: "test" } }),
     });
 
@@ -1631,6 +1704,56 @@ describe("check pipeline", () => {
     );
   });
 
+  it("slow samples that each finish keep the check alive past 120 s", async () => {
+    vi.useFakeTimers();
+    try {
+      const collectLayout = vi.fn(async (_time: number, _tolerance: number) => {
+        await new Promise((resolve) => setTimeout(resolve, 30_000));
+        return [];
+      });
+      const driver = fakeDriver({ collectLayout });
+      const { deps } = dependencies(driver);
+      deps.runBrowserCheck = async (_project, options, motion, deadline) => {
+        deadline!.start();
+        return runAuditGrid(driver, options, motion, undefined, deadline!.enter);
+      };
+      const pending = runCheckPipeline(PROJECT, DEFAULT_CHECK_OPTIONS, deps);
+      await vi.advanceTimersByTimeAsync(2_000_000);
+      const report = await pending;
+      expect(report.runtime.findings.map((finding) => finding.code)).not.toContain(
+        "check_runtime_failure",
+      );
+      expect(collectLayout.mock.calls.length * 30).toBeGreaterThan(120);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("a long overlap pass that keeps reporting progress finishes instead of hitting a wall clock", async () => {
+    vi.useFakeTimers();
+    try {
+      const collectOverlapGrid = vi.fn(async (times: number[]) => {
+        await new Promise((resolve) => setTimeout(resolve, 10_000 * times.length));
+        return times.map((): AnchoredLayoutIssue[] => []);
+      });
+      const driver = fakeDriver({ collectOverlapGrid });
+      const { deps } = dependencies(driver);
+      deps.runBrowserCheck = async (_project, options, motion, deadline) => {
+        deadline!.start();
+        return runAuditGrid(driver, options, motion, undefined, deadline!.enter);
+      };
+      const pending = runCheckPipeline(PROJECT, DEFAULT_CHECK_OPTIONS, deps);
+      await vi.advanceTimersByTimeAsync(2_000_000);
+      const report = await pending;
+      expect(report.runtime.findings.map((finding) => finding.code)).not.toContain(
+        "check_runtime_failure",
+      );
+      expect(collectOverlapGrid.mock.calls.length).toBeGreaterThan(1);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
   it("a deadline that fires in the overlap pass names that pass in its finding", async () => {
     vi.useFakeTimers();
     try {
@@ -2320,6 +2443,7 @@ describe("layout flag grammar", () => {
     const command = createCheckCommand({
       resolveProject: () => PROJECT,
       runPipeline,
+      prepareMedia: vi.fn(async () => []),
       withMeta: (value) => value,
     });
 
@@ -2474,6 +2598,7 @@ describe("sampled finding reporting", () => {
     const command = createCheckCommand({
       resolveProject: () => PROJECT,
       runPipeline: vi.fn(async () => report),
+      prepareMedia: vi.fn(async () => []),
       withMeta: (value) => value,
     });
     const log = vi.spyOn(console, "log").mockImplementation(() => undefined);

packages/cli/src/commands/check.ts

@@ -36,12 +36,14 @@ import {
 } from "../utils/checkPipeline.js";
 import type { CaptionZoneOptions, FrameCheckOptions, LayoutOptions } from "../utils/checkTypes.js";
 import { resolveLocalBrowserGpuMode } from "../browser/gpuPolicy.js";
+import { preResolveHostileMediaProxies, type PreparedMediaFile } from "../utils/checkBrowser.js";
 
 export const examples: Example[] = [
   ["Run the full verification gate", "hyperframes check"],
   ["Output one agent-readable envelope", "hyperframes check --json"],
   ["Persist the five audited contrast frames", "hyperframes check --snapshots"],
   ["Also fail on warnings", "hyperframes check --strict"],
+  ["Make only the browser-playable video copies, then exit", "hyperframes check --prepare-media"],
 ];
 
 type SavedCheck = Pick<ArtifactRecord, "id" | "revision" | "report" | "attribution">;
@@ -50,6 +52,7 @@ type SavedCheckReport = CheckReport & { saved?: SavedCheck };
 export interface CheckCommandDependencies {
   resolveProject(dir: string | undefined): ProjectDir;
   runPipeline(project: ProjectDir, options: CheckOptions): Promise<SavedCheckReport>;
+  prepareMedia(project: ProjectDir, options: CheckOptions): Promise<PreparedMediaFile[]>;
   withMeta(value: object): object;
 }
 
@@ -70,6 +73,11 @@ const DEFAULT_COMMAND_DEPENDENCIES: CheckCommandDependencies = {
       return report;
     }
   },
+  async prepareMedia(project, options) {
+    const { bundleWithLocalizedFonts } = await import("../utils/bundleWithLocalizedFonts.js");
+    const html = await bundleWithLocalizedFonts(project.dir);
+    return (await preResolveHostileMediaProxies(project.dir, html, options.autoProxy)).files;
+  },
   withMeta,
 };
 
@@ -211,6 +219,12 @@ const CHECK_COMMAND_ARGS = {
     description: "Exit non-zero on warnings too",
     default: false,
   },
+  "prepare-media": {
+    type: "boolean",
+    description:
+      "Only make the browser-playable copies of videos Chrome cannot decode, then exit (no browser, no report). Stopped copies resume on the next run",
+    default: false,
+  },
   proxy: {
     type: "boolean",
     description:
@@ -264,6 +278,10 @@ export function createCheckCommand(
         if (!asJson) {
           console.log(`${c.accent("◆")}  Checking ${c.accent(project.name)}`);
         }
+        if (args["prepare-media"] === true) {
+          await runPrepareMedia(dependencies, project, options, asJson);
+          return;
+        }
         const report = await withProjectLock(project.dir, "check", () =>
           dependencies.runPipeline(project, options),
         );
@@ -294,6 +312,40 @@ export function createCheckCommand(
   });
 }
 
+async function runPrepareMedia(
+  dependencies: CheckCommandDependencies,
+  project: ProjectDir,
+  options: CheckOptions,
+  asJson: boolean,
+): Promise<void> {
+  const files = await withProjectLock(project.dir, "check", () =>
+    dependencies.prepareMedia(project, options),
+  );
+  const failed = files.filter((file) => file.state === "failed");
+  if (asJson) {
+    console.log(
+      JSON.stringify(
+        dependencies.withMeta({
+          ok: failed.length === 0,
+          prepared: files,
+          total: files.length,
+          ready: files.length - failed.length,
+          failed: failed.length,
+        }),
+        null,
+        2,
+      ),
+    );
+  } else {
+    const mark = failed.length === 0 ? c.success("✓") : c.error("✗");
+    console.log(
+      `${mark}  Browser-playable copies: ${files.length - failed.length}/${files.length} ready`,
+    );
+    for (const file of failed) console.log(`   ${file.file}: ${file.reason}`);
+  }
+  setCommandExitCode(failed.length === 0 ? 0 : 1);
+}
+
 function parseCheckOptions(args: Record<string, unknown>): CheckOptions {
   const maxTransitionSamples = positiveInteger(args["max-transition-samples"], 0);
   return {