multiplane 0.3.13 → 0.3.16

package/README.en.md

@@ -133,7 +133,7 @@ For the full contract, patterns that break determinism, and 3D layer usage, see
 
 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`, with the reason) when a file the shot loaded or the audio file has changed, or the Multiplane, Chromium or FFmpeg version, the raster mode or the encoder differs, so a film is never joined from mismatched parts; a different GPU or driver only produces a warning (`resume_renderer_changed`). `multiplane status` reports whether a job can be resumed and how many frames are done. See section 6.1 of the protocol.
+`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`, with the reason) when a file the shot loaded or the audio file has changed, or the Multiplane, Chromium or FFmpeg version, the raster mode or the encoder differs, so a film is never joined from mismatched parts; a different GPU or driver only produces a warning (`resume_renderer_changed`). New checkpoints track both requested resource paths and their resolved files: retargeting a symlink (including a project-root alias) to different content also prevents resume. `multiplane status` reports whether a job can be resumed and how many frames are done. See section 6.1 of the protocol.
 
 A stuck browser does not stall a render forever. If a worker holds frames but delivers none for `max(120 seconds, 10 × the slowest frame so far)`, its browser is closed and relaunched, the frame is rendered again from scratch (with the same pixels), and a `worker_stalled` warning is reported. Each frame is retried at most twice; a third stall ends the job with `browser_crashed`. Segments already encoded are kept, so the job can be resumed.
 
@@ -287,7 +287,7 @@ npm install three@0.180.0
 - **Tray popover**: on Windows and macOS, clicking the tray icon opens a small panel with running, queued and recently finished jobs. The tray icon and the taskbar button show render progress. Linux keeps the system menu.
 - **Environment**: check whether the browser, GPU rasterization, FFmpeg, and other requirements are ready; on first use, **Install browser** here downloads Chromium. Install and update the Multiplane skill for Claude Code (`~/.claude/skills/`) and Codex (`~/.agents/skills/`), without directly overwriting user modifications.
 - **Settings**: write the user config `config.json` described above.
-- **Hosted renders** (off by default): when turned on in Settings, renders started by an agent are run by the app instead of the agent's session, so they keep going when the session ends. One hosted render runs at a time and the rest wait in a queue. The agent's command and output stay the same, and `multiplane wait <job>` picks a job up again after a session restarts. With hosting on, closing the window keeps the app in the system tray. See section 11 of the protocol.
+- **Hosted renders** (off by default): when turned on in Settings, renders started by an agent are run by the app instead of the agent's session, so they keep going when the session ends. One hosted render runs at a time and the rest wait in a queue. If an executor cannot start, that job reports a failure and the queue continues instead of retrying it indefinitely. The agent's command and output stay the same, and `multiplane wait <job>` picks a job up again after a session restarts. With hosting on, closing the window keeps the app in the system tray. See section 11 of the protocol.
 - **Updates**: the app checks GitHub for a new release at startup and once a day (can be turned off). On Windows it downloads and installs the update in the app; on macOS and Linux it links to the download page. The About page lists what changed in each version since the one installed, in the interface language.
 - The interface is in English and Simplified Chinese. It follows the system language and can be switched in Settings.
 

package/README.md

@@ -133,7 +133,7 @@ Shot.define({
 
 镜头路径相对资源根 `--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`，并说明是哪一项），以免拼出前后不一致的片子；只是显卡或驱动不同，则只给出警告（`resume_renderer_changed`）。`multiplane status` 会告诉你一个作业能不能续传、已经渲完多少帧。见协议第 6.1 节。
+`render` 按约 10 秒一段编码，每段编完就落盘。渲染中途停下（进程被杀、死机、断电、浏览器反复崩溃、手动停止）后，`multiplane resume <job>` 会跳过已经编好的段、只渲剩下的，最后不重新编码地拼成成片，画面与一次渲完的逐帧相同。续传沿用原作业的全部参数；镜头加载过的文件或音频文件改了，或 Multiplane、Chromium、FFmpeg 的版本、光栅模式、编码器变了，会拒绝续传（`resume_unavailable`，并说明是哪一项），以免拼出前后不一致的片子；只是显卡或驱动不同，则只给出警告（`resume_renderer_changed`）。新的检查点同时记录资源的请求路径和实际文件；符号链接（包括项目根目录的别名）改为指向不同内容时，也会拒绝续传。`multiplane status` 会告诉你一个作业能不能续传、已经渲完多少帧。见协议第 6.1 节。
 
 浏览器卡住时，渲染也不会一直挂着：某个进程拿着帧、却在 `max(120 秒, 此前最慢一帧耗时的 10 倍)` 内一帧都交不出来时，会关掉它的浏览器、重新启动，并把那一帧从头重渲（像素相同），同时报 `worker_stalled` 警告。每一帧最多重试两次，第三次再卡住，作业以 `browser_crashed` 结束；已经编好的段会保留，之后可以用 `resume` 接着渲。
 
@@ -287,7 +287,7 @@ npm install three@0.180.0
 - **托盘弹窗**：在 Windows 和 macOS 上点托盘图标，会打开一个小面板，列出进行中、排队中和最近完成的作业；托盘图标和任务栏按钮会显示渲染进度。Linux 上仍是系统菜单。
 - **环境**：检查浏览器、GPU 光栅、FFmpeg 等是否就绪，首次使用时在这里点“安装浏览器”下载 Chromium；给 Claude Code（`~/.claude/skills/`）和 Codex（`~/.agents/skills/`）安装、更新 Multiplane 的 skill，自己改过的不会被直接覆盖。
 - **设置**：写入上文的用户配置 `config.json`。
-- **托管渲染**（默认关闭）：在设置里开启后，agent 发起的渲染改由软件执行，不再挂在 agent 的会话上，会话结束也会照常做完。一次只执行一个托管渲染，其余排队。agent 的命令和输出不变；会话重启后用 `multiplane wait <job>` 接上之前的作业。开启托管后，关闭窗口时软件留在系统托盘。见协议第 11 节。
+- **托管渲染**（默认关闭）：在设置里开启后，agent 发起的渲染改由软件执行，不再挂在 agent 的会话上，会话结束也会照常做完。一次只执行一个托管渲染，其余排队。执行进程启动失败时，该作业会报告失败，后续队列可以继续，不会无限重试同一个作业。agent 的命令和输出不变；会话重启后用 `multiplane wait <job>` 接上之前的作业。开启托管后，关闭窗口时软件留在系统托盘。见协议第 11 节。
 - **更新**：启动时和之后每天检查一次 GitHub 上的新版本（可以关闭）。Windows 上在软件里下载并安装；macOS 和 Linux 上打开下载页。“关于”页会按界面语言列出从已安装版本起每个版本的更新内容。
 - 界面有英文和简体中文，默认跟随系统语言，也可以在设置里切换。
 

package/package.json

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

package/skills/multiplane/SKILL.md

@@ -73,7 +73,7 @@ Shot.define({
 | `fps` | No | Frame rate, default 30. |
 | `fonts` | No | Fonts to wait for: `[['48px MyFont', 'text used'], ...]`. |
 | `setup()` | No | One-time preparation (load images, create a 3D scene, etc.). May return a Promise; the renderer waits for it before starting. |
-| `cuts` | No | Array of hard cut times (seconds). Motion blur time samples do not cross these times. **Declare every hard cut in the image**, or frames on either side of the cut will blur together. |
+| `cuts` | No | Array of hard cut times (seconds). Motion blur time samples do not cross these times. **Declare every hard cut in the image**, or frames on either side of the cut will blur together. This includes instant changes inside a scene: a state that snaps on or off (a pressed button, a panel that collapses), an effect or impulse that starts at full strength, a caption that swaps. Undeclared, the frame at that instant blends both states and is rendered with the maximum number of samples, which cannot make a jump any smoother. |
 | `post` | No | Post-processing defaults: `motionBlur` (time samples per frame; 1 disables it), `maxMotionBlur` (upper limit for adding samples where motion is fast; see below), `shutter` (shutter fraction of a frame; 0.5 means 180°), `grain` (film grain intensity; 0 disables it). Command-line options override these. |
 | `blurAt(t)` | No | Return the required number of time samples (a positive integer) at this time, using fewer samples for static sections and more for fast motion. |
 | `meta` | No | Any JSON data for tools that read the shot (beats, captions, notes), at most 1 MiB. Readable as `SHOT.meta`; returned by `inspect`; never affects pixels. |
@@ -181,6 +181,8 @@ FFmpeg is not bundled. It is found in this order: `--ffmpeg <path>`, the environ
 
 Motion blur quality: the shot decides whether there is motion blur (`post.motionBlur` above 1, the starting number of samples); `--quality` decides how many samples fast frames get. The default `standard` compares adjacent samples block by block and starts at `motionBlur` but at most 4 (an explicit `--motion-blur` still sets the start; a limit no larger than the start keeps the count fixed), and doubles the count wherever something moved more than about 2 pixels, up to 32; `fast` is the same with a limit of 16; `high` starts at `motionBlur`, uses about 1 pixel and goes up to 256. Static frames drop to 1 sample. Use the default `standard` for iterating and for the final render: on real shots `high` takes several times longer for a difference visible only when zoomed in. Use `fast` when the user asks for speed over quality (quick reviews of long shots, renders that are not the final deliverable); it renders sooner and very fast motion shows slightly more visible steps. Use `high` only when the user asks, for stills that will be viewed up close, or when very fast thin motion still strobes under `standard`. Do not raise `motionBlur` for the whole shot to fix strobing; use `high`, or `--max-motion-blur` for a custom limit. `result.data.blurSamples` (`{ min, max, mean, histogram }`) shows the counts used. A shot with its own `blurAt(t)` keeps full control of the count.
 
+Things that change in discrete steps instead of moving (grain or noise offsets that jump every few frames, flicker, random glitch patterns, re-seeded effects) should take their time from `SHOT.sampleContext?.frameTime ?? t`, for example `Math.floor((SHOT.sampleContext?.frameTime ?? t) * 24)`. `frameTime` is the time of the output frame and is the same for every motion-blur sample of that frame, so the step stays crisp instead of blending two states, and it does not push the sample count up. Keep continuous motion (position, rotation, scale, fades) on `t`.
+
 When the user wants an image rather than a video (a cover, poster, thumbnail or illustration), write a shot and use `stills` for the final output: each PNG gets the same supersampling (`--scale 2`), motion blur, depth of field and `--alpha` as video. Pick a time during motion if the still should show motion blur. Hand over the `t-<seconds>.png` file from `result.data.stills`, not the contact sheet.
 
 Use `--draft` with `render` or `stills` while iterating: it captures at a scale of at most 0.5 and upscales, with no motion blur and no grain, so it is faster and visibly lower in quality. Options you pass explicitly override the preset. Render the final video without `--draft`; `result.data.draft` is `true` when a draft was produced, so do not hand a draft over as the final result.

package/src/capture.mjs

@@ -40,7 +40,7 @@ async function openShotOnce(shot, scale = 1, options = {}) {
     hint: 'Files under node_modules are not served. Use --root to point to the package directory (for example, --root node_modules/multiplane).',
   });
   try { await access(entry); } catch { throw new MultiplaneError('shot_not_found'); }
-  const server = await startServer(0, root);
+  const server = await startServer(0, inputRoot);
   let browser, page, crashed = false;
   try {
     browser = await launchBrowser(options);
@@ -120,9 +120,9 @@ async function openShotOnce(shot, scale = 1, options = {}) {
     if (alpha && cdp) await cdp.send('Emulation.setDefaultBackgroundColorOverride', { color: { r: 0, g: 0, b: 0, a: 0 } });
     const timings = { renderCallMs: 0, screenshotMs: 0 };
     let closing, sampleContextUsed = false, motionProbeUsed = false, dofSamples = 0;
-    const draw = async (t, { motionBlur = 1, motionBlurBase = motionBlur, motionProbeTime, dofMotionSamples, dofMotionIndex } = {}) => {
+    const draw = async (t, { frameTime = t, motionBlur = 1, motionBlurBase = motionBlur, motionProbeTime, dofMotionSamples, dofMotionIndex } = {}) => {
         const renderStart = performance.now();
-        const changed = await page.evaluate(({ t, motionBlur, motionBlurBase, motionProbeTime, dofMotionSamples, dofMotionIndex, alpha }) => {
+        const changed = await page.evaluate(({ t, frameTime, motionBlur, motionBlurBase, motionProbeTime, dofMotionSamples, dofMotionIndex, alpha }) => {
           globalThis.__multiplaneStatic?.suspend();
           if (alpha) document.documentElement.style.setProperty('--multiplane-page-background', 'transparent');
           const stage = document.querySelector('#stage');
@@ -136,7 +136,7 @@ async function openShotOnce(shot, scale = 1, options = {}) {
           const previous = SHOT.sampleContext;
           let contextUsed = false;
           // TODO(design): Document motionBlurBase, stable across nested refinements.
-          SHOT.sampleContext = { time: t, motionBlurBase, get motionBlur() { contextUsed = true; return motionBlur; } };
+          SHOT.sampleContext = { time: t, frameTime, motionBlurBase, get motionBlur() { contextUsed = true; return motionBlur; } };
           let failure;
           // Private renderer/layer handshake; never part of the shot contract.
           const probe = globalThis.__multiplaneMotionProbe = { time: motionProbeTime, used: false, motionSamples: dofMotionSamples, motionIndex: dofMotionIndex, samples: 0 };
@@ -148,7 +148,7 @@ async function openShotOnce(shot, scale = 1, options = {}) {
           stage.getBoundingClientRect();
           const changed = globalThis.__multiplaneStatic?.read() ?? true;
           return { failure, contextUsed, probeUsed: probe.used, dofSamples: probe.samples, changed, reason: globalThis.__multiplaneStatic?.reason };
-        }, { t, motionBlur, motionBlurBase, motionProbeTime, dofMotionSamples, dofMotionIndex, alpha }).then(({ failure, changed, contextUsed, probeUsed, dofSamples: count, reason }) => {
+        }, { t, frameTime, motionBlur, motionBlurBase, motionProbeTime, dofMotionSamples, dofMotionIndex, alpha }).then(({ failure, changed, contextUsed, probeUsed, dofSamples: count, reason }) => {
           sampleContextUsed = contextUsed;
           motionProbeUsed = probeUsed;
           dofSamples = count;

package/src/config-lock.mjs

@@ -0,0 +1,94 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { hostname } from 'node:os';
+import { processCreatedAt } from './process-identity.mjs';
+import { MultiplaneError } from './errors.mjs';
+
+const schema = 'multiplane-config-lock/1';
+const ownerName = /^[0-9a-f-]{36}\.json$/;
+
+async function removeEmpty(lock) {
+  try { await fs.rmdir(lock); }
+  catch (error) {
+    // Never recursively remove a directory that may contain another owner.
+    if (!['ENOENT', 'ENOTEMPTY', 'EEXIST', 'ENOTDIR'].includes(error.code)) throw error;
+  }
+}
+
+async function release(lock, name) {
+  try { await fs.unlink(path.join(lock, name)); }
+  catch (error) { if (['ENOENT', 'ENOTDIR'].includes(error.code)) return; throw error; }
+  await removeEmpty(lock);
+}
+
+async function recover(lock) {
+  try {
+    // Legacy empty files have no verifiable owner. Age alone is not proof
+    // that a writer died, so leave them (and unrecognized locks) untouched.
+    if (!(await fs.lstat(lock)).isDirectory()) return;
+    const names = await fs.readdir(lock);
+    // An empty or partial directory may belong to a writer initializing its
+    // owner record. Only the successful marker remover may remove emptiness.
+    if (names.length !== 1 || !ownerName.test(names[0])) return;
+    let owner;
+    try { owner = JSON.parse(await fs.readFile(path.join(lock, names[0]), 'utf8')); }
+    catch (error) { if (error instanceof SyntaxError) return; throw error; }
+    if (owner?.schema !== schema || owner.host !== hostname() || !Number.isSafeInteger(owner.pid) || owner.pid <= 0) return;
+    let dead = false;
+    try { process.kill(owner.pid, 0); }
+    catch (error) { if (error.code !== 'ESRCH') return; dead = true; }
+    if (!dead && typeof owner.createdAt === 'string' && Number.isFinite(Date.parse(owner.createdAt))) {
+      const current = await processCreatedAt(owner.pid);
+      dead = current !== null && current !== owner.createdAt;
+    }
+    // The unique filename, not a stat/unlink comparison, protects a new
+    // owner from a delayed release or a second concurrent recovery.
+    if (dead) await release(lock, names[0]);
+  } catch (error) {
+    if (!['ENOENT', 'ENOTDIR'].includes(error.code)) throw error;
+  }
+}
+
+export async function lockConfiguration(file, { timeout = 10000 } = {}) {
+  const lock = file + '.lock', name = randomUUID() + '.json';
+  // Resolve identity before acquiring the directory, not while it is empty.
+  const owner = JSON.stringify({
+    schema, host: hostname(), pid: process.pid, createdAt: await processCreatedAt(process.pid),
+  }) + '\n';
+  const deadline = performance.now() + timeout;
+  for (;;) {
+    try {
+      // Unlike rename on Windows, mkdir never replaces a legacy lock file.
+      await fs.mkdir(lock);
+      break;
+    } catch (error) {
+      if (!['EEXIST', 'ENOTEMPTY', 'ENOTDIR', 'EISDIR', 'EPERM', 'EACCES'].includes(error.code)) throw error;
+      // The previous owner may release the lock before this inspection.
+      try { await fs.lstat(lock); }
+      catch (missing) {
+        if (missing.code !== 'ENOENT') throw missing;
+        if (performance.now() >= deadline) throw error;
+        await new Promise(resolve => setTimeout(resolve, 25));
+        continue;
+      }
+      if (performance.now() >= deadline) {
+        throw new MultiplaneError('config_locked', `Configuration is locked: ${lock}`, {
+          cause: error, details: { path: lock },
+          hint: 'Close other Multiplane processes and retry. If the lock remains, remove it only after confirming no process is changing settings.',
+        });
+      }
+      await recover(lock);
+      await new Promise(resolve => setTimeout(resolve, 25));
+    }
+  }
+  try { await fs.writeFile(path.join(lock, name), owner, { flag: 'wx' }); }
+  catch (error) {
+    // We acquired this directory and no contender can reclaim an unfinished
+    // owner record. Clean up only our own file and the now-empty directory.
+    await fs.rm(path.join(lock, name), { force: true });
+    await removeEmpty(lock);
+    throw error;
+  }
+  return () => release(lock, name);
+}

package/src/config.mjs

@@ -1,10 +1,11 @@
 import path from 'node:path';
 import { migrateUserHome } from './home-migration.mjs';
-import * as fs from 'node:fs/promises';
+import fs from 'node:fs/promises';
 import { randomUUID } from 'node:crypto';
 import { userHome } from './platform.mjs';
 import { MultiplaneError, invalidOption } from './errors.mjs';
 import { ffmpegOutput } from './ffmpeg.mjs';
+import { lockConfiguration } from './config-lock.mjs';
 
 export const configKeys = ['ffmpeg', 'raster', 'encoder', 'workers', 'jobsDir', 'hosted'];
 export async function probeFfmpeg(file) {
@@ -56,15 +57,7 @@ export class Configuration {
     }
     this.prepare();
     await fs.mkdir(path.dirname(this.file), { recursive: true });
-    const lock = this.file + '.lock', deadline = performance.now() + 10000;
-    let handle;
-    while (!handle) {
-      try { handle = await fs.open(lock, 'wx'); }
-      catch (error) {
-        if (error.code !== 'EEXIST' || performance.now() >= deadline) throw error;
-        await new Promise(resolve => setTimeout(resolve, 25));
-      }
-    }
+    const unlock = await lockConfiguration(this.file);
     const temporary = this.file + '.' + randomUUID() + '.tmp';
     let result;
     try {
@@ -72,7 +65,7 @@ export class Configuration {
       await fs.writeFile(temporary, JSON.stringify({ ...values, schema: 'multiplane/1', [key]: value }, null, 2) + '\n', { flag: 'wx' });
       await fs.rename(temporary, this.file);
       result = { ...await this.read(undefined, true), changed: key };
-    } finally { await fs.unlink(temporary).catch(() => {}); await handle.close(); await fs.unlink(lock); }
+    } finally { await fs.unlink(temporary).catch(() => {}); await unlock(); }
     if (key === 'ffmpeg' && value !== null) result.check = await probeFfmpeg(value);
     return result;
   }

package/src/errors.mjs

@@ -13,6 +13,7 @@ export const errorCodes = Object.freeze(Object.fromEntries([
   [3, 'wait_timeout', 'Timed out waiting for job completion.'],
   [2, 'job_not_found', 'Job status was not found or is invalid.'],
   [3, 'config_invalid', 'User configuration is not a JSON object.'],
+  [3, 'config_locked', 'User configuration is being changed by another process.'],
   [3, 'skill_modified', 'The installed skill has local modifications.'],
   [3, 'skill_blocked', 'The skill directory cannot be safely changed.'],
   [3, 'skill_changed', 'The installed skill changed since inspection.'],

package/src/hosted.mjs

@@ -97,9 +97,10 @@ export const resultExitCode = result => result.ok ? 0 : errorCodes[result.code]?
 
 // Keep bytes intact across partial writes and UTF-8 boundaries. Only complete lines
 // are published, so timeout diagnostics cannot splice into a partial JSON record.
-export async function followJob(directory, { timeout = Infinity, onBytes, onEvent, interval = 100 } = {}) {
+export async function followJob(directory, { timeout = Infinity, onBytes, onEvent, interval = 100, inspect = processCreatedAt } = {}) {
   const deadline = performance.now() + timeout * 1000;
   let offset = 0, pending = Buffer.alloc(0);
+  let identity = null;
   for (;;) {
     let handle;
     try {
@@ -125,8 +126,21 @@ export async function followJob(directory, { timeout = Infinity, onBytes, onEven
       || typeof status.state !== 'string') throw new MultiplaneError('job_not_found');
     // A result is committed to the event log before status; read the next poll.
     if (!status.result && status.state === 'running') {
-      try { process.kill(status.pid, 0); }
-      catch (error) { if (error.code === 'ESRCH') throw new MultiplaneError('internal_error', 'Job process exited without a result.'); }
+      let exited = false, present = false;
+      try { process.kill(status.pid, 0); present = true; }
+      catch (error) { exited = error.code === 'ESRCH'; }
+      if (present) {
+        if (!identity || identity.pid !== status.pid || identity.startedAt !== status.startedAt
+          || performance.now() >= identity.expiresAt) {
+          const createdAt = await Promise.resolve().then(() => inspect(status.pid)).catch(() => null);
+          // Cache failed queries too, avoiding a subprocess on every poll.
+          identity = { pid: status.pid, startedAt: status.startedAt, createdAt, expiresAt: performance.now() + 10000 };
+        }
+        const { createdAt } = identity;
+        // Allow two seconds for platform clock rounding; failed queries stay unknown.
+        exited = Date.parse(createdAt) - Date.parse(status.startedAt) > 2000;
+      }
+      if (exited) throw new MultiplaneError('internal_error', 'Job process exited without a result.');
     }
     if (performance.now() >= deadline) throw new MultiplaneError('wait_timeout');
     await delay(interval);

package/src/input-records.mjs

@@ -12,9 +12,15 @@ export async function fileDigest(file) {
   for await (const bytes of createReadStream(file)) hash.update(bytes);
   return hash.digest('hex');
 }
-export async function recordInput(file) {
+export async function recordInput(file, requested = file) {
   const record = inputRecords.getStore();
   if (!record) return;
+  // Bind logical aliases to the bytes read from the canonical served target.
+  // Reading the alias again could race a retarget or reuse its stale media cache.
+  const remember = value => {
+    if (requested !== file) record(requested, value);
+    record(file, value);
+  };
   const info = await stat(file);
   // Large media stays streamed. Cache only its digest, never its body.
   if (info.size > 1024 * 1024) {
@@ -24,10 +30,10 @@ export async function recordInput(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 });
+    remember({ bytes: info.size, sha256 });
     return;
   }
   const bytes = await readFile(file);
-  record(file, { bytes: bytes.length, sha256: digest(bytes) });
+  remember({ bytes: bytes.length, sha256: digest(bytes) });
   return bytes;
 }

package/src/post.mjs

@@ -264,7 +264,7 @@ export function createPostCapture(capture, options = {}, fps = capture.fps) {
         const changes = [];
         const observeStart = performance.now();
         for (const time of probes) {
-          changes.push(await capture.observe(time, { motionBlur, motionBlurBase }));
+          changes.push(await capture.observe(time, { frameTime: t, motionBlur, motionBlurBase }));
           observedTime = time;
           if (changes.at(-1)) break;
         }
@@ -280,7 +280,7 @@ export function createPostCapture(capture, options = {}, fps = capture.fps) {
       let finalCapture = hooked || motionBlur === 1;
       let selectedTimes = times;
       let dofMotionSamples = new Set(times).size;
-      const context = (observed, time) => ({ motionBlur, motionBlurBase, observed,
+      const context = (observed, time) => ({ frameTime: t, motionBlur, motionBlurBase, observed,
         motionProbeTime: finalCapture ? undefined : t,
         dofMotionSamples: finalCapture ? dofMotionSamples : undefined,
         dofMotionIndex: finalCapture ? [...new Set(selectedTimes)].sort((a, b) => a - b).indexOf(time) : undefined });
@@ -333,40 +333,54 @@ export function createPostCapture(capture, options = {}, fps = capture.fps) {
         // 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;
-        // 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);
-        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;
+        // Inspect the former probes without screenshots so conditional context
+        // reads keep selecting the compatible grid, including on still frames.
+        if (capture._inspectSample) {
+          for (const time of new Set([t, ...endpoints])) {
+            const start = performance.now();
+            await capture._inspectSample(time, context(false, time));
+            stats.captureMs += performance.now() - start;
+            contextUsed ||= capture.sampleContextUsed === true;
+          }
+          observedTime = undefined;
+        }
+        const initialGrid = grids.get(motionBlur);
+        const nearest = initialGrid.reduce((best, time) => Math.abs(time - t) < Math.abs(best - t) ? time : best);
+        let probeLegacy = contextUsed, still;
+        while (true) {
+          const probes = probeLegacy ? [t, endpoints[0], endpoints[1]] : [initialGrid[0], initialGrid.at(-1), nearest];
+          await sampleMany(probes.slice(0, 2), true);
+          still = cache.get(probes[0]).image.data.equals(cache.get(probes[1]).image.data);
+          if (still) {
+            await sampleMany([probes[2]], true);
+            still = cache.get(probes[0]).image.data.equals(cache.get(probes[2]).image.data);
+          }
+          if (!contextUsed || probeLegacy) break;
+          // A read at a new grid probe must also restart a potentially still frame.
+          probeLegacy = true; cache.clear(); observedTime = undefined;
         }
         let legacy = contextUsed;
         let grid = legacy ? times : grids.get(motionBlur);
         if (still) {
-          png = centerProbe.png; result = centerProbe.image; usedSamples = 1; selectedTimes = [t];
+          const time = contextUsed ? t : nearest, probe = cache.get(time);
+          png = probe.png; result = probe.image; usedSamples = 1; selectedTimes = [time];
           stats.staticFrames++; stats.adaptiveFrames++;
         } else {
           if (legacy) cache.clear();
           while (true) {
-            await sampleMany([...grid, t], true);
+            await sampleMany(legacy ? [...grid, t] : grid, true);
             // A conditional read discovered after the probes restarts the frame
             // on the old grids. No image from a different sample context survives.
             if (contextUsed && !legacy) {
               legacy = true; motionBlur = initialMotionBlur;
               cache.clear(); observedTime = undefined; grid = times; continue;
             }
-            const images = grid.map(time => cache.get(time).image), center = cache.get(t);
+            const images = grid.map(time => cache.get(time).image);
+            const representative = legacy ? t : grid.reduce((best, time) => Math.abs(time - t) < Math.abs(best - t) ? time : best);
+            const center = cache.get(representative);
             const identical = images.every(image => image.data.equals(center.image.data));
             if (identical) {
-              png = center.png; result = center.image; usedSamples = 1; selectedTimes = [t];
+              png = center.png; result = center.image; usedSamples = 1; selectedTimes = [representative];
               stats.staticFrames++; stats.adaptiveFrames++; break;
             }
             let difference = 0;

package/src/server.mjs

@@ -16,6 +16,7 @@ export async function startServer(port = 0, root = process.cwd()) {
   if (typeof root !== 'string' || !root.trim()) throw invalidOption('--root', '--root must be a directory path.');
   if (!String(port).trim() || !Number.isInteger(Number(port)) || Number(port) < 0 || Number(port) > 65535) throw invalidOption('--port', '--port must be an integer from 0 to 65535.');
   port = Number(port);
+  const requestedRoot = path.resolve(root);
   const base = await normalizeResourcePath(root);
   try { if (!(await stat(base)).isDirectory()) throw new Error(); }
   catch { throw invalidOption('--root', '--root must be an existing directory.'); }
@@ -43,7 +44,7 @@ export async function startServer(port = 0, root = process.cwd()) {
 
       const segments = pathname.replaceAll('\\', '/').split('/');
       if (segments.some(p => p.startsWith('.') || p === 'node_modules')) { res.writeHead(403); return res.end(); }
-      let resourceRoot = root, resourceBase = base, resourcePath = pathname;
+      let resourceRoot = root, resourceBase = base, requestedResourceRoot = requestedRoot, resourcePath = pathname;
       // /multiplane/ is reserved for runtime resources.
       if (pathname.startsWith('/multiplane/')) {
         if (pathname === '/multiplane/shots.json') {
@@ -58,6 +59,7 @@ export async function startServer(port = 0, root = process.cwd()) {
           resourcePath = pathname.slice('/multiplane/vendor/three'.length);
           if (!/^\/(build|examples\/jsm)\/.*\.js$/.test(resourcePath)) { res.writeHead(403); return res.end(); }
         } else { res.writeHead(404); return res.end(); }
+        requestedResourceRoot = resourceRoot;
         resourceBase = await normalizeResourcePath(resourceRoot);
       }
       let target = path.resolve(resourceRoot, `.${resourcePath}`);
@@ -68,11 +70,15 @@ export async function startServer(port = 0, root = process.cwd()) {
         if (pathname === '/favicon.ico' && error.code === 'ENOENT') { res.writeHead(204); return res.end(); }
         throw error;
       }
-      if (targetInfo.isDirectory()) target = path.join(target, 'index.html');
+      let requestedTarget = path.resolve(requestedResourceRoot, `.${resourcePath}`);
+      if (targetInfo.isDirectory()) {
+        target = path.join(target, 'index.html');
+        requestedTarget = path.join(requestedTarget, 'index.html');
+      }
       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 recorded = await recordInput(target, requestedTarget);
       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) {