multiplane 0.3.6 → 0.3.8

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));
@@ -61,16 +62,17 @@ export async function startServer(port = 0, root = process.cwd()) {
       }
       let target = path.resolve(resourceRoot, `.${resourcePath}`);
       if (!await isInsideResourceRoot(resourceRoot, target)) { res.writeHead(403); return res.end(); }
-      let targetInfo;
-      try { targetInfo = await stat(target); }
-      catch (error) {
-        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 targetInfo;
+      try { targetInfo = await stat(target); }
+      catch (error) {
+        if (pathname === '/favicon.ico' && error.code === 'ENOENT') { res.writeHead(204); return res.end(); }
+        throw error;
+      }
+      if (targetInfo.isDirectory()) target = path.join(target, '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 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.'); }

package/src/setup.mjs

@@ -1,51 +1,51 @@
-import { fileURLToPath } from 'node:url';
-import { Configuration } from './config.mjs';
-import { Skills } from './skills.mjs';
-import { createEvents, version } from './events.mjs';
-import { asError, invalidOption, MultiplaneError } from './errors.mjs';
-
-export async function setup(command, args, onEvent) {
-  const events = createEvents(command, null, { onEvent });
-  events.start();
-  try {
-    const positional = [], options = {};
-    for (let i = 0; i < args.length; i++) {
-      const token = args[i];
-      if (!token.startsWith('--')) { positional.push(token); continue; }
-      const key = token.slice(2);
-      if (!['json', ...(command === 'skill' ? ['host', 'force', 'expect'] : [])].includes(key) || key in options) throw invalidOption(token, 'Invalid or duplicate option.');
-      if (['json', 'force'].includes(key)) options[key] = true;
-      else { if (args[i + 1] === undefined || args[i + 1].startsWith('--')) throw invalidOption(token, 'Missing option value.'); options[key] = args[++i]; }
-    }
-    const [action, key, value] = positional;
-    let data;
-    if (command === 'config') {
-      if (!['get', 'set', 'unset'].includes(action) || (action === 'get' ? positional.length > 2 : positional.length !== (action === 'set' ? 3 : 2))) throw invalidOption('action', 'Use config get [key], set <key> <value>, or unset <key>.');
-      const config = new Configuration(undefined, process.env, warning => events.warning(warning));
-      data = action === 'get' ? await config.read(key) : await config.save(key, action === 'unset' ? null : value);
-      if (data.check && !data.check.usable) events.warning({ code: 'ffmpeg_unusable', message: 'The saved FFmpeg path is unusable.', details: { reason: data.check.reason } });
-    } else {
-      if (!['status', 'install', 'remove'].includes(action) || positional.length !== 1 || (action !== 'status' && !options.host) || !['all', 'claude', 'codex'].includes(options.host ?? 'all') || (action === 'status' && ('force' in options || 'expect' in options))) throw invalidOption('host', 'Use skill status, install, or remove with --host claude|codex|all.');
-      const skills = new Skills(fileURLToPath(new URL('../skills/multiplane/', import.meta.url)), version);
-      const hosts = await skills.list(!options.host || options.host === 'all' ? ['claude', 'codex'] : [options.host]);
-      if (action === 'status') data = { hosts };
-      else {
-        data = { hosts: [] }; let first;
-        for (const status of hosts) {
-          const item = { host: status.host, action, ok: true, code: null, message: null, target: status.target, version: action === 'install' ? version : null, backup: null };
-          try {
-            if (status.blocked) throw new MultiplaneError('skill_blocked', status.error);
-            // TODO(design): Document --expect null for the missing-copy signature.
-            const expected = options.expect === 'null' ? null : options.expect;
-            Object.assign(item, await skills.change(status.host, action, expected, undefined, !!options.force));
-          } catch (failure) { const error = asError(failure); first ??= error; Object.assign(item, { ok: false, code: error.code, message: error.message, version: status.version }); }
-          data.hosts.push(item);
-        }
-        if (first) { first.result = { data }; throw first; }
-      }
-    }
-    return events.finish(data);
-  } catch (failure) {
-    const error = asError(failure); error.result = events.finish(error.result?.data ?? {}, error); throw error;
-  } finally { events.dispose(); }
-}
+import { fileURLToPath } from 'node:url';
+import { Configuration } from './config.mjs';
+import { Skills } from './skills.mjs';
+import { createEvents, version } from './events.mjs';
+import { asError, invalidOption, MultiplaneError } from './errors.mjs';
+
+export async function setup(command, args, onEvent) {
+  const events = createEvents(command, null, { onEvent });
+  events.start();
+  try {
+    const positional = [], options = {};
+    for (let i = 0; i < args.length; i++) {
+      const token = args[i];
+      if (!token.startsWith('--')) { positional.push(token); continue; }
+      const key = token.slice(2);
+      if (!['json', ...(command === 'skill' ? ['host', 'force', 'expect'] : [])].includes(key) || key in options) throw invalidOption(token, 'Invalid or duplicate option.');
+      if (['json', 'force'].includes(key)) options[key] = true;
+      else { if (args[i + 1] === undefined || args[i + 1].startsWith('--')) throw invalidOption(token, 'Missing option value.'); options[key] = args[++i]; }
+    }
+    const [action, key, value] = positional;
+    let data;
+    if (command === 'config') {
+      if (!['get', 'set', 'unset'].includes(action) || (action === 'get' ? positional.length > 2 : positional.length !== (action === 'set' ? 3 : 2))) throw invalidOption('action', 'Use config get [key], set <key> <value>, or unset <key>.');
+      const config = new Configuration(undefined, process.env, warning => events.warning(warning));
+      data = action === 'get' ? await config.read(key) : await config.save(key, action === 'unset' ? null : value);
+      if (data.check && !data.check.usable) events.warning({ code: 'ffmpeg_unusable', message: 'The saved FFmpeg path is unusable.', details: { reason: data.check.reason } });
+    } else {
+      if (!['status', 'install', 'remove'].includes(action) || positional.length !== 1 || (action !== 'status' && !options.host) || !['all', 'claude', 'codex'].includes(options.host ?? 'all') || (action === 'status' && ('force' in options || 'expect' in options))) throw invalidOption('host', 'Use skill status, install, or remove with --host claude|codex|all.');
+      const skills = new Skills(fileURLToPath(new URL('../skills/multiplane/', import.meta.url)), version);
+      const hosts = await skills.list(!options.host || options.host === 'all' ? ['claude', 'codex'] : [options.host]);
+      if (action === 'status') data = { hosts };
+      else {
+        data = { hosts: [] }; let first;
+        for (const status of hosts) {
+          const item = { host: status.host, action, ok: true, code: null, message: null, target: status.target, version: action === 'install' ? version : null, backup: null };
+          try {
+            if (status.blocked) throw new MultiplaneError('skill_blocked', status.error);
+            // TODO(design): Document --expect null for the missing-copy signature.
+            const expected = options.expect === 'null' ? null : options.expect;
+            Object.assign(item, await skills.change(status.host, action, expected, undefined, !!options.force));
+          } catch (failure) { const error = asError(failure); first ??= error; Object.assign(item, { ok: false, code: error.code, message: error.message, version: status.version }); }
+          data.hosts.push(item);
+        }
+        if (first) { first.result = { data }; throw first; }
+      }
+    }
+    return events.finish(data);
+  } catch (failure) {
+    const error = asError(failure); error.result = events.finish(error.result?.data ?? {}, error); throw error;
+  } finally { events.dispose(); }
+}

package/src/skills.mjs

@@ -1,128 +1,128 @@
-import path from 'node:path';
-import os from 'node:os';
-import * as fs from 'node:fs/promises';
-import { createHash, randomUUID } from 'node:crypto';
-import { MultiplaneError } from './errors.mjs';
-export async function findCommand(name, env = process.env) {
-  const extensions = process.platform === 'win32' ? ['.exe', '.cmd', '.bat', ''] : [''];
-  const search = Object.entries(env).find(([k]) => k.toLowerCase() === 'path')?.[1] ?? '';
-  for (const dir of search.split(path.delimiter).filter(Boolean)) for (const ext of extensions) {
-    const file = path.resolve(dir.replace(/^"|"$/g, ''), name + ext);
-    try { if ((await fs.stat(file)).isFile()) { await fs.access(file, process.platform === 'win32' ? fs.constants.F_OK : fs.constants.X_OK); return file; } } catch {}
-  }
-  return null;
-}
-const marker = '.multiplane.json';
-const hash = bytes => createHash('sha256').update(bytes).digest('hex');
-async function exists(file) { try { await fs.lstat(file); return true; } catch (e) { if (e.code === 'ENOENT') return false; throw e; } }
-// Resolve existing ancestors without creating directories during inspection.
-async function realRoot(root) {
-  try {
-    const resolved = await fs.realpath(root);
-    if (!(await fs.stat(resolved)).isDirectory()) throw Object.assign(Error('Skill root is not a directory'), { code: 'ENOTDIR' });
-    return resolved;
-  }
-  catch (error) {
-    if (error.code !== 'ENOENT' || await exists(root)) throw error;
-    const parent = path.dirname(root);
-    if (parent === root) throw error;
-    return path.join(await realRoot(parent), path.basename(root));
-  }
-}
-const linkedSkill = () => Object.assign(Error('Skill directories cannot contain symbolic links'), { code: 'SKILL_LINK' });
-export async function treeHashes(root) {
-  const files = Object.create(null);
-  async function walk(dir, prefix = '') {
-    if ((await fs.lstat(dir)).isSymbolicLink()) throw linkedSkill();
-    for (const entry of (await fs.readdir(dir, { withFileTypes: true })).sort((a, b) => a.name < b.name ? -1 : 1)) {
-      const name = prefix + entry.name;
-      if (entry.isSymbolicLink()) throw linkedSkill();
-      if (entry.isDirectory()) { files[name + '/'] = null; await walk(path.join(dir, entry.name), name + '/'); }
-      else if (entry.isFile()) { if (name !== marker) files[name] = hash(await fs.readFile(path.join(dir, entry.name))); }
-      else throw Object.assign(Error('Unsupported skill file type'), { code: 'SKILL_LINK' });
-    }
-  }
-  await walk(root); return files;
-}
-export class Skills {
-  queue = Promise.resolve();
-  constructor(source, version, { user = process.env.MULTIPLANE_AGENT_HOME || os.homedir(), env = process.env } = {}) { this.source = source; this.version = version; this.user = user; this.env = env; }
-  target(host) {
-    if (!['claude', 'codex'].includes(host)) throw Error('Invalid agent');
-    return path.join(this.user, host === 'claude' ? '.claude' : '.agents', 'skills', 'multiplane');
-  }
-  async status(host) {
-    const target = path.join(await realRoot(path.dirname(this.target(host))), 'multiplane');
-    const detected = await exists(path.join(this.user, host === 'claude' ? '.claude' : '.codex')) || !!await findCommand(host, this.env);
-    const base = { host, target, detected, availableVersion: this.version, version: null, state: 'missing', signature: null, blocked: false, error: null };
-    if (!await exists(target)) return base;
-    let files;
-    try { files = await treeHashes(target); }
-    catch (error) { if (error.code === 'SKILL_LINK') return { ...base, state: 'modified', blocked: true, error: error.message }; throw error; }
-    const signature = hash(JSON.stringify(files));
-    let record;
-    try { record = JSON.parse(await fs.readFile(path.join(target, marker), 'utf8')); } catch {}
-    const current = await treeHashes(this.source);
-    const known = record?.v === 1 && record.host === host && record.skill === 'multiplane' && Array.isArray(record.releases)
-      ? record.releases.filter(r => r && typeof r.version === 'string' && r.files && typeof r.files === 'object' && !Array.isArray(r.files)) : [];
-    const release = [{ version: this.version, files: current }, ...known].find(r => JSON.stringify(r.files) === JSON.stringify(files));
-    return { ...base, signature, version: release?.version ?? record?.version ?? null, state: release ? release.version === this.version ? 'latest' : 'update' : 'modified' };
-  }
-  list(hosts = ['claude', 'codex']) { return Promise.all(hosts.map(async host => {
-    try { return await this.status(host); }
-    catch (error) { return { host, target: this.target(host), detected: false, availableVersion: this.version, version: null, state: 'error', blocked: true, error: error.message }; }
-  })); }
-  async backupName(host, date = new Date()) {
-    const pad = n => String(n).padStart(2, '0');
-    const base = `multiplane.bak-${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}-${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}`;
-    const parent = await realRoot(path.dirname(this.target(host)));
-    let name = base;
-    for (let i = 2; await exists(path.join(parent, name)); i++) name = `${base}-${i}`;
-    return name;
-  }
-  change(host, action, expected, backupName, force = false) {
-    const operation = this.queue.then(async () => {
-      if (!['install', 'remove'].includes(action)) throw Error('Invalid skill action');
-      backupName ??= await this.backupName(host);
-      if (!/^multiplane\.bak-\d{8}-\d{6}(?:-[2-9]\d*|-1\d+)?$/.test(backupName)) throw Error('Invalid backup name');
-      const before = await this.status(host);
-      if (before.blocked) throw new MultiplaneError('skill_blocked', before.error);
-      if (expected !== undefined && before.signature !== expected) throw new MultiplaneError('skill_changed');
-      if (before.state === 'modified' && !force) throw new MultiplaneError('skill_modified', undefined, { hint: 'Use --force to back up the modified directory before continuing.' });
-      const parent = path.dirname(before.target);
-      await fs.mkdir(parent, { recursive: true });
-      if (await fs.realpath(parent) !== parent) throw Error('Skill path changed');
-      const token = randomUUID(), stage = path.join(parent, '.multiplane-new-' + token);
-      const old = path.join(parent, backupName);
-      if (await exists(old)) throw Error('Backup already exists');
-      let moved = false, installed = false;
-      const remove = async target => {
-        if (path.dirname(path.resolve(target)) !== path.resolve(parent) || path.resolve(target) === path.resolve(parent)) throw Error('Invalid removal target');
-        await fs.rm(target, { recursive: true, force: true });
-      };
-      try {
-        if (action === 'install') {
-          const files = await treeHashes(this.source);
-          await fs.cp(this.source, stage, { recursive: true });
-          let previous;
-          try { previous = JSON.parse(await fs.readFile(path.join(before.target, marker), 'utf8')); } catch {}
-          const releases = previous?.v === 1 && previous.host === host && Array.isArray(previous.releases)
-            ? previous.releases.filter(r => r && typeof r.version === 'string' && r.files && typeof r.files === 'object' && !Array.isArray(r.files)) : [];
-          await fs.writeFile(path.join(stage, marker), JSON.stringify({ v: 1, host, skill: 'multiplane', version: this.version, installedAt: Date.now(), files, releases: [...releases.filter(r => r.version !== this.version), { version: this.version, files }] }, null, 2));
-          if (JSON.stringify(await treeHashes(stage)) !== JSON.stringify(files)) throw Error('Skill source changed during copy');
-        }
-        const latest = await this.status(host);
-        if (latest.blocked || latest.target !== before.target || latest.signature !== before.signature || await fs.realpath(parent) !== parent) throw new MultiplaneError('skill_changed');
-        if (before.state !== 'missing') { await fs.rename(before.target, old); moved = true; }
-        if (action === 'install') { await fs.rename(stage, before.target); installed = true; }
-      } catch (error) {
-        if (installed) await remove(before.target);
-        if (moved) await fs.rename(old, before.target);
-        throw error;
-      } finally { await remove(stage); }
-      if (moved && before.state !== 'modified') await remove(old);
-      return { backup: moved && before.state === 'modified' ? old : null };
-    });
-    this.queue = operation.catch(() => {}); return operation;
-  }
-}
+import path from 'node:path';
+import os from 'node:os';
+import * as fs from 'node:fs/promises';
+import { createHash, randomUUID } from 'node:crypto';
+import { MultiplaneError } from './errors.mjs';
+export async function findCommand(name, env = process.env) {
+  const extensions = process.platform === 'win32' ? ['.exe', '.cmd', '.bat', ''] : [''];
+  const search = Object.entries(env).find(([k]) => k.toLowerCase() === 'path')?.[1] ?? '';
+  for (const dir of search.split(path.delimiter).filter(Boolean)) for (const ext of extensions) {
+    const file = path.resolve(dir.replace(/^"|"$/g, ''), name + ext);
+    try { if ((await fs.stat(file)).isFile()) { await fs.access(file, process.platform === 'win32' ? fs.constants.F_OK : fs.constants.X_OK); return file; } } catch {}
+  }
+  return null;
+}
+const marker = '.multiplane.json';
+const hash = bytes => createHash('sha256').update(bytes).digest('hex');
+async function exists(file) { try { await fs.lstat(file); return true; } catch (e) { if (e.code === 'ENOENT') return false; throw e; } }
+// Resolve existing ancestors without creating directories during inspection.
+async function realRoot(root) {
+  try {
+    const resolved = await fs.realpath(root);
+    if (!(await fs.stat(resolved)).isDirectory()) throw Object.assign(Error('Skill root is not a directory'), { code: 'ENOTDIR' });
+    return resolved;
+  }
+  catch (error) {
+    if (error.code !== 'ENOENT' || await exists(root)) throw error;
+    const parent = path.dirname(root);
+    if (parent === root) throw error;
+    return path.join(await realRoot(parent), path.basename(root));
+  }
+}
+const linkedSkill = () => Object.assign(Error('Skill directories cannot contain symbolic links'), { code: 'SKILL_LINK' });
+export async function treeHashes(root) {
+  const files = Object.create(null);
+  async function walk(dir, prefix = '') {
+    if ((await fs.lstat(dir)).isSymbolicLink()) throw linkedSkill();
+    for (const entry of (await fs.readdir(dir, { withFileTypes: true })).sort((a, b) => a.name < b.name ? -1 : 1)) {
+      const name = prefix + entry.name;
+      if (entry.isSymbolicLink()) throw linkedSkill();
+      if (entry.isDirectory()) { files[name + '/'] = null; await walk(path.join(dir, entry.name), name + '/'); }
+      else if (entry.isFile()) { if (name !== marker) files[name] = hash(await fs.readFile(path.join(dir, entry.name))); }
+      else throw Object.assign(Error('Unsupported skill file type'), { code: 'SKILL_LINK' });
+    }
+  }
+  await walk(root); return files;
+}
+export class Skills {
+  queue = Promise.resolve();
+  constructor(source, version, { user = process.env.MULTIPLANE_AGENT_HOME || os.homedir(), env = process.env } = {}) { this.source = source; this.version = version; this.user = user; this.env = env; }
+  target(host) {
+    if (!['claude', 'codex'].includes(host)) throw Error('Invalid agent');
+    return path.join(this.user, host === 'claude' ? '.claude' : '.agents', 'skills', 'multiplane');
+  }
+  async status(host) {
+    const target = path.join(await realRoot(path.dirname(this.target(host))), 'multiplane');
+    const detected = await exists(path.join(this.user, host === 'claude' ? '.claude' : '.codex')) || !!await findCommand(host, this.env);
+    const base = { host, target, detected, availableVersion: this.version, version: null, state: 'missing', signature: null, blocked: false, error: null };
+    if (!await exists(target)) return base;
+    let files;
+    try { files = await treeHashes(target); }
+    catch (error) { if (error.code === 'SKILL_LINK') return { ...base, state: 'modified', blocked: true, error: error.message }; throw error; }
+    const signature = hash(JSON.stringify(files));
+    let record;
+    try { record = JSON.parse(await fs.readFile(path.join(target, marker), 'utf8')); } catch {}
+    const current = await treeHashes(this.source);
+    const known = record?.v === 1 && record.host === host && record.skill === 'multiplane' && Array.isArray(record.releases)
+      ? record.releases.filter(r => r && typeof r.version === 'string' && r.files && typeof r.files === 'object' && !Array.isArray(r.files)) : [];
+    const release = [{ version: this.version, files: current }, ...known].find(r => JSON.stringify(r.files) === JSON.stringify(files));
+    return { ...base, signature, version: release?.version ?? record?.version ?? null, state: release ? release.version === this.version ? 'latest' : 'update' : 'modified' };
+  }
+  list(hosts = ['claude', 'codex']) { return Promise.all(hosts.map(async host => {
+    try { return await this.status(host); }
+    catch (error) { return { host, target: this.target(host), detected: false, availableVersion: this.version, version: null, state: 'error', blocked: true, error: error.message }; }
+  })); }
+  async backupName(host, date = new Date()) {
+    const pad = n => String(n).padStart(2, '0');
+    const base = `multiplane.bak-${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}-${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}`;
+    const parent = await realRoot(path.dirname(this.target(host)));
+    let name = base;
+    for (let i = 2; await exists(path.join(parent, name)); i++) name = `${base}-${i}`;
+    return name;
+  }
+  change(host, action, expected, backupName, force = false) {
+    const operation = this.queue.then(async () => {
+      if (!['install', 'remove'].includes(action)) throw Error('Invalid skill action');
+      backupName ??= await this.backupName(host);
+      if (!/^multiplane\.bak-\d{8}-\d{6}(?:-[2-9]\d*|-1\d+)?$/.test(backupName)) throw Error('Invalid backup name');
+      const before = await this.status(host);
+      if (before.blocked) throw new MultiplaneError('skill_blocked', before.error);
+      if (expected !== undefined && before.signature !== expected) throw new MultiplaneError('skill_changed');
+      if (before.state === 'modified' && !force) throw new MultiplaneError('skill_modified', undefined, { hint: 'Use --force to back up the modified directory before continuing.' });
+      const parent = path.dirname(before.target);
+      await fs.mkdir(parent, { recursive: true });
+      if (await fs.realpath(parent) !== parent) throw Error('Skill path changed');
+      const token = randomUUID(), stage = path.join(parent, '.multiplane-new-' + token);
+      const old = path.join(parent, backupName);
+      if (await exists(old)) throw Error('Backup already exists');
+      let moved = false, installed = false;
+      const remove = async target => {
+        if (path.dirname(path.resolve(target)) !== path.resolve(parent) || path.resolve(target) === path.resolve(parent)) throw Error('Invalid removal target');
+        await fs.rm(target, { recursive: true, force: true });
+      };
+      try {
+        if (action === 'install') {
+          const files = await treeHashes(this.source);
+          await fs.cp(this.source, stage, { recursive: true });
+          let previous;
+          try { previous = JSON.parse(await fs.readFile(path.join(before.target, marker), 'utf8')); } catch {}
+          const releases = previous?.v === 1 && previous.host === host && Array.isArray(previous.releases)
+            ? previous.releases.filter(r => r && typeof r.version === 'string' && r.files && typeof r.files === 'object' && !Array.isArray(r.files)) : [];
+          await fs.writeFile(path.join(stage, marker), JSON.stringify({ v: 1, host, skill: 'multiplane', version: this.version, installedAt: Date.now(), files, releases: [...releases.filter(r => r.version !== this.version), { version: this.version, files }] }, null, 2));
+          if (JSON.stringify(await treeHashes(stage)) !== JSON.stringify(files)) throw Error('Skill source changed during copy');
+        }
+        const latest = await this.status(host);
+        if (latest.blocked || latest.target !== before.target || latest.signature !== before.signature || await fs.realpath(parent) !== parent) throw new MultiplaneError('skill_changed');
+        if (before.state !== 'missing') { await fs.rename(before.target, old); moved = true; }
+        if (action === 'install') { await fs.rename(stage, before.target); installed = true; }
+      } catch (error) {
+        if (installed) await remove(before.target);
+        if (moved) await fs.rename(old, before.target);
+        throw error;
+      } finally { await remove(stage); }
+      if (moved && before.state !== 'modified') await remove(old);
+      return { backup: moved && before.state === 'modified' ? old : null };
+    });
+    this.queue = operation.catch(() => {}); return operation;
+  }
+}

package/src/stills.mjs

@@ -55,7 +55,7 @@ export async function stillsShot(shot, options = {}) {
         }
       };
       for await (const { t, png: buffer, blurSamples, dofSamples } of verifiedFrames(source, { ...options, check: events.check }, times.length)) {
-        dofHistogram[dofSamples] = (dofHistogram[dofSamples] ?? 0) + 1;
+        dofHistogram[dofSamples] = (dofHistogram[dofSamples] ?? 0) + 1;
         histogram[blurSamples] = (histogram[blurSamples] ?? 0) + 1;
         events.check();
         await writeArtifact(path.join(out, `t-${t.toFixed(2)}.png`), buffer);