multiplane 0.3.7 → 0.3.8

package/README.en.md

@@ -127,11 +127,14 @@ For the full contract, patterns that break determinism, and 3D layer usage, see
 | `multiplane status <job>` | View job status |
 | `multiplane cancel <job>` | Stop a job |
 | `multiplane wait <job>` | Wait for a job to finish and print its events, for example after an agent session restarts |
+| `multiplane resume <job>` | Continue an interrupted render from where it stopped |
 | `multiplane config get\|set\|unset` | Read or change the user config |
 | `multiplane skill status\|install\|remove` | Install, update or remove the agent skill for Claude Code and Codex |
 
 Shot paths are relative to the resource root `--root` (the current directory by default). Each run has its own job directory, `out/jobs/<jobId>/`. Without `--out`, artifacts are written there (video, `stills/`, `verify/`), so runs do not overwrite each other. See `artifacts` in the result for the final paths. `--out` sets the output location. An existing target is rejected unless `--overwrite` is given. `render`, `stills`, and `verify` automatically run `lint` before starting and stop on errors. Use `--no-lint` to skip it. `npx multiplane <command> --help` lists all options for that command.
 
+`render` encodes in segments of about 10 seconds and keeps each one on disk as soon as it is done. If a render stops part way (the process is killed, the machine crashes or loses power, the browser keeps crashing, or you stop it), `multiplane resume <job>` skips the segments already encoded, renders the rest and joins them without re-encoding; the frames are identical to an uninterrupted render. A resume keeps all of the original job's options. It is refused (`resume_unavailable`) when a file the shot loaded has changed or the Multiplane, Chromium or FFmpeg version differs, so a film is never joined from mismatched parts. See section 6.1 of the protocol.
+
 Common `render` options:
 
 | Option | Meaning |

package/README.md

@@ -127,11 +127,14 @@ Shot.define({
 | `multiplane status <job>` | 查看作业状态 |
 | `multiplane cancel <job>` | 停止作业 |
 | `multiplane wait <job>` | 等一个作业结束并输出它的事件，例如 agent 会话重启之后 |
+| `multiplane resume <job>` | 中断的渲染从停下的地方接着渲 |
 | `multiplane config get\|set\|unset` | 读取或修改用户配置 |
 | `multiplane skill status\|install\|remove` | 给 Claude Code 和 Codex 安装、更新、移除 agent skill |
 
 镜头路径相对资源根 `--root`（默认当前目录）。每次运行都有自己的作业目录 `out/jobs/<jobId>/`，不给 `--out` 时产物就写在里面（视频、`stills/`、`verify/`），多次运行互不覆盖；最终路径见结果里的 `artifacts`。`--out` 指定输出位置，目标已存在时会拒绝覆盖，加 `--overwrite` 才替换。`render`、`stills`、`verify` 启动前自动跑 `lint`，有 error 就停下，`--no-lint` 跳过。`npx multiplane <command> --help` 列出该命令的全部参数。
 
+`render` 按约 10 秒一段编码，每段编完就落盘。渲染中途停下（进程被杀、死机、断电、浏览器反复崩溃、手动停止）后，`multiplane resume <job>` 会跳过已经编好的段、只渲剩下的，最后不重新编码地拼成成片，画面与一次渲完的逐帧相同。续传沿用原作业的全部参数；镜头加载过的文件改了，或 Multiplane、Chromium、FFmpeg 版本变了，会拒绝续传（`resume_unavailable`），以免拼出前后不一致的片子。见协议第 6.1 节。
+
 `render` 的常用参数：
 
 | 参数 | 含义 |

package/bin/multiplane

@@ -1,16 +1,13 @@
 #!/usr/bin/env node
-import { renderShot, stillsShot, verifyShot, inspectShot, lintShot, doctor, statusJob, cancelJob } from '../src/index.mjs';
-import { benchmark } from '../src/benchmark.mjs';
-import { serve } from '../src/serve.mjs';
-import { setup } from '../src/setup.mjs';
-import { postArgs, scaleArgs } from '../src/post.mjs';
-import { createEvents, version } from '../src/events.mjs';
+import { readFileSync } from 'node:fs';
 import { asError, invalidOption } from '../src/errors.mjs';
-import { waitJob } from '../src/jobs.mjs';
 import { claimExecutor, resultExitCode } from '../src/hosted.mjs';
 import { fileURLToPath } from 'node:url';
 
 const args = process.argv.slice(2), json = args.includes('--json');
+// Keep CLI flag metadata independent of the rendering implementation.
+const postArgs = ['quality', 'motion-blur', 'max-motion-blur', 'shutter', 'grain', 'no-post', 'adaptive-blur'];
+const scaleArgs = ['scale', 'render-scale', 'upscale'];
 const common = [...postArgs, ...scaleArgs, 'static-reuse', 'no-static-reuse', 'alpha', 'fps', 'raster', 'root', 'job-dir', 'no-lint', 'overwrite', 'no-hosted', 'job-dir-exact', 'hosted-executor'];
 const allowed = {
   inspect: ['root', 'fps', 'no-lint'], serve: ['root', 'port'],
@@ -19,6 +16,7 @@ const allowed = {
   benchmark: ['raster', 'max-workers'], config: [], skill: ['host', 'force', 'expect'],
   lint: ['root'], doctor: ['ffmpeg', 'raster'], status: ['job-dir'], cancel: ['job-dir', 'wait'],
   wait: ['job-dir', 'timeout'],
+  resume: ['job-dir', 'workers', 'no-hosted', 'job-dir-exact', 'hosted-executor'],
 };
 // Internal flags used by the desktop app to start hosted executors; not listed in help.
 const internal = ['job-dir-exact', 'hosted-executor'];
@@ -35,17 +33,18 @@ const onEvent = event => {
 };
 let command = args[0] ?? 'doctor';
 try {
-  const executor = ['render', 'stills', 'verify'].includes(command) && args.includes('--hosted-executor');
+  const executor = ['render', 'stills', 'verify', 'resume'].includes(command) && args.includes('--hosted-executor');
   const exactIndex = args.indexOf('--job-dir-exact');
   const lostClaim = executor && (exactIndex < 0 || !args[exactIndex + 1]
     || !await claimExecutor(args[exactIndex + 1], command));
   const onBytes = bytes => new Promise((resolve, reject) => process.stdout.write(bytes, error => error ? reject(error) : resolve()));
   if (lostClaim) { process.exitCode = 0; }
-  else if (args.length === 1 && args[0] === '--version') console.log(version);
+  else if (args.length === 1 && args[0] === '--version') console.log(JSON.parse(readFileSync(new URL('../package.json', import.meta.url))).version);
   else if (args.length === 0 || args[0] === '--help') {
     console.log('Usage: multiplane <render|stills|verify|inspect|lint> <shot.html> [--json] [--option value]\n'
       + '       multiplane serve [--root directory] [--port number] [--json]\n'
       + '       multiplane <status|cancel> <jobId|jobDir> [--json] [--wait seconds]\n'
+      + '       multiplane resume <jobId|jobDir> [--json] [--workers n] [--job-dir directory] [--no-hosted]\n'
       + '       multiplane wait <jobId|jobDir> [--json] [--timeout seconds]\n'
       + '       multiplane benchmark [--json] [--raster gpu|software] [--max-workers n]\n'
       + '       multiplane doctor [--json] [--ffmpeg path]\n'
@@ -56,11 +55,13 @@ try {
     if (args.includes('--help')) console.log(command === 'config'
       ? 'Usage: multiplane config <get [key]|set key value|unset key> [--json]\nKeys: ffmpeg jobsDir raster encoder workers hosted'
       : 'Usage: multiplane skill <status|install|remove> [--host claude|codex|all] [--force] [--expect signature] [--json]\nInstall and remove require --host.');
-    else await setup(command, args.slice(1), onEvent);
+    // TODO(design): setup/jobs still transitively load rendering through src/events.mjs.
+    // Removing those dependencies requires extending task 083's read-only src scope.
+    else { const { setup } = await import('../src/setup.mjs'); await setup(command, args.slice(1), onEvent); }
   } else {
     if (!allowed[command]) throw invalidOption('command', 'Unknown command: ' + command);
     if (args.includes('--help')) {
-      console.log('Usage: multiplane ' + command + (['doctor', 'serve', 'benchmark'].includes(command) ? '' : ['status', 'cancel', 'wait'].includes(command) ? ' <jobId|jobDir>' : ' <shot.html>') + ' [options]\nOptions: --json --help ' + listed(allowed[command]).map(f => '--' + f + (['static-reuse', 'no-static-reuse', 'overwrite', 'no-lint', 'no-post', 'alpha', 'draft', 'no-hosted', 'hosted-executor'].includes(f) ? '' : ' <value>')).join(' '));
+      console.log('Usage: multiplane ' + command + (['doctor', 'serve', 'benchmark'].includes(command) ? '' : ['status', 'cancel', 'wait', 'resume'].includes(command) ? ' <jobId|jobDir>' : ' <shot.html>') + ' [options]\nOptions: --json --help ' + listed(allowed[command]).map(f => '--' + f + (['static-reuse', 'no-static-reuse', 'overwrite', 'no-lint', 'no-post', 'alpha', 'draft', 'no-hosted', 'hosted-executor'].includes(f) ? '' : ' <value>')).join(' '));
     } else {
       const needsTarget = !['doctor', 'serve', 'benchmark'].includes(command);
       const target = needsTarget ? args[1] : undefined;
@@ -78,14 +79,23 @@ try {
       delete options.json;
       if (options['job-dir-exact'] && !executor) throw invalidOption('--job-dir-exact', '--job-dir-exact requires --hosted-executor.');
       options.onEvent = executor ? undefined : onEvent;
-      if (['render', 'stills', 'verify'].includes(command) && !executor) options._hostedCLI = {
+      if (['render', 'stills', 'verify', 'resume'].includes(command) && !executor) options._hostedCLI = {
         args: args.slice(1).filter(arg => arg !== '--json'), bin: fileURLToPath(import.meta.url), onBytes,
       };
       if (command === 'wait') {
+        const { waitJob } = await import('../src/jobs.mjs');
         const result = await waitJob(target, { ...options, onEvent: json ? undefined : onEvent, onBytes: json ? onBytes : undefined });
         reported = true; process.exitCode = resultExitCode(result);
       } else {
-        const action = { render: renderShot, stills: stillsShot, verify: verifyShot, inspect: inspectShot, serve, lint: lintShot, doctor, benchmark, status: statusJob, cancel: cancelJob }[command];
+        let action;
+        if (command === 'lint') {
+          const { runCommand } = await import('../src/events.mjs');
+          const { checkLint } = await import('../src/lint.mjs');
+          action = (shot, options) => runCommand('lint', shot, options, events => checkLint(shot, events.options, events), false);
+        } else {
+          const [module, name] = { render: ['render', 'renderShot'], stills: ['stills', 'stillsShot'], verify: ['verify', 'verifyShot'], inspect: ['inspect', 'inspectShot'], serve: ['serve', 'serve'], doctor: ['doctor', 'doctor'], benchmark: ['benchmark', 'benchmark'], status: ['jobs', 'statusJob'], cancel: ['jobs', 'cancelJob'], resume: ['resume', 'resumeRender'] }[command];
+          action = (await import(`../src/${module}.mjs`))[name];
+        }
         const result = needsTarget ? await action(target, options) : await action(options);
         if (result?.ok !== undefined) { reported = true; process.exitCode = resultExitCode(result); }
       }
@@ -93,6 +103,6 @@ try {
   }
 } catch (failure) {
   const error = asError(failure);
-  if (!reported) createEvents(command, null, { onEvent }).finish({}, error);
+  if (!reported) { const { createEvents } = await import('../src/events.mjs'); createEvents(command, null, { onEvent }).finish({}, error); }
   process.exitCode = error.exitCode;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "multiplane",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "type": "module",
   "license": "Apache-2.0",
   "publishConfig": {

package/skills/multiplane/SKILL.md

@@ -171,6 +171,7 @@ Use `--json` with any command. Resolve shot paths relative to `--root` (the curr
 | `multiplane status <job>` | View job status | — |
 | `multiplane cancel <job>` | Stop a job | `--wait` (seconds) |
 | `multiplane wait <job>` | Wait for a job started earlier and print its events | `--timeout` (seconds) |
+| `multiplane resume <job>` | Continue an interrupted render; already encoded segments are reused | `--workers` |
 
 Use `--out`, `--overwrite`, and `--no-lint` (skip automatic lint) with `stills`, `verify`, or `render`. Run `multiplane <command> --help` to list all options for that command.
 
@@ -213,3 +214,5 @@ With `--json`, stdout contains one JSON event per line. **The last line is alway
 Rendering may take a long time. Each run creates a job directory, `out/jobs/<jobId>/` (`jobId` appears in both the `start` event and the `result`). Read `status.json` for the latest progress snapshot and `events.jsonl` for the full event stream. To stop a job, run `multiplane cancel <jobId>` or create a file named `stop` in its job directory.
 
 If the user turned on hosting in the desktop app, the app runs the render and it keeps going after your session ends. Nothing changes in how you call the command; stderr says the job was handed over, and `status.json` may show `queued` while another hosted job runs. When a session resumes and you started a job earlier but never saw its `result`, run `multiplane wait <jobId> --json` to get its events and exit code instead of starting it again. Use `--no-hosted` only when the user asks for a render that should not go through the app.
+
+A `render` that ended without succeeding (`failed` or `cancelled`, or a job whose process disappeared, for example after a crash or reboot) can usually be continued instead of rendered again: run `multiplane resume <jobId> --json`. It reuses the segments already encoded (about 10 seconds each), renders the rest with the original options and output path, and produces the same frames as an uninterrupted render. It is a new job; its `result` carries `resumedFrom` and `resume.framesReused`. `multiplane status <jobId> --json` shows `data.resume.available` and how many frames are done. If it fails with `resume_unavailable`, read `details.reason`: `inputs_changed` or `environment_changed` means start a fresh `render` (do this deliberately, for example after you edited the shot); `running` means the job, or another resume, is still going, so `wait` for it; `missing_manifest` means the job predates segments. Only `--workers` can change on resume. A `resume_renderer_changed` warning (a different GPU or driver) needs no action.

package/src/capture-watchdog.mjs

@@ -0,0 +1,29 @@
+// Wall time controls recovery only; it never enters frame generation.
+export function createCaptureWatchdog(slots, onStall, { minimumMs = 120000, now = () => performance.now() } = {}) {
+  let longestFrameMs = 0, stopped = false;
+  const check = () => {
+    if (stopped) return;
+    const time = now(), threshold = Math.max(minimumMs, longestFrameMs * 10);
+    for (const [worker, slot] of slots.entries()) {
+      if (!slot.job || slot.recovering || time - slot.lastDelivery < threshold) continue;
+      slot.recovering = true;
+      onStall(slot, { worker, frame: slot.frame ?? slot.job.first, waitedSeconds: (time - slot.lastDelivery) / 1000 });
+    }
+  };
+  const timer = setInterval(check, Math.min(1000, Math.max(10, minimumMs / 4)));
+  timer.unref();
+  return {
+    check,
+    completed(slot) {
+      const time = now();
+      if (slot.frameStarted !== undefined) longestFrameMs = Math.max(longestFrameMs, time - slot.frameStarted);
+      slot.lastDelivery = time;
+    },
+    recovered(slot) {
+      slot.recovering = false;
+      slot.lastDelivery = now();
+      slot.frameStarted = slot.lastDelivery;
+    },
+    stop() { stopped = true; clearInterval(timer); },
+  };
+}

package/src/capture.mjs

@@ -175,7 +175,7 @@ async function openShotOnce(shot, scale = 1, options = {}) {
         return { png: measured };
     };
     return {
-      page, browser, server, ...metadata, alpha, beginFrame, timings,
+      page, browser, server, ...metadata, alpha, beginFrame, timings, _inspectSample: draw,
       get sampleContextUsed() { return sampleContextUsed; },
       get motionProbeUsed() { return motionProbeUsed; },
       get dofSamples() { return dofSamples; },
@@ -195,13 +195,13 @@ async function openShotOnce(shot, scale = 1, options = {}) {
 // Recovery belongs to a complete output frame, never to an individual blur sample.
 export async function openShot(shot, scale = 1, options = {}) {
   const budget = options._browserRecovery ?? recoveryBudget();
-  let current, closed = false;
-  const recover = async (error, t) => {
+  let current, closed = false, stalled;
+  const recover = async (error, t, stallAttempt) => {
     options.check?.();
     if (closed) throw error;
     const failure = crashedError(error, t);
-    if (Atomics.load(budget, 0) >= MAX_BROWSER_RESTARTS) throw failure;
-    const attempt = Atomics.add(budget, 0, 1) + 1;
+    if (!stallAttempt && Atomics.load(budget, 0) >= MAX_BROWSER_RESTARTS) throw failure;
+    const attempt = stallAttempt ?? Atomics.add(budget, 0, 1) + 1;
     if (attempt > MAX_BROWSER_RESTARTS) throw failure;
     await current?.close().catch(() => {});
     try { current = await openShotOnce(shot, scale, options); }
@@ -211,7 +211,8 @@ export async function openShot(shot, scale = 1, options = {}) {
       restarted.details = { ...failure.details, ...restarted.details };
       throw restarted;
     }
-    options.onWarning?.({ code: 'browser_restarted', message: 'Browser restarted; retrying the affected frame.', details: { ...failure.details, attempt } });
+    if (!stallAttempt) options.onWarning?.({ code: 'browser_restarted', message: 'Browser restarted; retrying the affected frame.', details: { ...failure.details, attempt } });
+    options.onRecovered?.();
   };
   try { current = await openShotOnce(shot, scale, options); }
   catch (error) { if (error.code !== 'browser_crashed') throw error; await recover(error); }
@@ -224,13 +225,28 @@ export async function openShot(shot, scale = 1, options = {}) {
     get dofSamples() { return current.dofSamples; },
     ...(current.observe ? { observe: (...args) => current.observe(...args) } : {}),
     beginFrame: (...args) => current.beginFrame(...args),
+    _inspectSample: (...args) => current._inspectSample(...args),
     frame: (...args) => current.frame(...args),
     ...(current.blurAt ? { blurAt: (...args) => current.blurAt(...args) } : {}),
+    // Closing the owned browser interrupts a blocked evaluate/CDP screenshot.
+    // Let the complete post frame unwind before retrying any of its samples.
+    async stall(details) {
+      if (closed || stalled) return;
+      stalled = new MultiplaneError('browser_crashed', 'Rendering worker stopped delivering frames.', { details });
+      await current.close();
+    },
     async retryFrame(t, operation) {
+      let stallAttempts = 0;
       for (;;) {
         try { return await operation(); }
         catch (error) {
           options.check?.();
+          if (!closed && stalled) {
+            const failure = stalled; stalled = undefined;
+            if (stallAttempts >= MAX_BROWSER_RESTARTS) throw failure;
+            await recover(failure, t, ++stallAttempts);
+            continue;
+          }
           if (closed || !current.isCrash(error)) throw error;
           await recover(error, t);
         }

package/src/errors.mjs

@@ -18,6 +18,7 @@ export const errorCodes = Object.freeze(Object.fromEntries([
   [3, 'skill_changed', 'The installed skill changed since inspection.'],
   [3, 'unsupported_node', 'Node 24 or newer is required.'],
   [2, 'invalid_option', 'Invalid option.'],
+  [2, 'resume_unavailable', 'This render cannot be resumed.'],
   [2, 'invalid_scale', 'Scale must produce positive even integer dimensions.'],
   [2, 'output_exists', 'Output already exists.'],
   [3, 'ffmpeg_not_found', 'FFmpeg was not found.'],

package/src/events.mjs

@@ -105,6 +105,7 @@ export function createEvents(command, shot, options = {}, job = false, deferStar
   if (!options._hostedCLI) monitor();
   return {
     directory, jobId, emit, warning, artifacts, options, monitor,
+    ...(options._resume ? { resumeData: { resumedFrom: options._resume.jobId, resume: { segmentsReused: 0, framesReused: 0 } } } : {}),
     // TODO(design): Document memoryBytes in status.json (latest sample, null on failure).
     memory(bytes) { state.memoryBytes = bytes; state.updatedAt = new Date().toISOString(); save(); },
     preview(frame) { state.previewFrame = frame; state.updatedAt = new Date().toISOString(); save(); },
@@ -113,7 +114,8 @@ export function createEvents(command, shot, options = {}, job = false, deferStar
       if (deferStart && !resolved) { save(); return; }
       startedEvent = true;
       const { onEvent, _preview, _resources, _probeVideo, _inspectFFmpeg, _hostedCLI, ...effective } = options;
-      emit('start', { version, shot, ...(jobId ? { jobId } : {}), options: effective, ...(this.workersSource ? { workersSource: this.workersSource } : {}) });
+      for (const key of Object.keys(effective)) if (key.startsWith('_')) delete effective[key];
+      emit('start', { ...this.resumeData, version, shot, ...(jobId ? { jobId } : {}), options: effective, ...(this.workersSource ? { workersSource: this.workersSource } : {}) });
       index('start', { command, shot, pid: process.pid });
       for (const [type, fields] of pendingEvents.splice(0)) emit(type, fields);
     },
@@ -129,7 +131,7 @@ export function createEvents(command, shot, options = {}, job = false, deferStar
       if (deferStart) this.start(true);
       const result = { command, ok: !error, code: error?.code ?? null, message: error?.message ?? null,
         ...(error?.hint ? { hint: error.hint } : {}), ...(error?.details ? { details: error.details } : {}),
-        artifacts, elapsedMs: Math.round(performance.now() - started), ...(jobId ? { jobId } : {}), data };
+        artifacts, elapsedMs: Math.round(performance.now() - started), ...(jobId ? { jobId } : {}), data: this.resumeData ? { ...this.resumeData, ...data } : data };
       index('end', { state: !error ? 'succeeded' : error.code === 'cancelled' ? 'cancelled' : 'failed' });
       emit('result', result);
       return result;
@@ -142,7 +144,7 @@ export async function runCommand(command, shot, options, action, job = true) {
   let events, resources, linted = false;
   try {
     const explicit = options;
-    const user = loadUserConfig(command, options);
+    const user = options._effectiveOptions ? { options: { ...options }, config: { applied: [] }, warnings: [] } : loadUserConfig(command, options);
     options = user.options;
     if (['render', 'stills', 'verify'].includes(command)) {
       options.quality = resolveQuality(options);
@@ -192,7 +194,7 @@ export async function runCommand(command, shot, options, action, job = true) {
       if (!options['no-lint']) { await checkLint(shot, events.options, events); linted = true; }
       events.start();
       const request = { schema: 'multiplane/1', jobId: events.jobId, jobDir: events.directory,
-        command, args: options._hostedCLI.args, cwd: process.cwd(), node: process.execPath,
+        command: options._resume ? 'resume' : command, args: options._hostedCLI.args, cwd: process.cwd(), node: process.execPath,
         bin: options._hostedCLI.bin, env: hostedEnvironment(process.env), at: new Date().toISOString() };
       const ownership = await handoff(request);
       if (ownership.hosted) {
@@ -210,7 +212,7 @@ export async function runCommand(command, shot, options, action, job = true) {
       resources = createResourceSampler({ enabled: options._resources !== false, onSample: events.memory });
       events.resources = resources;
     }
-    if (options.draft) {
+    if (options.draft && !options._effectiveOptions) {
       // Keep lint and cancellation active before the dimension-only draft probe.
       if (!linted && !options['no-lint']) {
         const { findings, data } = await scanShot(shot, events.options);

package/src/hosted.mjs

@@ -18,7 +18,7 @@ async function move(from, to) {
 }
 
 export async function hostedAvailable(command, options, env = process.env) {
-  if (!['render', 'stills', 'verify'].includes(command) || !options._hostedCLI || options.hosted !== true
+  if (!['render', 'stills', 'verify', 'resume'].includes(command) || !options._hostedCLI || options.hosted !== true
     || options['no-hosted'] || options['hosted-executor'] || env.MULTIPLANE_HOSTED === '0') return false;
   try {
     const app = await json(path.join(userHome(env), 'app.json'));
@@ -84,7 +84,7 @@ export async function handoff(request, { home = userHome(), timeout = 5000, star
 // Claim before loading config, creating status, linting or opening output files.
 export async function claimExecutor(jobDir, command) {
   try {
-    if (!path.isAbsolute(jobDir) || !['render', 'stills', 'verify'].includes(command)) return false;
+    if (!path.isAbsolute(jobDir) || !['render', 'stills', 'verify', 'resume'].includes(command)) return false;
     const jobId = path.basename(jobDir), base = hostedBase(jobId);
     const request = await json(base + '.claimed.json');
     if (request?.schema !== schema || request.jobId !== jobId || request.command !== command

package/src/index.mjs

@@ -1,4 +1,5 @@
 export { renderShot } from './render.mjs';
+export { resumeRender } from './resume.mjs';
 export { stillsShot } from './stills.mjs';
 export { verifyShot } from './verify.mjs';
 export { openShot } from './capture.mjs';

package/src/input-records.mjs

@@ -0,0 +1,33 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { readFile, stat } from 'node:fs/promises';
+
+// Servers inherit the render's context; unrelated inspect/serve calls do not.
+export const inputRecords = new AsyncLocalStorage();
+const largeFiles = new WeakMap();
+export const digest = bytes => createHash('sha256').update(bytes).digest('hex');
+export async function fileDigest(file) {
+  const hash = createHash('sha256');
+  for await (const bytes of createReadStream(file)) hash.update(bytes);
+  return hash.digest('hex');
+}
+export async function recordInput(file) {
+  const record = inputRecords.getStore();
+  if (!record) return;
+  const info = await stat(file);
+  // Large media stays streamed. Cache only its digest, never its body.
+  if (info.size > 1024 * 1024) {
+    let cache = largeFiles.get(record);
+    if (!cache) largeFiles.set(record, cache = new Map());
+    const previous = cache.get(file);
+    const sha256 = previous?.size === info.size && previous.mtimeMs === info.mtimeMs
+      ? previous.sha256 : await fileDigest(file);
+    cache.set(file, { size: info.size, mtimeMs: info.mtimeMs, sha256 });
+    record(file, { bytes: info.size, sha256 });
+    return;
+  }
+  const bytes = await readFile(file);
+  record(file, { bytes: bytes.length, sha256: digest(bytes) });
+  return bytes;
+}

package/src/jobs.mjs

@@ -6,8 +6,9 @@ import { MultiplaneError, invalidOption } from './errors.mjs';
 import { number } from './capture.mjs';
 import { followJob } from './hosted.mjs';
 import { loadUserConfig } from './user-home.mjs';
+import { resumeStatus } from './segments.mjs';
 
-const resolveJob = (target, options) => path.isAbsolute(target) || /[\\/]/.test(target) ? path.resolve(target) : path.join(jobDirectory(options), target);
+export const resolveJob = (target, options) => path.isAbsolute(target) || /[\\/]/.test(target) ? path.resolve(target) : path.join(jobDirectory(options), target);
 export async function readStatus(target, options = {}) {
   let status;
   try { status = JSON.parse(await readFile(path.join(resolveJob(target, options), 'status.json'), 'utf8')); }
@@ -25,6 +26,7 @@ export async function readStatus(target, options = {}) {
       }
     }
   }
+  if (status.command === 'render') status.resume = resumeStatus(status, resolveJob(target, options));
   return status;
 }
 export const statusJob = (target, options = {}) => runCommand('status', null, options, events => readStatus(target, events.options), false);

package/src/post.mjs

@@ -329,11 +329,25 @@ export function createPostCapture(capture, options = {}, fps = capture.fps) {
       let png, result, usedSamples = motionBlur;
       if (candidate && !verifyReuse) { ({ png, image: result, usedSamples } = previousRaw); }
       else if (upward) {
+        // TODO(design): Half-size probes need a compatible decision policy;
+        // halving the raster and displacement threshold changes refinement.
         // Calibrated in capture raster pixels: about 2px for fast/standard, 1px for high.
         const threshold = resolveQuality(options) === 'high' ? 1 : 2;
-        await sampleMany([...endpoints, t], true);
+        // Stop as soon as motion is established. Retain exact full-size still
+        // checks, and reuse every matching time without changing the final grid.
+        await sampleMany([t, endpoints[0]], true);
         const centerProbe = cache.get(t);
-        const still = endpoints.every(time => cache.get(time).image.data.equals(centerProbe.image.data));
+        let still = cache.get(endpoints[0]).image.data.equals(centerProbe.image.data);
+        if (still) {
+          await sampleMany([endpoints[1]], true);
+          still = cache.get(endpoints[1]).image.data.equals(centerProbe.image.data);
+        } else if (capture._inspectSample) {
+          // Preserve conditional sampleContext reads at the skipped endpoint.
+          const start = performance.now();
+          await capture._inspectSample(endpoints[1], context(false, endpoints[1]));
+          stats.captureMs += performance.now() - start;
+          contextUsed ||= capture.sampleContextUsed === true;
+        }
         let legacy = contextUsed;
         let grid = legacy ? times : grids.get(motionBlur);
         if (still) {
@@ -400,6 +414,8 @@ export function createPostCapture(capture, options = {}, fps = capture.fps) {
       if (!(candidate && !verifyReuse)) {
         // Only lens-dependent probe captures need replacing. DOM captures and
         // final hook captures remain reusable at the same time and context.
+        // TODO(design): Zero aperture still has interleaved projection jitter;
+        // reusing its probes requires an approved change to that pattern.
         if (motionProbeUsed && !finalCapture) {
           finalCapture = true;
           dofMotionSamples = new Set(selectedTimes).size;

package/src/render-pool.mjs

@@ -4,6 +4,7 @@ import { MultiplaneError } from './errors.mjs';
 import { availableParallelism, freemem, totalmem } from 'node:os';
 import { Worker } from 'node:worker_threads';
 import { blurSampleReport } from './post.mjs';
+import { createCaptureWatchdog } from './capture-watchdog.mjs';
 
 export function defaultWorkers(scale = 1, hardware = {}) {
   const cores = hardware.cores ?? availableParallelism();
@@ -12,24 +13,50 @@ export function defaultWorkers(scale = 1, hardware = {}) {
   return Math.max(1, Math.min(12, Math.floor(cores / 2), Math.floor((free - 2 * 1024 ** 3) / workerBytes)));
 }
 
-export function createRenderPool(shot, options, fps, workers, size, onWarning, onCaptured) {
+export function createRenderPool(shot, options, fps, workers, size, onWarning, onCaptured, onInput) {
   options = { ...options, _browserRecovery: options._browserRecovery ?? recoveryBudget() };
   reuseState(options);
   const slots = [], stats = { frames: 0, samples: 0, staticFrames: 0 };
   const histogram = {}, dofHistogram = {};
   const captured = new Set();
-  let failure;
+  let failure, stopping = false, closing;
+  function close() {
+    if (closing) return closing;
+    stopping = true; watchdog.stop();
+    for (const slot of slots) if (!slot.closed) slot.worker.postMessage({ type: 'close' });
+    // A blocked page cannot finish its frame. Close only browsers owned by
+    // these workers after the grace period, letting their normal cleanup run.
+    const timer = setTimeout(() => {
+      for (const slot of slots) if (!slot.closed) slot.worker.postMessage({ type: 'cancel' });
+    }, options._stopGraceMs ?? 5000); // Internal override for short fault tests.
+    closing = Promise.all(slots.map(s => s.exited)).finally(() => clearTimeout(timer));
+    return closing;
+  }
+  // Internal deadline override for short fault-injection tests; no CLI option.
+  const watchdog = createCaptureWatchdog(slots, (slot, details) => {
+    if (failure || stopping) return;
+    try {
+      onWarning?.({ code: 'worker_stalled', severity: 'warning', message: 'Rendering worker stalled.', details });
+      slot.worker.postMessage({ type: 'stalled', details });
+    } catch (error) { fail(error); }
+  }, { minimumMs: options._stallTimeoutMs });
+  const fail = error => {
+    failure ??= error;
+    watchdog.stop();
+    for (const s of slots) { s.pending?.reject(failure); s.pending = null; }
+    void close();
+  };
   for (let i = 0; i < workers; i++) {
     const worker = new Worker(new URL('./render-worker.mjs', import.meta.url), { workerData: { shot, options, fps, size } });
     const slot = { worker, pending: null, closed: false };
-    const fail = error => {
-      failure ??= error;
-      for (const s of slots) { s.pending?.reject(error); s.pending = null; }
-    };
     slot.ready = new Promise((resolve, reject) => { slot.pending = { resolve, reject }; });
     slot.ready.catch(() => {});
     worker.on('message', message => {
+      if (message.type === 'frame-start') { slot.frame = message.frame; slot.frameStarted = performance.now(); return; }
+      if (message.type === 'recovered') { watchdog.recovered(slot); return; }
+      if (message.type === 'input') { try { onInput?.(message.file, message.record); } catch (error) { fail(error); } return; }
       if (message.type === 'captured') {
+        watchdog.completed(slot);
         if (!captured.has(message.frame)) {
           captured.add(message.frame);
           try { onCaptured?.(captured.size); } catch (error) { fail(error); }
@@ -39,6 +66,7 @@ export function createRenderPool(shot, options, fps, workers, size, onWarning, o
       if (message.type === 'warning') { onWarning?.(message.warning); return; }
       if (message.type === 'failure') { fail(new MultiplaneError(message.code ?? 'worker_crashed', message.error, { details: message.details, hint: message.hint })); return; }
       const pending = slot.pending; slot.pending = null;
+      slot.job = null;
       pending?.resolve(message);
     });
     worker.on('error', error => fail(new MultiplaneError('worker_crashed', undefined, { cause: error })));
@@ -66,6 +94,8 @@ export function createRenderPool(shot, options, fps, workers, size, onWarning, o
         next = Math.min(end, next + chunk, reuseEnabled(options) ? (Math.floor(begin / REUSE_INTERVAL) + 1) * REUSE_INTERVAL + 1 : end);
         const promise = new Promise((resolve, reject) => { slot.pending = { resolve, reject }; });
         promise.catch(() => {});
+        slot.job = { first: begin, end: next }; slot.frame = begin;
+        slot.lastDelivery = performance.now(); slot.frameStarted = undefined;
         slot.worker.postMessage({ type: 'render', first: begin, end: next });
         queue.push({ slot, promise });
       };
@@ -86,13 +116,10 @@ export function createRenderPool(shot, options, fps, workers, size, onWarning, o
         if (options.transport !== 'raw') schedule(slot);
       }
     },
-    async close() {
-      for (const slot of slots) if (!slot.closed) slot.worker.postMessage({ type: 'close' });
-      await Promise.all(slots.map(s => s.exited));
-    },
+    close,
     async cancel() {
-      for (const slot of slots) if (!slot.closed) slot.worker.postMessage({ type: 'cancel' });
-      await Promise.all(slots.map(s => s.exited));
+      fail(new MultiplaneError('cancelled'));
+      await close();
     },
   };
   const frames = api.frames.bind(api);

package/src/render-worker.mjs

@@ -3,8 +3,11 @@ import { MultiplaneError, asError } from './errors.mjs';
 import { parentPort, workerData, isMarkedAsUntransferable } from 'node:worker_threads';
 import { openShot } from './capture.mjs';
 import { createPostCapture, resolveScale } from './post.mjs';
+import { inputRecords } from './input-records.mjs';
 
-let capture, closing = false, running = false;
+if (workerData.options._recordInputs) inputRecords.enterWith((file, record) => parentPort.postMessage({ type: 'input', file, record }));
+
+let capture, closing = false, running = false, activeFrame;
 const sendFailure = error => {
   const failure = asError(error);
   parentPort.postMessage({ type: 'failure', error: failure.message, code: failure.code, details: failure.details, hint: failure.hint });
@@ -16,12 +19,17 @@ async function close() {
   parentPort.close();
 }
 try {
-  capture = await openShot(workerData.shot, resolveScale(workerData.options).renderScale, { ...workerData.options, onWarning: warning => parentPort.postMessage({ type: 'warning', warning }), check: () => { if (closing) throw new MultiplaneError('cancelled'); } });
+  capture = await openShot(workerData.shot, resolveScale(workerData.options).renderScale, { ...workerData.options, onRecovered: () => parentPort.postMessage({ type: 'recovered' }), onWarning: warning => parentPort.postMessage({ type: 'warning', warning }), check: () => { if (closing) throw new MultiplaneError('cancelled'); } });
   if (workerData.size && (capture.width !== workerData.size.width || capture.height !== workerData.size.height)) throw new MultiplaneError('internal_error', 'Worker stage dimensions differ from the main process.');
   const processed = createPostCapture(capture, { ...workerData.options, onWarning: warning => parentPort.postMessage({ type: 'warning', warning }) }, workerData.fps);
   parentPort.on('message', async message => {
     if (message.type === 'cancel') { closing = true; await capture?.close(); if (!running) parentPort.close(); return; }
     if (message.type === 'close') { await close(); return; }
+    if (message.type === 'stalled') {
+      if (!closing && activeFrame === message.details.frame) await capture.stall(message.details).catch(sendFailure);
+      else parentPort.postMessage({ type: 'recovered' });
+      return;
+    }
     if (closing) return;
     running = true;
     try {
@@ -29,7 +37,10 @@ try {
       const source = async function* (first, end) {
         for (let index = first; index < end && !closing; index++) {
           const frame = message.first + index;
+          activeFrame = frame;
+          parentPort.postMessage({ type: 'frame-start', frame });
           const png = await processed.frame(frame / workerData.fps, frame, index === end - 1);
+          activeFrame = undefined;
           parentPort.postMessage({ type: 'captured', frame });
           yield { png, hash: processed.lastHash, blurSamples: processed.lastBlurSamples, dofSamples: processed.lastDofSamples };
         }

package/src/render.mjs

@@ -1,9 +1,8 @@
 import { readBenchmark, benchmarkMachine, selectWorkers, classifyShot } from './workers.mjs';
 import { recoveryBudget } from './browser-recovery.mjs';
 import path from 'node:path';
-import { mkdir, rm, writeFile } from 'node:fs/promises';
+import { mkdir, rm, writeFile, rename } from 'node:fs/promises';
 import { createHash } from 'node:crypto';
-import { spawn } from 'node:child_process';
 import { stopChild } from './process.mjs';
 import { inspectFFmpeg } from './ffmpeg.mjs';
 import { openShot, number } from './capture.mjs';
@@ -11,19 +10,28 @@ import { createPostCapture, resolveScale } from './post.mjs';
 import { createRenderPool } from './render-pool.mjs';
 import { resolveFormat, videoEncoding } from './format.mjs';
 import { checkAlphaVideo } from './output-alpha.mjs';
-import { writeFrame } from './video-pipe.mjs';
-import { runCommand } from './events.mjs';
+import { inputRecords, recordInput } from './input-records.mjs';
+import { atomicJSON, lockSegments, manifestStore, checkInputs, checkEnvironment, reusableSegments, readManifest, unavailable } from './segments.mjs';
+import { segmentEncoder, assembleSegments } from './segment-encoder.mjs';
+import { version, runCommand } from './events.mjs';
 import { loaded, observeBrowser, environment } from './environment.mjs';
-import { MultiplaneError, invalidOption } from './errors.mjs';
+import { invalidOption } from './errors.mjs';
 import { requireNewOutput, publishVideo } from './artifacts.mjs';
 import { createPreview } from './preview.mjs';
 import { checkVideo } from './output-check.mjs';
 import { frameRate } from './frame-rate.mjs';
 
+const persistedOptions = options => Object.fromEntries(Object.entries(options).filter(([key, value]) =>
+  !key.startsWith('_') && typeof value !== 'function' && !['job-dir-exact', 'hosted-executor'].includes(key)));
+
 export async function renderShot(shot, options = {}) {
-  return runCommand('render', shot, options, async events => {
+  return runCommand('render', shot, options, async events => inputRecords.run(null, async () => {
     options = { ...events.options };
     delete options.onEvent;
+    const resume = options._resume; delete options._resume;
+    const hook = options._segmentHook; delete options._segmentHook;
+    const segmentFrames = options._segmentFrames; delete options._segmentFrames;
+    delete options._effectiveOptions;
     const probe = options._probeVideo;
     delete options._probeVideo;
     const inspect = options._inspectFFmpeg ?? inspectFFmpeg;
@@ -32,25 +40,56 @@ export async function renderShot(shot, options = {}) {
     const name = path.basename(shot, path.extname(shot));
     let result;
 
-    let capture, pool, encoder, temporary, cleaning, encoderClosed = false;
+    let capture, pool, temporary, cleaning, store, directory, release, movedSource;
+    const encoders = new Set(), pending = [];
+    const inputs = {};
+    const onInput = (file, record) => { if (store) store.input(file, record); else inputs[file] = record; };
+    inputRecords.enterWith(onInput);
     function cleanup() { return cleaning ??= cleanResources(); }
     async function cleanResources() {
       try {
-        if (encoder && !encoderClosed) await stopChild(encoder);
+        await Promise.all([...encoders].map(encoder => stopChild(encoder)));
+        await Promise.allSettled(pending);
       } finally {
         try { await capture?.close(); }
-        finally { try { await pool?.close(); } finally { if (temporary) await rm(temporary, { force: true }); } }
+        finally { try { await pool?.close(); } finally {
+          try {
+            if (temporary && movedSource) await rename(temporary, movedSource);
+            else if (temporary) await rm(temporary, { force: true });
+          } finally { release?.(); }
+        } }
       }
     }
 
     try {
+      if (resume) {
+        directory = resume.directory;
+        release ??= lockSegments(directory);
+        resume.manifest = readManifest(directory);
+        if (!resume.manifest) throw unavailable('missing_manifest');
+        atomicJSON(path.join(events.directory, 'resume.json'), { directory });
+        await checkInputs(resume.manifest);
+      }
       const out = path.resolve(options.out ?? path.join(events.directory, `${name}.${options.format}`));
+      if (!resume) {
+        directory = path.join(events.directory, 'segments');
+        release = lockSegments(directory);
+        // A launch failure can be retried even before metadata or a first frame
+        // exists. Replace this provisional record with effective values below.
+        store = manifestStore(directory, { schema: 'multiplane-segments/1', jobId: events.jobId,
+          shot: path.resolve(options.root, shot), options: persistedOptions({ ...options, out,
+            audio: options.audio ? path.resolve(options.audio) : undefined }),
+          environment: null, first: 0, end: 0, total: 0, segmentFrames: segmentFrames ?? null, inputs: {}, segments: [] });
+        store.save();
+        await recordInput(path.resolve(options.root, shot));
+        if (options.audio) await recordInput(path.resolve(options.audio));
+      }
       if (!options.overwrite) await requireNewOutput(out);
       events.check();
       events.progress('launch');
       const { scale, renderScale } = resolveScale(options);
       const encoding = videoEncoding(options);
-      let videoArgs = encoding.args;
+
       const ffmpegInfo = await inspect(options.ffmpeg, process.env, { x264: 'libx264', 'nvenc-h264': 'h264_nvenc', 'nvenc-hevc': 'hevc_nvenc' }[encoding.encoder] ?? encoding.encoder);
       const ffmpeg = ffmpegInfo.path;
       options.transport = 'raw';
@@ -74,8 +113,7 @@ export async function renderShot(shot, options = {}) {
       options.alpha = events.options.alpha = capture.alpha;
       resolveFormat(options);
       Object.assign(encoding, videoEncoding(options));
-      videoArgs = encoding.args;
-      await loaded(events, capture, ffmpegInfo);
+
       const fps = number(options.fps ?? capture.fps, '--fps', { positive: true });
       const rate = frameRate(fps);
       const processed = createPostCapture(capture, options, fps);
@@ -87,57 +125,110 @@ export async function renderShot(shot, options = {}) {
       const total = end - first;
       if (!total) throw invalidOption('--from', 'Range contains no frames.');
       const { width, height } = capture;
-      events.progress('capture', 0, total);
+      directory = resume?.directory ?? path.join(events.directory, 'segments');
+      release ??= lockSegments(directory);
+      const info = await environment(capture.browser);
+      const currentEnvironment = { multiplane: version, chromium: info.chromium, raster: options.raster,
+        renderer: info.gpu.renderer, ffmpeg: ffmpegInfo.version, encoder: encoding.encoder };
+      const effective = { ...options, fps, from, to, out, ffmpeg, audio: options.audio ? path.resolve(options.audio) : undefined,
+        'motion-blur': processed.post.motionBlur, 'max-motion-blur': processed.post.maxMotionBlur,
+        shutter: processed.post.shutter, grain: processed.post.grain };
+      const savedOptions = persistedOptions(effective);
+      let manifest;
+      if (resume) {
+        manifest = resume.manifest;
+        checkEnvironment(manifest.environment, currentEnvironment);
+        if (manifest.environment && manifest.environment.renderer !== currentEnvironment.renderer) {
+          events.warning({ code: 'resume_renderer_changed', message: 'GPU renderer changed since the original render.',
+            details: { before: manifest.environment.renderer, after: currentEnvironment.renderer } });
+        }
+        await checkInputs(manifest);
+        manifest.segments = await reusableSegments(directory, manifest);
+        if (!manifest.environment) Object.assign(manifest, { environment: currentEnvironment, options: savedOptions,
+          first, end, total, segmentFrames: manifest.segmentFrames ?? Math.max(1, Math.round(fps * 10)) });
+      } else {
+        manifest = { schema: 'multiplane-segments/1', jobId: events.jobId, shot: path.resolve(options.root, shot),
+          options: savedOptions, environment: currentEnvironment, first, end, total,
+          segmentFrames: segmentFrames ?? Math.max(1, Math.round(fps * 10)), inputs: store.manifest.inputs, segments: [] };
+      }
+      if (!Number.isSafeInteger(manifest.segmentFrames) || manifest.segmentFrames < 1) throw invalidOption('_segmentFrames', 'Segment size must be a positive integer.');
+      store = manifestStore(directory, manifest);
+      for (const [file, record] of Object.entries(inputs)) store.input(file, record);
+      if (options.audio) await recordInput(path.resolve(options.audio));
+      store.save();
+      const framesReused = manifest.segments.reduce((sum, segment) => sum + segment.end - segment.first, 0);
+      const resumeData = resume ? { resumedFrom: resume.jobId, resume: { segmentsReused: manifest.segments.length, framesReused } } : {};
+      events.resumeData = resumeData;
+      if (resume) atomicJSON(path.join(events.directory, 'resume.json'), { directory });
+      await loaded(events, capture, ffmpegInfo);
+      events.progress('capture', framesReused, total);
       await capture.close(); capture = undefined;
       events.check();
-      const actualWorkers = Math.min(workers, Math.ceil(total / 4));
+      const actualWorkers = Math.min(workers, Math.max(1, Math.ceil((total - framesReused) / 4)));
       events.resources.setWorkers(actualWorkers);
       const started = performance.now();
       const frameHashes = process.env.RENDER_FRAME_HASHES ? [] : null;
+      options._recordInputs = true;
       pool = createRenderPool(shot, options, fps, actualWorkers, { width, height }, events.warning,
-        done => events.progress('capture', done, total));
+        done => events.progress('capture', done + framesReused, total), onInput);
       events.onCancel(() => pool?.cancel());
       await mkdir(path.dirname(out), { recursive: true });
-      events.check();
-      temporary = `${out}.${events.jobId}.partial.${options.format}`;
-      const audioArgs = options.audio
-        ? ['-i', path.resolve(options.audio), '-map', '0:v:0', '-map', '1:a:0', '-af', `atrim=start=${audioOffset + rate.seconds(first)},asetpts=PTS-STARTPTS,apad,atrim=duration=${rate.seconds(total)}`, ...encoding.audio]
-        : ['-an'];
-      // Supported since FFmpeg 5.1; older FFmpeg uses the global -vsync 0.
-      // Do not add output -r: passthrough must neither drop nor duplicate frames.
-      encoder = spawn(ffmpeg, ['-hide_banner', '-loglevel', 'error', '-y', '-f', 'rawvideo', '-pixel_format', 'rgba', '-video_size', `${width * scale}x${height * scale}`, '-framerate', rate.argument, '-i', 'pipe:0', ...audioArgs, ...videoArgs, '-fps_mode', 'passthrough', '-pix_fmt', encoding.pixelFormat, ...encoding.mux, temporary], { windowsHide: true, stdio: ['pipe', 'ignore', 'pipe'] });
-      encoder.once('close', () => { encoderClosed = true; });
-      events.onCancel(() => stopChild(encoder));
-      let stderr = '', failure;
-      encoder.stderr.on('data', data => { stderr = (stderr + data).slice(-8000); });
-      encoder.stdin.on('error', error => { failure = error; });
-      const finished = new Promise((resolve, reject) => {
-        encoder.once('error', cause => reject(new MultiplaneError('encode_failed', undefined, { cause, details: { reason: cause.message } })));
-        encoder.once('close', code => code === 0 ? resolve() : reject(new MultiplaneError('encode_failed', undefined, { details: { exitCode: code, stderr } })));
-      });
-      finished.catch(error => { failure = error; });
+      temporary = out + '.' + events.jobId + '.partial.' + options.format;
       const alphaReferences = new Map();
-      let encoderWriteMs = 0, framesSent = 0;
-      // Internal switch for the pixel-equivalence and overhead tests, not a CLI option.
+      let encoderWriteMs = 0, framesSent = total, sealingFailure;
       const preview = createPreview(events, width * scale, height * scale, { enabled: options._preview !== false });
-      for await (const { frame, png } of pool.frames(first, end, async ({ frame, png }) => {
-        events.check();
-        await preview(png, frame);
-      })) {
-        events.check();
-        if (failure) throw new MultiplaneError('encode_failed', undefined, { cause: failure });
-        if (options.alpha && (framesSent === 0 || framesSent === Math.floor(total / 2))) alphaReferences.set(framesSent, Buffer.from(png.filter((_, i) => i % 4 === 3)));
-        frameHashes?.push({ frame, sha256: createHash('sha256').update(png).digest('hex') });
-        const writeStarted = performance.now();
-        await writeFrame(encoder.stdin, png).catch(cause => { throw new MultiplaneError('encode_failed', undefined, { cause, details: { reason: cause.message } }); });
-        encoderWriteMs += performance.now() - writeStarted;
-        framesSent++;
+      const remember = segment => {
+        frameHashes?.push(...(segment.frameHashes ?? []));
+        for (const [frame, bytes] of Object.entries(segment.alphaReferences ?? {})) alphaReferences.set(Number(frame), Buffer.from(bytes, 'base64'));
+      };
+      // Keep workers busy while the preceding encoder drains and seals.
+      const ranges = [];
+      for (let start = first, index = 0; start < end; start += manifest.segmentFrames, index++) {
+        const stop = Math.min(end, start + manifest.segmentFrames);
+        const reused = manifest.segments.find(item => item.first === start && item.end === stop);
+        if (reused) { remember(reused); continue; }
+        ranges.push({ first: start, end: stop, index });
+      }
+      for (let cursor = 0; cursor < ranges.length;) {
+        let last = cursor;
+        while (last + 1 < ranges.length && ranges[last].end === ranges[last + 1].first) last++;
+        let active, hashes, references, rangeIndex = cursor;
+        for await (const { frame, png } of pool.frames(ranges[cursor].first, ranges[last].end)) {
+          events.check();
+          if (sealingFailure) throw sealingFailure;
+          if (!active) {
+            active = segmentEncoder({ ffmpeg, directory, ...ranges[rangeIndex], width: width * scale, height: height * scale,
+              rate, encoding, format: options.format, events, store, hook });
+            encoders.add(active.child);
+            active.finished.finally(() => encoders.delete(active.child)).catch(() => {});
+            hashes = []; references = {};
+          }
+          await preview(png, frame);
+          const relative = frame - first;
+          if (options.alpha && (relative === 0 || relative === Math.floor(total / 2))) references[relative] = Buffer.from(png.filter((_, i) => i % 4 === 3)).toString('base64');
+          if (frameHashes) hashes.push({ frame, sha256: createHash('sha256').update(png).digest('hex') });
+          const writeStarted = performance.now();
+          await active.write(png);
+          encoderWriteMs += performance.now() - writeStarted;
+          if (frame + 1 === ranges[rangeIndex].end) {
+            const sealed = active.seal({ ...(frameHashes ? { frameHashes: hashes } : {}), ...(options.alpha ? { alphaReferences: references } : {}) }).then(remember);
+            sealed.catch(error => { sealingFailure ??= error; });
+            pending.push(sealed);
+            // Hooks model interruption at an exact durable boundary in tests.
+            if (hook) await sealed;
+            active = undefined; rangeIndex++;
+          }
+        }
+        cursor = last + 1;
       }
       const drainStarted = performance.now();
       events.progress('encode', total, total);
-      encoder.stdin.end();
-      await finished;
+      await Promise.all(pending);
+      // Finish all resource requests before the final input audit/publication.
+      await pool.close();
       events.check();
+      await checkInputs(manifest);
+      movedSource = await assembleSegments({ ffmpeg, directory, manifest, temporary, encoding, rate, audioOffset, events });
       const encoderDrainMs = performance.now() - drainStarted;
       const probeStarted = performance.now();
       const outputCheck = await checkVideo(ffmpeg, temporary, { frames: framesSent, durationSeconds: rate.seconds(framesSent), width: width * scale, height: height * scale, fps: rate.fps, ...(options.alpha ? { alpha: true, format: options.format } : {}) }, events, probe);
@@ -145,13 +236,18 @@ export async function renderShot(shot, options = {}) {
       const outputCheckMs = performance.now() - probeStarted;
       await publishVideo(temporary, out, options.overwrite);
       temporary = undefined;
+      // Invalidate the checkpoint while still holding the lock, so another
+      // resume cannot reuse a manifest whose output has already been published.
+      await rm(path.join(directory, 'manifest.json'), { force: true });
+      await rm(directory, { recursive: true, force: true });
+      release(); release = undefined;
       const elapsed = (performance.now() - started) / 1000;
-      if (frameHashes) await writeFile(process.env.RENDER_FRAME_HASHES, JSON.stringify(frameHashes, null, 2));
+      if (frameHashes) await writeFile(process.env.RENDER_FRAME_HASHES, JSON.stringify(frameHashes.sort((a, b) => a.frame - b.frame), null, 2));
       if (process.env.RENDER_PROFILE) await writeFile(process.env.RENDER_PROFILE, JSON.stringify({elapsed,frames:total,workers:actualWorkers,options,stats:pool.stats,encoderWriteMs,encoderDrainMs,outputCheckMs},null,2));
       events.artifact(out, 'video');
-      result = { staticReuse: pool.staticReuse, blurSamples: pool.blurSamples, dofSamples: pool.dofSamples, output: out, frames: framesSent, fps, from, to, width: width * scale, height: height * scale, encoder: encoding.encoder, format: options.format, alpha: options.alpha, post: { ...processed.post, adaptiveBlur: Number(options['adaptive-blur'] ?? 0.5) }, renderScale, scale, outputCheck };
+      result = { ...resumeData, staticReuse: pool.staticReuse, blurSamples: pool.blurSamples, dofSamples: pool.dofSamples, output: out, frames: framesSent, fps, from, to, width: width * scale, height: height * scale, encoder: encoding.encoder, format: options.format, alpha: options.alpha, post: { ...processed.post, adaptiveBlur: Number(options['adaptive-blur'] ?? 0.5) }, renderScale, scale, outputCheck };
     } finally { await cleanup(); }
 
     return options.draft ? { ...result, draft: true } : result;
-  });
+  }));
 }

package/src/resume.mjs

@@ -0,0 +1,23 @@
+import { renderShot } from './render.mjs';
+import { readStatus, resolveJob } from './jobs.mjs';
+import { readManifest, segmentDirectory, unavailable, checkInputs } from './segments.mjs';
+import { invalidOption } from './errors.mjs';
+import { loadUserConfig } from './user-home.mjs';
+
+export async function resumeRender(target, options = {}) {
+  const allowed = ['workers', 'json', 'job-dir', 'no-hosted', 'onEvent', '_hostedCLI', '_segmentHook', '_inspectFFmpeg', '_probeVideo', 'hosted-executor', 'job-dir-exact'];
+  for (const key of Object.keys(options)) if (!allowed.includes(key)) throw invalidOption('--' + key, 'This option cannot be changed when resuming.');
+  const configured = loadUserConfig('status', options);
+  const jobDir = resolveJob(target, configured.options);
+  const status = await readStatus(jobDir);
+  if (status.command !== 'render') throw unavailable('not_render');
+  if (status.state === 'succeeded') throw unavailable('succeeded');
+  if (!['failed', 'cancelled'].includes(status.state)) throw unavailable('running');
+  const directory = segmentDirectory(jobDir), manifest = readManifest(directory);
+  if (!manifest) throw unavailable('missing_manifest');
+  await checkInputs(manifest);
+  return renderShot(manifest.shot, { ...manifest.options, ...options,
+    _resume: { directory, jobId: status.jobId }, _effectiveOptions: true,
+    // Only hosting policy and job lookup use current configuration.
+    hosted: loadUserConfig('render', {}).options.hosted, 'no-hosted': options['no-hosted'] ?? false });
+}

package/src/segment-encoder.mjs

@@ -0,0 +1,91 @@
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import { rename, stat, writeFile, open } from 'node:fs/promises';
+import path from 'node:path';
+import { stopChild } from './process.mjs';
+import { writeFrame } from './video-pipe.mjs';
+import { MultiplaneError } from './errors.mjs';
+import { fileDigest } from './input-records.mjs';
+
+function childProcess(ffmpeg, args, events, input = false, onLine) {
+  events.check();
+  const child = spawn(ffmpeg, ['-hide_banner', '-loglevel', 'error', '-y', ...args],
+    { windowsHide: true, stdio: [input ? 'pipe' : 'ignore', 'pipe', 'pipe'] });
+  let stderr = '', stdout = '', failure;
+  const unsubscribe = events.onCancel(() => stopChild(child));
+  child.stderr.on('data', bytes => { stderr = (stderr + bytes).slice(-8000); });
+  if (onLine) createInterface({ input: child.stdout, crlfDelay: Infinity }).on('line', onLine);
+  else child.stdout.on('data', bytes => { stdout = (stdout + bytes).slice(-8000); });
+  child.stdin?.on('error', error => { failure = error; });
+  const finished = new Promise((resolve, reject) => {
+    child.once('error', cause => reject(new MultiplaneError('encode_failed', undefined, { cause })));
+    child.once('close', code => {
+      unsubscribe();
+      if (code === 0) resolve(stdout);
+      else reject(new MultiplaneError('encode_failed', undefined, { details: { exitCode: code, stderr } }));
+    });
+  });
+  finished.catch(error => { failure = error; });
+  return { child, finished, async write(bytes) {
+    try {
+      if (failure) throw failure;
+      await writeFrame(child.stdin, bytes);
+    } catch (cause) {
+      throw cause instanceof MultiplaneError ? cause : new MultiplaneError('encode_failed', undefined,
+        { cause, details: { reason: cause.message } });
+    }
+  } };
+}
+
+export function segmentEncoder({ ffmpeg, directory, index, first, end, width, height, rate, encoding, format, events, store, hook }) {
+  const file = `segment-${String(index).padStart(6, '0')}.${format}`;
+  const temporary = path.join(directory, file + '.partial.' + format);
+  const encoder = childProcess(ffmpeg, ['-f', 'rawvideo', '-pixel_format', 'rgba', '-video_size', `${width}x${height}`,
+    '-framerate', rate.argument, '-i', 'pipe:0', '-an', ...encoding.args, '-fps_mode', 'passthrough',
+    '-pix_fmt', encoding.pixelFormat, ...encoding.mux, temporary], events, true);
+  return { ...encoder, async seal(extra = {}) {
+    encoder.child.stdin.end();
+    await encoder.finished;
+    events.check();
+    // Count copied video packets without decoding or relying on version-specific progress fields.
+    let frames = 0;
+    const probe = childProcess(ffmpeg, ['-i', temporary, '-map', '0:v:0', '-an', '-c', 'copy', '-f', 'framecrc', '-'], events, false, line => {
+      if (line.trim() && !line.trimStart().startsWith('#')) frames++;
+    });
+    await probe.finished;
+    if (!frames) throw new MultiplaneError('output_invalid', 'Segment frame count could not be read.', { details: { expected: end - first, frames: null } });
+    if (frames !== end - first) throw new MultiplaneError('output_invalid', 'Segment frame count differs.', { details: { expected: end - first, frames } });
+    const handle = await open(temporary, 'r+');
+    try { await handle.sync(); } finally { await handle.close(); }
+    await hook?.('beforeSeal', index);
+    await rename(temporary, path.join(directory, file));
+    const segment = { file, first, end, bytes: (await stat(path.join(directory, file))).size,
+      sha256: await fileDigest(path.join(directory, file)), ...extra };
+    store.manifest.segments = store.manifest.segments.filter(item => item.first !== first).concat(segment).sort((a, b) => a.first - b.first);
+    store.save();
+    await hook?.('sealed', index);
+    return segment;
+  } };
+}
+
+export async function assembleSegments({ ffmpeg, directory, manifest, temporary, encoding, rate, audioOffset, events }) {
+  const segments = [...manifest.segments].sort((a, b) => a.first - b.first);
+  const { options, first, total } = manifest;
+  if (segments.length === 1 && !options.audio) {
+    const source = path.join(directory, segments[0].file);
+    try { await rename(source, temporary); return source; }
+    catch (error) {
+      if (error.code !== 'EXDEV') throw error;
+      const { copyFile } = await import('node:fs/promises');
+      await copyFile(source, temporary);
+      return;
+    }
+  }
+  const list = path.join(directory, 'concat.txt');
+  // Relative generated names avoid quoting user paths in the concat language.
+  await writeFile(list, segments.map(segment => `file '${segment.file}'\nduration ${rate.seconds(segment.end - segment.first)}\n`).join(''));
+  const input = segments.length === 1 ? ['-i', path.join(directory, segments[0].file)] : ['-f', 'concat', '-safe', '1', '-i', list];
+  const audio = options.audio ? ['-i', options.audio, '-map', '0:v:0', '-map', '1:a:0', '-af',
+    `atrim=start=${audioOffset + rate.seconds(first)},asetpts=PTS-STARTPTS,apad,atrim=duration=${rate.seconds(total)}`, ...encoding.audio] : ['-map', '0:v:0', '-an'];
+  await childProcess(ffmpeg, [...input, ...audio, '-c:v', 'copy', ...encoding.mux, temporary], events).finished;
+}

package/src/segments.mjs

@@ -0,0 +1,123 @@
+import path from 'node:path';
+import { mkdirSync, readFileSync, writeFileSync, renameSync, openSync, closeSync, unlinkSync, statSync, fsyncSync } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import { fileDigest } from './input-records.mjs';
+import { MultiplaneError } from './errors.mjs';
+import { retryFileOperation } from './user-home.mjs';
+
+export const unavailable = (reason, changes) => new MultiplaneError('resume_unavailable', undefined,
+  { details: { reason, ...(changes ? { changes } : {}) } });
+
+// TODO(design): Document the checkpoint schema and resume.json directory pointer.
+
+export function atomicJSON(file, data) {
+  const temporary = file + '.tmp';
+  const fd = openSync(temporary, 'w');
+  try { writeFileSync(fd, JSON.stringify(data) + '\n'); fsyncSync(fd); } finally { closeSync(fd); }
+  retryFileOperation(() => renameSync(temporary, file), performance.now() + 1000);
+}
+
+export function segmentDirectory(jobDir) {
+  try {
+    const { directory } = JSON.parse(readFileSync(path.join(jobDir, 'resume.json'), 'utf8'));
+    if (!path.isAbsolute(directory) || path.basename(directory) !== 'segments') throw Error('Invalid segment directory.');
+    return directory;
+  }
+  catch { return path.join(jobDir, 'segments'); }
+}
+
+export function readManifest(directory) {
+  try {
+    const value = JSON.parse(readFileSync(path.join(directory, 'manifest.json'), 'utf8'));
+    if (value.schema !== 'multiplane-segments/1' || !value.options || !Array.isArray(value.segments) || !value.inputs) return null;
+    if (typeof value.shot !== 'string' || !Number.isSafeInteger(value.first) || value.first < 0
+      || !Number.isSafeInteger(value.end) || value.end < value.first || value.total !== value.end - value.first
+      || (value.segmentFrames !== null && (!Number.isSafeInteger(value.segmentFrames) || value.segmentFrames < 1))) return null;
+    const starts = new Set();
+    for (const segment of value.segments) {
+      if (!Number.isSafeInteger(segment.first) || segment.first < value.first || segment.first >= value.end
+        || (segment.first - value.first) % value.segmentFrames !== 0
+        || segment.end !== Math.min(value.end, segment.first + value.segmentFrames)
+        || starts.has(segment.first) || typeof segment.file !== 'string' || segment.file !== path.basename(segment.file)) return null;
+      starts.add(segment.first);
+    }
+    return value;
+  } catch { return null; }
+}
+
+export function lockSegments(directory) {
+  mkdirSync(directory, { recursive: true });
+  const file = path.join(directory, 'render.lock');
+  for (;;) {
+    let fd;
+    try { fd = openSync(file, 'wx'); }
+    catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      try {
+        const before = statSync(file);
+        let owner;
+        try { owner = JSON.parse(readFileSync(file, 'utf8')); } catch { /* Do not steal a lock being written. */ }
+        let dead = false;
+        if (Number.isSafeInteger(owner?.pid) && owner.pid > 0) {
+          try { process.kill(owner.pid, 0); } catch (error) { dead = error.code === 'ESRCH'; }
+        }
+        if (dead || (!owner && Date.now() - before.mtimeMs > 10000)) {
+          const after = statSync(file);
+          if (before.ino === after.ino && before.mtimeMs === after.mtimeMs) unlinkSync(file);
+          continue;
+        }
+      } catch (error) { if (error.code === 'ENOENT') continue; throw error; }
+      throw unavailable('running');
+    }
+    try { writeFileSync(fd, JSON.stringify({ pid: process.pid })); fsyncSync(fd); } finally { closeSync(fd); }
+    return () => { try { unlinkSync(file); } catch (error) { if (error.code !== 'ENOENT') throw error; } };
+  }
+}
+
+export function manifestStore(directory, manifest) {
+  const save = () => atomicJSON(path.join(directory, 'manifest.json'), manifest);
+  return { manifest, save,
+    input(file, record) {
+      const previous = manifest.inputs[file];
+      if (previous && previous.sha256 !== record.sha256) throw unavailable('inputs_changed', [file]);
+      if (!previous) { manifest.inputs[file] = record; save(); }
+    },
+  };
+}
+
+export async function checkInputs(manifest) {
+  const changes = [];
+  for (const [file, expected] of Object.entries(manifest.inputs)) {
+    try { if (await fileDigest(file) !== expected.sha256) changes.push(file); }
+    catch { changes.push(file); }
+  }
+  if (changes.length) throw unavailable('inputs_changed', changes);
+}
+
+export function checkEnvironment(expected, actual) {
+  if (!expected) return;
+  const changes = Object.keys(actual).filter(key => key !== 'renderer' && JSON.stringify(expected[key]) !== JSON.stringify(actual[key]));
+  if (changes.length) throw unavailable('environment_changed', changes);
+}
+
+export async function reusableSegments(directory, manifest) {
+  const valid = [];
+  for (const segment of manifest.segments) {
+    if (segment.file !== path.basename(segment.file)) continue;
+    try {
+      const file = path.join(directory, segment.file);
+      if ((await stat(file)).size === segment.bytes && await fileDigest(file) === segment.sha256) valid.push(segment);
+    } catch { /* Missing or damaged segments are rendered again. */ }
+  }
+  return valid;
+}
+
+export function resumeStatus(status, directory) {
+  const manifest = readManifest(segmentDirectory(directory));
+  // TODO(design): Specify missing_manifest for legacy, missing or invalid checkpoints.
+  const reason = status.state === 'succeeded' ? 'succeeded' : !['failed', 'cancelled'].includes(status.state) ? 'running' : !manifest ? 'missing_manifest' : null;
+  return { available: reason === null, reason,
+    framesDone: manifest?.segments.reduce((sum, segment) => sum + segment.end - segment.first, 0)
+      ?? (status.state === 'succeeded' ? status.result?.data?.frames ?? status.done ?? 0 : 0),
+    framesTotal: manifest?.total ?? status.total ?? status.result?.data?.frames ?? 0 };
+}

package/src/server.mjs

@@ -6,6 +6,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { MultiplaneError, invalidOption } from './errors.mjs';
 import { resolveThree } from './three-package.mjs';
+import { recordInput } from './input-records.mjs';
 
 export const root = process.cwd();
 const packageRoot = fileURLToPath(new URL('../', import.meta.url));
@@ -71,6 +72,7 @@ export async function startServer(port = 0, root = process.cwd()) {
       target = await normalizeResourcePath(target);
       if (!await isInsideResourceRoot(resourceBase, target)) { res.writeHead(403); return res.end(); }
       const info = await stat(target);
+      const recorded = await recordInput(target);
       const contentType = { '.wav': 'audio/wav', '.srt': 'text/plain; charset=utf-8', '.mp4': 'video/mp4' }[path.extname(target)] ?? mime[path.extname(target)] ?? 'application/octet-stream';
       const headers = { 'Content-Type': contentType, 'Content-Length': info.size, 'Accept-Ranges': 'bytes' };
       if (req.headers.range) {
@@ -82,10 +84,12 @@ export async function startServer(port = 0, root = process.cwd()) {
         }
         res.writeHead(206, { ...headers, 'Content-Length': end - start + 1, 'Content-Range': `bytes ${start}-${end}/${info.size}` });
         if (req.method === 'HEAD') return res.end();
+        if (recorded) return res.end(recorded.subarray(start, end + 1));
         return createReadStream(target, { start, end }).on('error', () => res.destroy()).pipe(res);
       }
       res.writeHead(200, headers);
       if (req.method === 'HEAD') return res.end();
+      if (recorded) return res.end(recorded);
       createReadStream(target).on('error', () => res.destroy()).pipe(res);
     } catch (error) {
       if (error.code === 'ERR_MODULE_NOT_FOUND') { res.writeHead(503, { 'x-multiplane-error': 'three_not_installed' }); return res.end('Optional three.js is not installed.'); }