@litfamily/lithermes 1.0.26 → 1.0.28

package/assets/lithermes-plugin/skills/lit-diagram-drawer/scripts/hostexec.mjs

@@ -0,0 +1,118 @@
+// Child processes that survive Windows. Since the CVE-2024-27980 fix, Node refuses to spawn a
+// .cmd or .bat file without a shell (spawnSync npm.cmd EINVAL), and PATH lookups there depend on
+// PATHEXT. Platform, env and fs probes are arguments so tests can simulate win32 without
+// touching globals. Every skill that spawns tools carries a byte-identical copy of this file.
+import { spawnSync as nodeSpawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { posix, win32 } from 'node:path';
+
+const SHELL_SCRIPT = /\.(?:cmd|bat)$/i;
+const SAFE_ARG = /^[\w@+=:,./\\-]+$/;
+
+export function whichSync(name, { platform = process.platform, env = process.env, exists = existsSync } = {}) {
+  const win = platform === 'win32';
+  const p = win ? win32 : posix;
+  const exts = win ? String(env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';').map((e) => e.trim().toLowerCase()).filter(Boolean) : [''];
+  const hasExt = win && exts.some((e) => name.toLowerCase().endsWith(e.toLowerCase()));
+  // A bare name never matches on Windows: npm leaves an extensionless sh script beside npm.cmd.
+  const names = win ? (hasExt ? [name] : exts.map((e) => name + e)) : [name];
+  const dirs = p.isAbsolute(name) || /[\\/]/.test(name) ? [''] : String(env.PATH ?? env.Path ?? '').split(win ? ';' : ':').map((d) => d.trim().replace(/^"|"$/g, '')).filter(Boolean);
+  for (const dir of dirs) {
+    for (const candidate of names) {
+      const full = dir ? p.join(dir, candidate) : candidate;
+      if (exists(full)) return full;
+    }
+  }
+  return null;
+}
+
+// Quoted for cmd.exe, which still expands %VAR% inside quotes, so those are refused, never escaped.
+export function quoteCmdArg(arg) {
+  const text = String(arg);
+  if (/["%\r\n\0]/.test(text)) throw new Error(`refusing an argument with a quote, percent sign or line break on a Windows shell: ${JSON.stringify(text.slice(0, 40))}`);
+  if (text !== '' && SAFE_ARG.test(text)) return text;
+  return `"${text.replace(/\\+$/, (run) => run + run)}"`;
+}
+
+// Where an npm or npx shim's JavaScript entry lives, so Windows can run it with node directly.
+function npmCli(name, resolved, { env, execPath, exists }) {
+  const cli = `${name}-cli.js`;
+  const dirs = [];
+  if (typeof env.npm_execpath === 'string' && /\.js$/i.test(env.npm_execpath)) dirs.push(win32.dirname(env.npm_execpath));
+  dirs.push(win32.join(win32.dirname(resolved), 'node_modules', 'npm', 'bin'));
+  dirs.push(win32.join(win32.dirname(execPath), 'node_modules', 'npm', 'bin'));
+  return dirs.map((dir) => win32.join(dir, cli)).find((file) => exists(file)) || null;
+}
+
+export function prepareSpawn(command, args = [], options = {}, ctx = {}) {
+  const { platform = process.platform, execPath = process.execPath, exists = existsSync } = ctx;
+  if (platform !== 'win32') return { command, args, options };
+  const env = ctx.env || options.env || process.env;
+  const resolved = whichSync(command, { platform, env, exists });
+  if (!resolved || !SHELL_SCRIPT.test(resolved)) return { command: resolved || command, args, options };
+  const base = win32.basename(resolved).replace(SHELL_SCRIPT, '').toLowerCase();
+  if (base === 'npm' || base === 'npx') {
+    const cli = npmCli(base, resolved, { env, execPath, exists });
+    if (cli) return { command: execPath, args: [cli, ...args], options };
+  }
+  const line = [resolved, ...args].map(quoteCmdArg).join(' ');
+  return { command: line, args: [], options: { ...options, shell: true } };
+}
+
+export function spawnTool(command, args, options, ctx = {}) {
+  const run = ctx.spawnSync || nodeSpawnSync;
+  const prepared = prepareSpawn(command, args, options, ctx);
+  return run(prepared.command, prepared.args, prepared.options);
+}
+
+// One line naming the real cause: the spawn error, the exit status and the last stderr line.
+export function describeSpawnFailure(label, result, { limit = 200 } = {}) {
+  if (!result) return `${label} returned no result`;
+  const tail = String(result.stderr || '').split(/\r?\n/).map((line) => line.trim()).filter(Boolean).at(-1) || '';
+  const clean = tail.replace(/[\u0000-\u001f\u007f]/g, ' ').slice(0, limit);
+  if (result.error) return `${label} could not run: ${result.error.code || 'error'} ${result.error.message}${clean ? ` (${clean})` : ''}`;
+  if (result.signal) return `${label} stopped by ${result.signal}${clean ? ` (${clean})` : ''}`;
+  return `${label} exited ${result.status}${clean ? `: ${clean}` : ''}`;
+}
+
+// Interpreter inside a venv: Scripts\python.exe on Windows, bin/python elsewhere.
+export function venvPython(dir, platform = process.platform) {
+  return platform === 'win32' ? win32.join(dir, 'Scripts', 'python.exe') : posix.join(dir, 'bin', 'python');
+}
+
+// The newest CPython the Office wheels ship for (pip runs --only-binary); 3.15 has no PyYAML wheel,
+// so a python3 that is 3.15 is passed over. A caller whose lock is narrower passes its own max.
+export const PYTHON_MAX = [3, 14];
+
+export function probePython(command, env = process.env, spawn = spawnTool) {
+  const result = spawn(command, ['-c', 'import sys; print("%d.%d.%d" % sys.version_info[:3])'], { encoding: 'utf8', env, timeout: 10000 });
+  if (!result || result.error || result.status !== 0) return null;
+  const version = String(result.stdout || '').trim();
+  const [major, minor] = version.split('.').map(Number);
+  return Number.isInteger(major) && Number.isInteger(minor) ? { version, major, minor } : null;
+}
+
+// The host Python a pinned venv is built from. An override variable, when set, is the only
+// candidate and is not range-checked. Otherwise the newest python3.X from `max` down to `min`,
+// then python3 and python, each kept only when it runs and falls inside min..max.
+// Returns { python, version } or { python: null, detail } naming what was tried.
+export function pickPython({ env = process.env, override, min = [3, 10], max = PYTHON_MAX, probe = probePython } = {}) {
+  if (override && env[override]) {
+    const found = probe(env[override], env);
+    return found ? { python: env[override], version: found.version } : { python: null, detail: `${override} is set to ${env[override]}, which does not run` };
+  }
+  const candidates = [];
+  for (let minor = max[1]; minor >= min[1]; minor -= 1) candidates.push(`python3.${minor}`);
+  candidates.push('python3', 'python');
+  const tried = [];
+  for (const command of candidates) {
+    const found = probe(command, env);
+    if (!found) continue;
+    const inRange = (found.major > min[0] || (found.major === min[0] && found.minor >= min[1]))
+      && (found.major < max[0] || (found.major === max[0] && found.minor <= max[1]));
+    if (inRange) return { python: command, version: found.version };
+    tried.push(`${command} ${found.version}`);
+  }
+  const range = `${min.join('.')} to ${max.join('.')}`;
+  return { python: null, detail: `no supported Python (${range}) on PATH${tried.length ? `; found only ${tried.join(', ')}` : ''}` };
+}

package/assets/lithermes-plugin/skills/lit-docx/scripts/convert_md_to_pdf.py

@@ -106,10 +106,17 @@ def short_author_list(frontmatter: dict) -> str:
     return f"{first_name} et al."
 
 
+def latex_fonts(publisher: dict) -> tuple[str, str]:
+    """The Latin and CJK faces the LaTeX template asks fontspec for."""
+
+    cjk_cfg = publisher["latex"].get("cjk") or {}
+    body_font = ((publisher.get("docx") or {}).get("font") or {}).get("body") or {}
+    return str(body_font.get("family") or "Times New Roman"), str(cjk_cfg.get("main_font") or "Pretendard")
+
+
 def template_variables(frontmatter: dict, publisher_name: str, publisher: dict, detected_locale: str, mode: str) -> dict[str, str]:
     latex_cfg = publisher["latex"]
-    cjk_cfg = latex_cfg.get("cjk") or {}
-    body_font = ((publisher.get("docx") or {}).get("font") or {}).get("body") or {}
+    mainfont, cjk_main_font = latex_fonts(publisher)
     title = str(frontmatter.get("title") or "")
     return {
         "title": title,
@@ -122,8 +129,8 @@ def template_variables(frontmatter: dict, publisher_name: str, publisher: dict,
         "author-list-short": short_author_list(frontmatter),
         "documentclass": str(latex_cfg.get("documentclass") or "article"),
         "classoptions": ",".join(str(item) for item in latex_cfg.get("classoptions") or []),
-        "mainfont": str(body_font.get("family") or "Times New Roman"),
-        "cjk-main-font": str(cjk_cfg.get("main_font") or "Pretendard"),
+        "mainfont": mainfont,
+        "cjk-main-font": cjk_main_font,
         "publisher-name": publisher_name,
         "detected-locale": detected_locale,
         "mode": mode,
@@ -183,6 +190,26 @@ def kpsewhich_has(target: str) -> bool:
     return result.returncode == 0 and bool(result.stdout.strip())
 
 
+def installed_font_families() -> set[str] | None:
+    """Lower-cased family names fontconfig knows, or None when there is no fc-list to ask."""
+
+    fc_list = command_path("fc-list")
+    if not fc_list:
+        return None
+    result = run_checked([fc_list, ":", "family"])
+    if result.returncode != 0:
+        return None
+    return {name.strip().lower() for line in result.stdout.splitlines() for name in line.split(",") if name.strip()}
+
+
+def missing_pdf_fonts(publisher: dict, detected_locale: str, families: set[str] | None) -> list[str]:
+    if families is None:
+        return []
+    mainfont, cjk_main_font = latex_fonts(publisher)
+    wanted = [mainfont] + ([cjk_main_font] if detected_locale in {"ko", "mixed"} else [])
+    return [name for name in dict.fromkeys(wanted) if name.lower() not in families]
+
+
 def preflight_pdf_compile(publisher_name: str, publisher: dict, detected_locale: str) -> None:
     ensure_pandoc()
     if not command_path("xelatex"):
@@ -204,6 +231,13 @@ def preflight_pdf_compile(publisher_name: str, publisher: dict, detected_locale:
         raise SystemExit(
             "Error: xeCJK.sty not found. Korean/CJK PDF output requires xeCJK from TeX Live."
         )
+    missing = missing_pdf_fonts(publisher, detected_locale, installed_font_families())
+    if missing:
+        raise SystemExit(
+            f"BLOCKED: PDF font not installed: {', '.join(missing)} (publisher '{publisher_name}', fontspec would stop XeLaTeX). "
+            "Install the font system-wide (Pretendard ships in skills/lit-pptx/pretendard-font/public/static) "
+            "or change latex.cjk.main_font / the docx body font in templates/registry.yaml to one you have."
+        )
 
 
 def compile_latex_to_pdf(tex_path: Path, pdf_path: Path) -> str:

package/assets/lithermes-plugin/skills/lit-docx/templates/latex/acs/template.tex

@@ -3,6 +3,9 @@
 \usepackage{graphicx}
 \usepackage{hyperref}
 \usepackage{booktabs}
+$if(tables)$
+\usepackage{longtable,array,calc}
+$endif$
 \usepackage{microtype}
 \usepackage{siunitx}
 \usepackage{csquotes}

package/assets/lithermes-plugin/skills/lit-docx/templates/latex/elsevier/template.tex

@@ -4,6 +4,9 @@
 \usepackage{hyperref}
 \usepackage{natbib}
 \usepackage{booktabs}
+$if(tables)$
+\usepackage{longtable,array,calc}
+$endif$
 \usepackage{microtype}
 \usepackage{siunitx}
 \usepackage{csquotes}

package/assets/lithermes-plugin/skills/lit-docx/templates/latex/ieee/template.tex

@@ -3,6 +3,9 @@
 \usepackage{graphicx}
 \usepackage{hyperref}
 \usepackage{booktabs}
+$if(tables)$
+\usepackage{longtable,array,calc}
+$endif$
 \usepackage{microtype}
 \usepackage{siunitx}
 \usepackage{csquotes}

package/assets/lithermes-plugin/skills/lit-docx/templates/latex/korean-generic/template.tex

@@ -3,6 +3,9 @@
 \usepackage{graphicx}
 \usepackage{hyperref}
 \usepackage{booktabs}
+$if(tables)$
+\usepackage{longtable,array,calc}
+$endif$
 \usepackage{microtype}
 \usepackage{siunitx}
 \usepackage{csquotes}

package/assets/lithermes-plugin/skills/lit-docx/templates/latex/nature/template.tex

@@ -3,6 +3,9 @@
 \usepackage{graphicx}
 \usepackage{hyperref}
 \usepackage{booktabs}
+$if(tables)$
+\usepackage{longtable,array,calc}
+$endif$
 \usepackage{microtype}
 \usepackage{siunitx}
 \usepackage{csquotes}

package/assets/lithermes-plugin/skills/lit-humanizer/SKILL.md

@@ -60,6 +60,8 @@ after_payload_edit: "npm --prefix packages/lithermes-installer run sync-plugin -
 
 For a file edit, the Hermes `pre_tool_call` guard blocks block-tier findings in added text passed to `write_file` or `patch` for Markdown, HTML, text, TeX, CSV, SVG, reStructuredText, and AsciiDoc files. Warn-tier findings arrive as advisory context. Fenced code, inline code, exact quoted user spans, and internal `plans/`, `evidence/`, `HANDOFF*`, ledger, `.lit*/`, and `.hermes/` paths are excluded. The guard never scans unchanged file text. Use `write_file` or `patch` for prose edits when pre-save checking is required.
 
+Lead with what a number or thing is. A run of definitions by negation leaves the reader to assemble the meaning from what was ruled out. Write "18,420회는 같은 사람의 반복 방문을 포함한 방문 횟수 합계입니다" in place of `18,420회는 주민 수가 아님. 고유 방문자 수도 아님.`, and give a needed caveat once; an honest limit such as "고유 이용자 지표는 자료에 없습니다" stays. The detector's `negation-cluster` check counts, in each paragraph, list block or Markdown table column (cells of 12 characters or fewer are ignored), after removing fenced code, inline code and `>` quote lines: the Korean forms `아닙니다`, `아님`, `아니다`, `아니며`, `아니라`, `아닌` and their rewordings `~로 읽을 수 없음`, `~로 볼 수 없음`, `~로 보지 않음`, `~을 뜻하지 않음`, `~와는 다름`, `~로 읽으면 안 됨`; the English forms `is not`, `are not`, `isn't`, `aren't`, `not a`, `rather than` and the rewordings `should not be read as`, `does not mean`. Two Korean hits, or three in any language, make it block-tier: the `pre_tool_call` guard denies the `write_file` or `patch`, and the denial text Hermes returns as the tool result carries the rewrite advice and this example. Exactly two hits that are not both Korean stay a warn-tier advisory and the write goes through. Rewording `아님` into `~로 읽을 수 없음` counts the same. Put a bad example you need to show in inline code or a `>` quote so the guard skips it.
+
 DOCX/PPTX/PDF checks happen after a supported file-write event or when a script-like tool reports an explicit output path in its result. Hermes' `post_tool_call` is observer-only, so a finding cannot undo a completed export: revise the source and rebuild the file. DOCX/PPTX extraction uses Python's standard-library ZIP/XML support. PDF extraction uses host `pdftotext` when present; if it is unavailable or fails, the scan fails open and reports that boundary. A DOCX, PPTX or Markdown file that a `terminal` or `execute_code` call builds is checked when that call returns: Hermes' `transform_tool_result` hook finds files modified while the call ran (the reported or session working directory, `workdir`, and folders of paths named in the command, code or output; bounded depth, file count and size, internal paths skipped) and, on a block-tier finding, puts `LIT_HUMANIZER_SCRIPT_DELIVERABLE_BLOCK` with the rule ids in that tool result's `error` field. The command's exit code stays as it ran, and the file stays on disk: edit the build source and rebuild before presenting it. A file written outside those folders, deeper than the scan, or by a background process after the call returned is not seen; run the detector on it explicitly.
 
 ## #contract.language_and_scope

package/assets/lithermes-plugin/skills/lit-pptx/bin/hostexec.mjs

@@ -0,0 +1,118 @@
+// Child processes that survive Windows. Since the CVE-2024-27980 fix, Node refuses to spawn a
+// .cmd or .bat file without a shell (spawnSync npm.cmd EINVAL), and PATH lookups there depend on
+// PATHEXT. Platform, env and fs probes are arguments so tests can simulate win32 without
+// touching globals. Every skill that spawns tools carries a byte-identical copy of this file.
+import { spawnSync as nodeSpawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { posix, win32 } from 'node:path';
+
+const SHELL_SCRIPT = /\.(?:cmd|bat)$/i;
+const SAFE_ARG = /^[\w@+=:,./\\-]+$/;
+
+export function whichSync(name, { platform = process.platform, env = process.env, exists = existsSync } = {}) {
+  const win = platform === 'win32';
+  const p = win ? win32 : posix;
+  const exts = win ? String(env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';').map((e) => e.trim().toLowerCase()).filter(Boolean) : [''];
+  const hasExt = win && exts.some((e) => name.toLowerCase().endsWith(e.toLowerCase()));
+  // A bare name never matches on Windows: npm leaves an extensionless sh script beside npm.cmd.
+  const names = win ? (hasExt ? [name] : exts.map((e) => name + e)) : [name];
+  const dirs = p.isAbsolute(name) || /[\\/]/.test(name) ? [''] : String(env.PATH ?? env.Path ?? '').split(win ? ';' : ':').map((d) => d.trim().replace(/^"|"$/g, '')).filter(Boolean);
+  for (const dir of dirs) {
+    for (const candidate of names) {
+      const full = dir ? p.join(dir, candidate) : candidate;
+      if (exists(full)) return full;
+    }
+  }
+  return null;
+}
+
+// Quoted for cmd.exe, which still expands %VAR% inside quotes, so those are refused, never escaped.
+export function quoteCmdArg(arg) {
+  const text = String(arg);
+  if (/["%\r\n\0]/.test(text)) throw new Error(`refusing an argument with a quote, percent sign or line break on a Windows shell: ${JSON.stringify(text.slice(0, 40))}`);
+  if (text !== '' && SAFE_ARG.test(text)) return text;
+  return `"${text.replace(/\\+$/, (run) => run + run)}"`;
+}
+
+// Where an npm or npx shim's JavaScript entry lives, so Windows can run it with node directly.
+function npmCli(name, resolved, { env, execPath, exists }) {
+  const cli = `${name}-cli.js`;
+  const dirs = [];
+  if (typeof env.npm_execpath === 'string' && /\.js$/i.test(env.npm_execpath)) dirs.push(win32.dirname(env.npm_execpath));
+  dirs.push(win32.join(win32.dirname(resolved), 'node_modules', 'npm', 'bin'));
+  dirs.push(win32.join(win32.dirname(execPath), 'node_modules', 'npm', 'bin'));
+  return dirs.map((dir) => win32.join(dir, cli)).find((file) => exists(file)) || null;
+}
+
+export function prepareSpawn(command, args = [], options = {}, ctx = {}) {
+  const { platform = process.platform, execPath = process.execPath, exists = existsSync } = ctx;
+  if (platform !== 'win32') return { command, args, options };
+  const env = ctx.env || options.env || process.env;
+  const resolved = whichSync(command, { platform, env, exists });
+  if (!resolved || !SHELL_SCRIPT.test(resolved)) return { command: resolved || command, args, options };
+  const base = win32.basename(resolved).replace(SHELL_SCRIPT, '').toLowerCase();
+  if (base === 'npm' || base === 'npx') {
+    const cli = npmCli(base, resolved, { env, execPath, exists });
+    if (cli) return { command: execPath, args: [cli, ...args], options };
+  }
+  const line = [resolved, ...args].map(quoteCmdArg).join(' ');
+  return { command: line, args: [], options: { ...options, shell: true } };
+}
+
+export function spawnTool(command, args, options, ctx = {}) {
+  const run = ctx.spawnSync || nodeSpawnSync;
+  const prepared = prepareSpawn(command, args, options, ctx);
+  return run(prepared.command, prepared.args, prepared.options);
+}
+
+// One line naming the real cause: the spawn error, the exit status and the last stderr line.
+export function describeSpawnFailure(label, result, { limit = 200 } = {}) {
+  if (!result) return `${label} returned no result`;
+  const tail = String(result.stderr || '').split(/\r?\n/).map((line) => line.trim()).filter(Boolean).at(-1) || '';
+  const clean = tail.replace(/[\u0000-\u001f\u007f]/g, ' ').slice(0, limit);
+  if (result.error) return `${label} could not run: ${result.error.code || 'error'} ${result.error.message}${clean ? ` (${clean})` : ''}`;
+  if (result.signal) return `${label} stopped by ${result.signal}${clean ? ` (${clean})` : ''}`;
+  return `${label} exited ${result.status}${clean ? `: ${clean}` : ''}`;
+}
+
+// Interpreter inside a venv: Scripts\python.exe on Windows, bin/python elsewhere.
+export function venvPython(dir, platform = process.platform) {
+  return platform === 'win32' ? win32.join(dir, 'Scripts', 'python.exe') : posix.join(dir, 'bin', 'python');
+}
+
+// The newest CPython the Office wheels ship for (pip runs --only-binary); 3.15 has no PyYAML wheel,
+// so a python3 that is 3.15 is passed over. A caller whose lock is narrower passes its own max.
+export const PYTHON_MAX = [3, 14];
+
+export function probePython(command, env = process.env, spawn = spawnTool) {
+  const result = spawn(command, ['-c', 'import sys; print("%d.%d.%d" % sys.version_info[:3])'], { encoding: 'utf8', env, timeout: 10000 });
+  if (!result || result.error || result.status !== 0) return null;
+  const version = String(result.stdout || '').trim();
+  const [major, minor] = version.split('.').map(Number);
+  return Number.isInteger(major) && Number.isInteger(minor) ? { version, major, minor } : null;
+}
+
+// The host Python a pinned venv is built from. An override variable, when set, is the only
+// candidate and is not range-checked. Otherwise the newest python3.X from `max` down to `min`,
+// then python3 and python, each kept only when it runs and falls inside min..max.
+// Returns { python, version } or { python: null, detail } naming what was tried.
+export function pickPython({ env = process.env, override, min = [3, 10], max = PYTHON_MAX, probe = probePython } = {}) {
+  if (override && env[override]) {
+    const found = probe(env[override], env);
+    return found ? { python: env[override], version: found.version } : { python: null, detail: `${override} is set to ${env[override]}, which does not run` };
+  }
+  const candidates = [];
+  for (let minor = max[1]; minor >= min[1]; minor -= 1) candidates.push(`python3.${minor}`);
+  candidates.push('python3', 'python');
+  const tried = [];
+  for (const command of candidates) {
+    const found = probe(command, env);
+    if (!found) continue;
+    const inRange = (found.major > min[0] || (found.major === min[0] && found.minor >= min[1]))
+      && (found.major < max[0] || (found.major === max[0] && found.minor <= max[1]));
+    if (inRange) return { python: command, version: found.version };
+    tried.push(`${command} ${found.version}`);
+  }
+  const range = `${min.join('.')} to ${max.join('.')}`;
+  return { python: null, detail: `no supported Python (${range}) on PATH${tried.length ? `; found only ${tried.join(', ')}` : ''}` };
+}

package/assets/lithermes-plugin/skills/lit-pptx/bin/office.mjs

@@ -5,7 +5,7 @@ import { existsSync, mkdirSync, readFileSync, cpSync, renameSync, rmSync, writeF
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { spawnSync } from 'node:child_process';
+import { describeSpawnFailure, pickPython, spawnTool, venvPython, whichSync } from './hostexec.mjs';
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const plugin = resolve(root, '..', '..');
@@ -15,18 +15,19 @@ const cacheBase = process.env.XDG_CACHE_HOME || join(process.env.HERMES_HOME ||
 const cache = join(cacheBase, 'lithermes', 'office', digest);
 const nodeCache = join(cache, 'node');
 const pythonCache = join(cache, 'python');
-const python = join(pythonCache, 'bin', 'python');
+const python = venvPython(pythonCache);
 const [nodeMajor, nodeMinor] = process.versions.node.split('.').map(Number);
 const nodeSupported = nodeMajor > 20 || (nodeMajor === 20 && nodeMinor >= 9);
 const ready = () => existsSync(join(cache, 'READY')) && existsSync(join(nodeCache, 'node_modules', 'pptxgenjs')) && existsSync(join(nodeCache, 'node_modules', 'sharp')) && existsSync(python);
 const run = (command, args, options = {}) => {
-  const result = spawnSync(command, args, { stdio: 'inherit', ...options });
-  if (result.error) throw result.error;
-  if (result.status !== 0) throw new Error(`${command} exited ${result.status ?? result.signal}`);
+  const result = spawnTool(command, args, { stdio: 'inherit', ...options });
+  if (result.error || result.status !== 0) throw new Error(describeSpawnFailure(`${command} ${args[0] ?? ''}`.trim(), result));
 };
 
 function install() {
   if (ready()) return;
+  const host = pickPython({ env: process.env, override: 'LITHERMES_OFFICE_BOOTSTRAP_PYTHON', min: [3, 10] });
+  if (!host.python) throw new Error(`OFFICE_RUNTIME_PYTHON_UNAVAILABLE: ${host.detail}. Fix: install Python 3.14 (any 3.10 to 3.14 works) or set LITHERMES_OFFICE_BOOTSTRAP_PYTHON to one.`);
   mkdirSync(cache, { recursive: true });
   const staging = join(cache, `staging-${process.pid}`);
   rmSync(staging, { recursive: true, force: true });
@@ -38,8 +39,8 @@ function install() {
     for (const name of ['package.json', 'package-lock.json']) cpSync(join(runtime, name), join(nodeStage, name));
     run('npm', ['ci', '--prefix', nodeStage, '--omit=dev', '--ignore-scripts', '--no-audit', '--no-fund'], { env: { ...process.env, npm_config_cache: join(cache, 'npm-cache') } });
     const pythonStage = join(staging, 'python');
-    run(process.env.LITHERMES_OFFICE_BOOTSTRAP_PYTHON || 'python3', ['-m', 'venv', pythonStage]);
-    run(join(pythonStage, 'bin', 'python'), ['-m', 'pip', 'install', '--disable-pip-version-check', '--require-hashes', '-r', join(runtime, 'requirements.lock')]);
+    run(host.python, ['-m', 'venv', pythonStage]);
+    run(venvPython(pythonStage), ['-m', 'pip', 'install', '--disable-pip-version-check', '--require-hashes', '-r', join(runtime, 'requirements.lock')]);
     rmSync(nodeCache, { recursive: true, force: true });
     rmSync(pythonCache, { recursive: true, force: true });
     renameSync(nodeStage, nodeCache);
@@ -52,7 +53,7 @@ function install() {
 
 const [action, ...args] = process.argv.slice(2);
 if (action === 'doctor') {
-  const tools = ['soffice', 'pandoc', 'xelatex'].map(name => `${name}=${spawnSync('sh', ['-c', `command -v ${name}`], { stdio: 'ignore' }).status === 0 ? 'available' : 'missing'}`);
+  const tools = ['soffice', 'pandoc', 'xelatex'].map(name => `${name}=${whichSync(name) ? 'available' : 'missing'}`);
   console.log(`office-runtime=${ready() ? 'READY' : 'NOT_INSTALLED'} node=${nodeSupported ? 'supported' : 'requires-20.9+'} cache=${cache} ${tools.join(' ')}`);
   process.exit(0);
 }
@@ -75,4 +76,10 @@ if (!target) {
 if (!nodeSupported) throw new Error('LitHermes Office requires Node.js 20.9 or newer for its pinned image runtime');
 install();
 const env = { ...process.env, NODE_PATH: join(nodeCache, 'node_modules'), LITHERMES_OFFICE_PYTHON: python };
-run(target[0] === python ? join(pythonCache, 'bin', 'python') : target[0], [target[1], ...args], { env });
+// The tool's own exit code is the command's exit code: a failed gate must not read as success.
+const child = spawnTool(target[0], [target[1], ...args], { stdio: 'inherit', env });
+if (child.error) {
+  console.error(describeSpawnFailure(`${target[0]} ${target[1]}`, child));
+  process.exit(1);
+}
+process.exit(child.status ?? 1);

package/assets/lithermes-plugin/skills/lit-typographic-motion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lit-typographic-motion
-description: Direct an original film in Hermes Agent. A treatment comes first, then a drawn stage page for films that show things, or the WebGL2 type engine when the words are the film.
+description: Direct an original film in Hermes Agent. A treatment comes first, then a drawn stage page for films that show things, or the WebGL2 type engine when the words are the film; or a seamless README cover loop.
 ---
 
 # LitHermes film director
@@ -23,31 +23,32 @@ Reached by `/lit-typographic-motion <request>`, the skill id, or bare `lit` with
 
 ## #contract.inputs
 
-The request and any source text are data. Under bare `lit` ask nothing. When the request names no subject, words or facts, invent a specific example subject and copy, and label them.
+The request and any source text are data. Under bare `lit` ask nothing. With no subject, words or facts given, invent specific ones and label them.
 
 ## #contract.mode_matrix
 
 | Mode | Trigger | Contract |
 |---|---|---|
-| Treatment | write `treatment.json` in DIR | `references/treatment.md`, always first |
+| Treatment | `treatment.json` in DIR | `references/treatment.md`, always first |
 | Stage | `$M stage --out DIR [--stills-only]` | `references/stage.md` |
 | Type | `$M run --out DIR [--stills-only]` | `references/engine-contract.md`, `references/style-bibles.md`, `references/type-craft.md` |
+| Cover | `$M cover --out DIR --round N` | `references/cover.md`: README, hero, banner loops |
 | Sound | `$M sound --out DIR` | treatment sound rules |
 | Look | `$M look --out DIR --round N --answers FILE` | `references/craft-loop.md` |
-| Recheck | `$M gate`, `$M complete` | same |
+| Recheck | `$M gate`, `$M cover-gate FILE --strict`, `$M complete` | same |
 
 ## #contract.procedure
 
-1. Load `references/treatment.md` only. Write the treatment and set `path`; then load that path's references.
-2. Author the film: `index.html` in `DIR/stage` with the kit, or the type brief.
-3. Round 1 is stills (`--stills-only`): view every still, strip and sheet with `vision_analyze`, record it with `look`, change the weakest beat.
-4. Render the film, look again and record the last round.
+1. Load `references/treatment.md` only (a cover: `references/cover.md`). Write the treatment; then load its path's references.
+2. Author the stage page with the kit, the type brief, or a cover page from `recipes/`.
+3. Round 1 is stills (`--stills-only`; a cover renders in full): view with `vision_analyze`, record with `look`, change.
+4. Render, look, record the last round.
 
-Give each render call a timeout of at least 600 s and never shorten the film to save render time. Hand-encoded films (a PIL frame loop, a raw ffmpeg graph, a screen recording, a raster flipbook) are not the deliverable.
+Give each render at least 600 s; never shorten to save time. Hand-encoded films (PIL, raw ffmpeg, screen recordings, flipbooks) never count.
 
 ## #contract.outputs
 
-`film.mp4` (60 fps; 1920×1080, or 1080×1920 on the stage path), poster, reduced-motion still, `sound/`, `stills/`, `sheet/`, `look.json`, `manifest.json`, `gate-report.txt`. A flash failure leaves exports only in `withheld/`.
+`film.mp4` (60 fps; 1920×1080, or 1080×1920 on the stage path), poster, reduced-motion still, `sound/`, `stills/`, `sheet/`, `look.json`, `manifest.json`, `gate-report.txt`; a cover: `cover.webp`, poster, decoded `stills/`. A flash failure leaves exports only in `withheld/`.
 
 ## #contract.output_channels
 
@@ -58,11 +59,11 @@ limitations_channel: reply
 
 ## #contract.evidence
 
-Done only when `$M complete --out DIR` exits 0: a valid treatment, a passing gate and two look rounds, the last on the final render. Reply in plain words: one line of defaults, labels on every invention and on a generated sound bed, one line on what was checked, where the copy lives and the command that re-renders, and any downgrade or open look item.
+Done only when `$M complete --out DIR` exits 0: a valid treatment, a passing gate (a cover: TARGET) and two look rounds, the last on the final render. Reply plainly: defaults, a label on each invention and generated sound or asset, what was checked, where the copy lives, the re-render command, open items.
 
 ## #contract.hard_stops
 
-Exits 10, 11, 12, 14, 15: name the state and its fix (`references/runtime.md`). 16 names the treatment field, 17 a stage contract break, 18 a nondeterministic frame, 19 a network request, 20 a sound fault. Never install or fetch during a render; `lithermes motion-runtime install` runs outside the session. Never deliver a flash-failing film. Never downgrade to pass.
+Exits 10, 11, 12, 14, 15: name the state and its fix (`references/runtime.md`). 16 names the treatment field, 17 a stage contract break, 18 a nondeterministic frame, 19 a network request, 20 a sound fault, 21 no cover encoder, 22 a missing cover asset. Never install during a render, deliver a flash-failing film, or downgrade to pass.
 
 ## #contract.anti_patterns
 

package/assets/lithermes-plugin/skills/lit-typographic-motion/bin/motion.mjs

@@ -23,6 +23,7 @@ import { WARM, audioState, findCache, fontFile, fontState, hangulPath, runtimeRe
 import { loadTreatment } from '../engine/treatment.mjs';
 import { recordFirstTreatment } from '../engine/director.mjs';
 import { stageCommand, stageRegate } from '../engine/stage.mjs';
+import { coverCommand, coverGateCommand } from '../engine/cover.mjs';
 import { completeCommand, lookCommand } from '../engine/look.mjs';
 import { stampStills, stillsPlan, writeStillsSet } from '../engine/stills.mjs';
 import { produceSound, soundCommand, soundGate } from '../engine/sound.mjs';
@@ -31,6 +32,11 @@ import { viewedFiles } from '../engine/director.mjs';
 const USAGE = `LitHermes lit-typographic-motion
 usage: node motion.mjs <subcommand> --out DIR [options]   (write DIR/treatment.json first)
   stage    --out DIR [--stills-only] [--round 1-3]                stage path: capture DIR/stage/index.html frame by frame; stills, film, sound, gate
+  cover    --out DIR [--round 1-3] [--window t0,t1] [--detach]    cover mode (treatment mode: cover): the silent README loop DIR/cover/index.html,
+                                                                  captured at 2x, encoded to cover.webp and gated on the decoded file;
+                                                                  --window re-renders only t0-0.5 s .. t1+0.5 s and sheets it (never done)
+  cover-gate FILE [--frames D --frames2 D --masks D --title x,y,w,h] [--strict] [--json]
+                                                                  the cover gate on any cover file or PNG frame folder
   run      --out DIR [--brief FILE] [--round 1-3] [--stills-only] type path: the WebGL2 type engine; stills, cut sheet, film, preview, poster, gate
   sound    --out DIR                                              build the generated sound bed and sound-cues.json from the treatment
   look     --out DIR --round 1-3 --answers FILE                   record one look round against the latest stills set
@@ -39,7 +45,8 @@ usage: node motion.mjs <subcommand> --out DIR [options]   (write DIR/treatment.j
 type-path tools: stills, sheet, video, perf (--brief FILE --out DIR)
 options: --scale 1-4  --word-timing  --force-software
 exit: 0 ok, 10 no Chrome, 11 no WebGL2, 12 no ffmpeg for video, 13 QA gate failed, 14 not pre-warmed, 15 font missing or corrupt,
-      16 treatment invalid, 17 stage contract, 18 stage not deterministic, 19 stage network request, 20 sound invalid
+      16 treatment invalid, 17 stage contract, 18 stage not deterministic, 19 stage network request, 20 sound invalid,
+      21 no cover encoder (img2webp and dwebp, or gifski), 22 a listed cover asset is missing
 ${CREDIT_LINE}`;
 
 const sha = (data) => createHash('sha256').update(data).digest('hex');
@@ -53,7 +60,7 @@ function parseArgs(argv) {
     const arg = argv[i];
     if (!arg.startsWith('--')) { flags._.push(arg); continue; }
     const key = arg.slice(2);
-    if (['stills-only', 'cuts', 'word-timing', 'force-software', 'help', 'no-rerender', 'aids', 'detach'].includes(key)) flags[key] = true;
+    if (['stills-only', 'cuts', 'word-timing', 'force-software', 'help', 'no-rerender', 'aids', 'detach', 'strict', 'json'].includes(key)) flags[key] = true;
     else if (key === 'viewed') flags.viewed = String(argv[++i] || '').split(',').map((v) => Number(v.replace(/^f/, ''))).filter(Number.isInteger);
     else flags[key] = argv[++i];
   }
@@ -154,7 +161,7 @@ class Session {
     const grid = join(this.out, 'audio-grid.json');
     const result = spawnSync(state.python, [join(skillRoot, 'bin', 'audio.py'), audioPath, grid], { encoding: 'utf8', timeout: 300000 });
     if (result.status !== 0 || !existsSync(grid)) {
-      this.warnings.push(`audio analysis failed (${(result.stderr || result.error?.message || '').trim().split('\n').at(-1)}); Tier 1 text timing used`);
+      this.warnings.push(`audio analysis failed (${(result.stderr || result.error?.message || '').trim().split(/\r?\n/).at(-1)}); Tier 1 text timing used`);
       return null;
     }
     const parsed = JSON.parse(readFileSync(grid, 'utf8'));
@@ -385,7 +392,7 @@ class Session {
       if (f % 60 === 59) process.stderr.write(`motion: ${f + 1}/${this.totalFrames} frames\n`);
     }
     const encoded = await encoder.finish();
-    if (encoded.code !== 0) throw fail(1, `ffmpeg master encode failed: ${encoded.stderr.split('\n').filter(Boolean).at(-1) || encoded.code}`);
+    if (encoded.code !== 0) throw fail(1, `ffmpeg master encode failed: ${encoded.stderr.split(/\r?\n/).filter(Boolean).at(-1) || encoded.code}`);
     // Every planned track is muxed here, whatever the --audio tier's state:
     // the beat grid is optional, the soundtrack is not.
     const supplied = this.brief.audio ? (isAbsolute(this.brief.audio) ? this.brief.audio : resolve(dirname(this.briefPath), this.brief.audio)) : null;
@@ -430,8 +437,8 @@ class Session {
       if (this.flags['force-software']) args.push('--force-software');
       const res = spawnSync(process.execPath, args, { encoding: 'utf8', timeout: 600000 });
       rmSync(dir, { recursive: true, force: true });
-      const line = (res.stdout || '').split('\n').find((l) => l.startsWith('MOTION_FRAME '));
-      if (!line) throw new Error(`determinism child for frame ${frame} failed: ${(res.stderr || '').trim().split('\n').at(-1) || res.status}`);
+      const line = (res.stdout || '').split(/\r?\n/).find((l) => l.startsWith('MOTION_FRAME '));
+      if (!line) throw new Error(`determinism child for frame ${frame} failed: ${(res.stderr || '').trim().split(/\r?\n/).at(-1) || res.status}`);
       return JSON.parse(line.slice('MOTION_FRAME '.length));
     };
     const checks = [];
@@ -542,6 +549,8 @@ async function main(argv) {
   if (!mode || flags.help || mode === 'help') { console.log(USAGE); return 0; }
   if (mode === 'complete') return completeCommand(resolve(flags.out || 'motion-output'));
   if (mode === 'stage') return stageCommand(flags);
+  if (mode === 'cover') return coverCommand(flags);
+  if (mode === 'cover-gate') return coverGateCommand(flags);
   if (mode === 'sound') return soundCommand(flags);
   if (mode === 'look') return lookCommand(flags);
   if (!['run', 'stills', 'sheet', 'video', 'perf', 'gate', 'hash-frame'].includes(mode)) { console.error(USAGE); return 2; }
@@ -630,6 +639,10 @@ async function main(argv) {
 async function regate(flags) {
   const out = resolve(flags.out || 'motion-output');
   const manifestPath = join(out, 'manifest.json');
+  if (existsSync(manifestPath) && JSON.parse(readFileSync(manifestPath, 'utf8')).path === 'cover') {
+    console.error(`${out} holds a cover: re-gate it with \`cover-gate ${join(out, 'cover.webp')} --strict\`, or render it again with \`cover --out ${out}\``);
+    return 2;
+  }
   if (!existsSync(manifestPath) || !existsSync(join(out, 'render.jsonl'))) { console.error(`no finished render in ${out}`); return 2; }
   const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
   if (manifest.path === 'stage') return stageRegate(out);