ffmpeg-skill 3.6.3 → 3.6.5

package/README.md

@@ -676,6 +676,8 @@ CI (`.github/workflows/ci.yml`) runs on every pull request and on pushes to `mai
 
 **Releasing** is fully automated end to end, including the version number itself — a PR doesn't need to touch `package.json`, `docs/contract.md`, or `CHANGELOG.md` at all. Once a PR merges to `main`, `.github/workflows/release.yml` takes it from there: if nobody bumped the version by hand, it resolves the next version ([.github/scripts/resolve_version.py](.github/scripts/resolve_version.py)) from the labels on every PR merged since the last tag (`minor`/`feature`/`enhancement` → minor, `fix`/`bug`/`patch` → patch, an unlabeled PR defaults to `patch`; a PR whose only labels are `chore`, `ci`, `docs` or `dependencies` is not releasable, so a merge that changes no shipped file releases nothing). Most PRs don't need a label added by hand: `release-drafter.yml`'s `autolabel` job applies one automatically from the PR's title/changed files (`Fix ...` → `fix`, `Add ...`/`feat ...` → `feature`, `docs`/`.md`/`.github/`/`build(deps)` changes → `chore`) as soon as it's opened — add a label yourself only to override that. **A major version is never chosen automatically**: no label rule produces `major`, and the workflow refuses to auto-bump across a major boundary even if someone applies that label — a real major release is a deliberate `package.json` bump in a PR, which the manual path below already handles. It bumps `package.json`, `.claude-plugin/plugin.json`, `docs/contract.md` and `docs/roadmap.md`'s released-version sentence, writes a `CHANGELOG.md` section listing those PRs (and any issues they closed), and pushes that commit to `main` itself. Either way — auto-bumped or hand-bumped in the PR — it then creates the `vX.Y.Z` tag, publishes a GitHub Release with notes extracted from `CHANGELOG.md`'s matching section, and publishes the package to npm. A PR that still wants to write its own version bump and `CHANGELOG.md` prose (e.g. to explain the "why" of a release by hand) can — the automation only fills in when nobody made that call already. A push to `main` with nothing new to release is a no-op. npm publishing needs an `NPM_TOKEN` repo secret (an npm access token with publish rights on this package) — without it the tag and GitHub Release still happen, only the npm step is skipped. A repo that depends on this one (an editing skill, an agent) should pin an `ffmpeg-skill` version by tag or npm version, not by tracking `main` — a merged-but-not-yet-released commit on `main` can be ahead of the last published npm version for the few minutes between merge and this workflow completing.
 
+**A version that was tagged but never reached npm** (the npm step failed; a re-run of that release sees the tag and skips the publish) is finished by dispatching the same workflow on its tag: `gh workflow run release.yml --ref vX.Y.Z -f version=X.Y.Z`. That runs only the workflow's `recover` job. It refuses a version that is not `X.Y.Z`, has no tag, or that npm already has, and a run whose commit is not the tagged one: the npm provenance attestation names the run's commit, so it must be the commit the package is built from. It publishes with `--provenance` under the `latest` dist-tag when the version is above every stable (non-prerelease) version npm has, and under `backport` otherwise, so `latest` never moves back. Then it publishes the `plugin` branch when no commit there is for this version and the branch's tip is older, and the MCP Registry entry when the registry does not list the version (never for a `backport`). The GitHub Release is left as it is. A tag cut before the job was added (#448; every tag up to v3.6.3) has no `recover` job at its commit and cannot be recovered this way.
+
 Contributing a change: see [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## Docs

package/docs/contract.md

@@ -21,7 +21,7 @@ The contract is derived from the code that runs, not maintained beside it:
 | Field | Meaning | Changes when |
 |---|---|---|
 | `contract_version` | shape of this document (`2.0`) | a key is renamed, removed or changes meaning |
-| `skill.version` | the npm / package.json version (`3.6.3`) | any release |
+| `skill.version` | the npm / package.json version (`3.6.5`) | any release |
 
 A release that adds a tool or a flag keeps `contract_version`; a breaking change to the
 ToolSpec shape bumps it. Consumers pin on `contract_version` and read `skill.version`
@@ -149,7 +149,7 @@ JSON would have been rewritten for that. The flat keys, typed per tool in `outpu
   "deprecated": [],
   "removed": [{"what": "...", "since": "1.10.0", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"},
               {"what": "running on FFmpeg 5.x (the requirements.ffmpeg floor)", "since": "2.14.0", "replacement": "FFmpeg 6.1 or later; ...", "removed_in": "3.0.0", "where": "behaviour"}],
-  "skill": {"id": "ffmpeg-skill", "version": "3.6.3", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "3.6.5", "execution_mode": "local", "kind": "execution",
             "entrypoints": {"cli": "...", "mcp": "...", "contract": "...", "doctor": "..."},
             "not_provided": ["AI reasoning", "decisions", "production plans", "project IR", "approvals", "network access", "transcription engine"]},
   "requirements": {"python": ">=3.10 (standard library only)", "ffmpeg": ">=6.1", "ffprobe": ">=6.1"},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "3.6.3",
+  "version": "3.6.5",
   "mcpName": "io.github.kajisho5/ffmpeg-skill",
   "description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 42 FFmpeg tools with a machine-readable contract, contract-derived MCP server, FFmpeg capability detection, probe-first / verify-last workflow. Cut, join, silence removal, fit, captions and karaoke, overlays, motion graphics, HDR to SDR, LUTs, audio clean-up and typed dynamics, sync with drift correction, multicam, loudness, delivery checks, project rendering, batch. No API keys, no cloud, no dependencies.",
   "keywords": [

package/scripts/_common/asr.py

@@ -9,7 +9,7 @@ why it is its own file.
 """
 from __future__ import annotations
 
-import json
+import math
 import os
 import re
 import unicodedata
@@ -18,7 +18,7 @@ from typing import Any, Dict, List, NamedTuple, Optional, Tuple
 
 from _common.decision import _unspaced_script, fmt_srt_time, parse_time
 from _common.emit import die, info, warn
-from _common.runner import read_text_or_die
+from _common.runner import parse_json, read_json, read_text_or_die
 
 # The engines this skill knows how to drive, and how to install each -- one string, so every
 # tool that needs a transcript refuses in the same words. The two Parakeet engines are
@@ -85,26 +85,60 @@ class Transcription:
                 f"facts={self.facts!r}, notes={self.notes!r})")
 
 
+# A line that starts a cue even with no blank line before it: a clock time, "-->", a clock time,
+# then nothing or whitespace (ffmpeg's position fields, X1:.. Y1:..). ffmpeg's SRT demuxer starts
+# an event at every such line; the first line of a block holding "-->" is a timing line whatever
+# its shape.
+_SRT_CUE_START = re.compile(r"^\s*\d+:\d+[\d:.,]*\s*-->\s*\d+:\d+[\d:.,]*(\s|$)")
+
+
+def srt_blocks(text: str) -> List[Tuple[str, List[str]]]:
+    """(timing line, text lines) of every cue in SRT text whose line ends are already `\\n`.
+
+    A blank (or whitespace-only) line ends a cue, and the first line holding "-->" in a run of
+    lines is its timing line; the lines before it (the index) are not text. Inside a run, a later
+    line shaped like a timing line (_SRT_CUE_START) starts the next cue, and a bare number just
+    before it is that cue's index, so an SRT written without blank lines between cues reads as
+    ffmpeg reads it rather than as one cue. A later line that merely contains "-->" is text."""
+    out: List[Tuple[str, List[str]]] = []
+    for run in re.split(r"\n\s*\n", text):
+        lines = [ln for ln in run.split("\n") if ln.strip()]
+        first = next((i for i, ln in enumerate(lines) if "-->" in ln), None)
+        if first is None:
+            continue
+        timing, body = lines[first], []
+        for ln in lines[first + 1:]:
+            if _SRT_CUE_START.match(ln):
+                if body and body[-1].strip().isdigit():
+                    body.pop()
+                out.append((timing, body))
+                timing, body = ln, []
+            else:
+                body.append(ln)
+        out.append((timing, body))
+    return out
+
+
+def srt_timing_times(line: str) -> Tuple[str, str]:
+    """The start and end tokens of an SRT timing line: what is before the first "-->", and the
+    first word after it. ffmpeg reads the two times and ignores the rest (position fields
+    `X1:.. X2:.. Y1:.. Y2:..`, or a stray second "-->")."""
+    a, _sep, b = line.partition("-->")
+    words = b.split()
+    return a.strip(), words[0] if words else ""
+
+
 def parse_srt(path: str) -> List[Tuple[float, float, str]]:
     cues: List[Tuple[float, float, str]] = []
-    block: List[str] = []
-    content = read_text_or_die(path, "--srt").lstrip("\ufeff").replace("\r\n", "\n") + "\n\n"
-    for line in content.split("\n"):
-        if line.strip():
-            block.append(line)
-            continue
-        if block:
-            times = next((b for b in block if "-->" in b), None)
-            if times:
-                a, b = times.split("-->")
-                text = "\n".join(block[block.index(times) + 1:]).strip()
-                try:
-                    cues.append((parse_time(a), parse_time(b), text))
-                except ValueError as e:  # includes MissingFpsError: SRT timings are hh:mm:ss,ms, never frames
-                    die(f"{path}: cannot read the timing line {times.strip()!r}: {e}")
-            block = []
+    for times, body in srt_blocks(read_text_or_die(path, "--srt")):
+        a, b = srt_timing_times(times)
+        text = "\n".join(body).strip()
+        try:
+            cues.append((parse_time(a), parse_time(b), text))
+        except ValueError as e:  # includes MissingFpsError: SRT timings are hh:mm:ss,ms, never frames
+            die(f"{path}: cannot read the timing line {times.strip()!r}: {e}", kind="input")
     if not cues:
-        die(f"no cues found in {path}")
+        die(f"no cues found in {path}", kind="input")
     return cues
 
 
@@ -204,8 +238,9 @@ def write_srt(cues: List[Tuple[float, float, str]], path: str) -> None:
             # line with two adjacent pipes ("a||b") becomes "a\n\nb" -- and writing that blank line
             # raw would split one cue into two malformed half-blocks (the second missing its own
             # index/timecode). Collapse any run of blank lines within the cue text to a single
-            # newline so the cue's own text can never fake the format's block boundary.
-            t = re.sub(r"\n{2,}", "\n", t).strip("\n")
+            # newline so the cue's own text can never fake the format's block boundary. A line of
+            # only spaces or tabs is blank to every SRT reader too, so it goes the same way.
+            t = "\n".join(ln for ln in t.split("\n") if ln.strip())
             fh.write(f"{i}\n{fmt_srt_time(s)} --> {fmt_srt_time(e)}\n{t}\n\n")
     # under batch.py: this SRT as written is the run's own (an edit made after it is not)
     from _common.runner import report_committed
@@ -476,20 +511,24 @@ def whisper_word_timings(srt_path: Optional[str]) -> List[Tuple[float, float, st
         if not os.path.exists(cand):
             continue
         try:
-            data = json.loads(Path(cand).read_text(encoding="utf-8"))
+            data = read_json(cand)
         except (OSError, ValueError):
             continue
+        # the shape is not checked first: a segment that is a string or a list, or "segments" that
+        # is a number, is simply no words, as _dicts() reads every engine's JSON
         raw = []
         if isinstance(data, dict):
-            raw = list(data.get("words") or [])
-            for seg in data.get("segments") or []:
-                raw.extend((seg or {}).get("words") or [])
+            raw = _dicts(data.get("words"))
+            for seg in _dicts(data.get("segments")):
+                raw.extend(_dicts(seg.get("words")))
         words = []
         for w in raw:
             try:
                 text = str(w.get("word") or w.get("text") or "").strip()
-                if text:
-                    words.append((float(w["start"]), float(w["end"]), text))
+                start, end = float(w["start"]), float(w["end"])
+                # NaN / Infinity are valid to json.loads and place no word anywhere
+                if text and math.isfinite(start) and math.isfinite(end):
+                    words.append((start, end, text))
             except (AttributeError, KeyError, TypeError, ValueError):
                 continue
         if words:
@@ -519,12 +558,12 @@ def _words_from_whisper_cpp_json(path: str) -> "List[Dict[str, Any]]":
     boundaries). A token that is part of a character (U+FFFD) is still glued.
     """
     try:
-        doc = json.loads(Path(path).read_text(encoding="utf-8"))
+        doc = read_json(path)
     except (OSError, ValueError):
         return []
     out: "List[Dict[str, Any]]" = []
-    for seg in (doc.get("transcription") or []):
-        for tok in (seg.get("tokens") or []):
+    for seg in _dicts(doc.get("transcription")) if isinstance(doc, dict) else []:
+        for tok in _dicts(seg.get("tokens")):
             text = str(tok.get("text") or "")
             if not text.strip() or text.strip().startswith("[_"):
                 continue
@@ -552,7 +591,7 @@ def _whisper_json_language(path: str) -> Optional[str]:
     """The language a Whisper engine's JSON says it decoded: whisper.cpp's `result.language`, or
     openai-whisper's top-level `language`. None when the file has neither."""
     try:
-        doc = json.loads(Path(path).read_text(encoding="utf-8")) or {}
+        doc = read_json(path) or {}
         lang = str(((doc.get("result") or {}).get("language")) or doc.get("language") or "").strip().lower()
     except (OSError, ValueError, AttributeError):
         return None
@@ -568,12 +607,12 @@ def _heard_language(heard: list) -> Optional[str]:
 def _words_from_openai_whisper_json(path: str) -> "List[Dict[str, Any]]":
     """openai-whisper --word_timestamps True --output_format json: segments[].words[]."""
     try:
-        doc = json.loads(Path(path).read_text(encoding="utf-8"))
+        doc = read_json(path)
     except (OSError, ValueError):
         return []
     out: "List[Dict[str, Any]]" = []
-    for seg in (doc.get("segments") or []):
-        for w in (seg.get("words") or []):
+    for seg in _dicts(doc.get("segments")) if isinstance(doc, dict) else []:
+        for w in _dicts(seg.get("words")):
             try:
                 out.append({"word": str(w.get("word") or w.get("text") or "").strip(),
                             "start": float(w["start"]), "end": float(w["end"])})
@@ -592,7 +631,7 @@ def _words_from_parakeet_mlx_json(path: str) -> "List[Dict[str, Any]]":
     after it starts a word too (" m" "is" "ter" " " "Q" "u" "il" "ter" -> "mister", "Quilter").
     """
     try:
-        doc = json.loads(Path(path).read_text(encoding="utf-8"))
+        doc = read_json(path)
     except (OSError, ValueError):
         return []
     out: "List[Dict[str, Any]]" = []
@@ -619,7 +658,7 @@ def _words_from_parakeet_mlx_json(path: str) -> "List[Dict[str, Any]]":
 def _cues_from_parakeet_mlx_json(path: str) -> List[Tuple[float, float, str]]:
     """parakeet-mlx's own sentence segmentation, as cues."""
     try:
-        doc = json.loads(Path(path).read_text(encoding="utf-8"))
+        doc = read_json(path)
     except (OSError, ValueError):
         return []
     cues: List[Tuple[float, float, str]] = []
@@ -642,7 +681,7 @@ def _dicts(value: Any) -> "List[Dict[str, Any]]":
 def _words_from_parakeet_cpp_json(text: str) -> "List[Dict[str, Any]]":
     """parakeet-cli transcribe --json: {"words": [{"w", "start", "end", "conf"}]}, times in seconds."""
     try:
-        doc = json.loads(text)
+        doc = parse_json(text)
     except ValueError:
         return []
     out: "List[Dict[str, Any]]" = []
@@ -978,7 +1017,7 @@ def _heard_nothing(text: str, key: str) -> bool:
     Anything else that yields no words -- not JSON, the wrong shape, entries that do not parse --
     is output that could not be read, not a finding that nobody spoke."""
     try:
-        doc = json.loads(text)
+        doc = parse_json(text)
     except ValueError:
         return False
     return isinstance(doc, dict) and doc.get(key) == []
@@ -990,7 +1029,7 @@ def _whisper_heard_nothing(path: str, key: str) -> bool:
     no speech (#414). A document with text and no word timings is a build without them, not
     silence, and stays the "no word-level timings" refusal."""
     try:
-        doc = json.loads(Path(path).read_text(encoding="utf-8"))
+        doc = read_json(path)
     except (OSError, ValueError):
         return False
     if not isinstance(doc, dict) or not isinstance(doc.get(key), list):

package/scripts/_common/decision.py

@@ -6,7 +6,6 @@ and encoder-selection rules testable on their own.
 """
 from __future__ import annotations
 
-import json
 import math
 import os
 import re
@@ -17,6 +16,7 @@ from typing import Any, Dict, List, Optional, Sequence, Tuple
 from _common.color import (as_limited, bt709_label_filter, bt709_matrix_args, bt709_matrix_filter, bt709_tag_args, drawn_stream_format,
                            is_neutral_color, limited_range_filter, rgb_island, rgb_to_bt709_filter, _sdr_bt709)
 from _common.emit import die, record_fallback, refuse, warn
+from _common.runner import read_json
 from _common.runner import CODECS, STATE, ffmpeg_encoders, ffmpeg_list_error, ffmpeg_version, hw_platform_reason
 
 
@@ -1025,13 +1025,29 @@ def load_brand(path: Optional[str]) -> Dict[str, Any]:
     if not path:
         return brand
     if not os.path.exists(path):
-        die(f"brand file not found: {path}")
+        die(f"brand file not found: {path}", kind="input")
     try:
-        data = json.loads(Path(path).read_text(encoding="utf-8"))
-    except ValueError as exc:
-        die(f"brand file is not valid JSON: {exc}")
+        data = read_json(path)
+    except OSError as exc:
+        die(f"brand file {path} cannot be read: {exc.strerror or exc}", kind="input")
+    except ValueError as exc:  # malformed, not UTF-8, or nested too deep (read_json)
+        die(f"brand file is not valid JSON: {exc}", kind="input")
+    if not isinstance(data, dict):
+        die(f"brand file {path} must be a JSON object {{...}}, got {type(data).__name__}", kind="input")
+    # the shapes the readers below and brand_caption_style() walk: a block that is not an object,
+    # and a path that is not a string, were a traceback there
+    for key, value in (*data.items(), ("styles.caption", (data.get("styles") or {}).get("caption")
+                                       if isinstance(data.get("styles"), dict) else None)):
+        if value is None:
+            continue
+        if (isinstance(BRAND_DEFAULTS.get(key), dict) or key == "styles.caption") and not isinstance(value, dict):
+            die(f'brand file {path}: "{key}" must be an object {{...}}, got {type(value).__name__}', kind="input")
+        if key in ("logo", "font_file", "font") and not isinstance(value, str):
+            die(f'brand file {path}: "{key}" must be a string, got {type(value).__name__}', kind="input")
     base = Path(path).resolve().parent
     for k, v in data.items():
+        if v is None and isinstance(brand.get(k), dict):
+            continue  # a null block keeps its defaults: readers walk it as an object (#483 review)
         if isinstance(v, dict) and isinstance(brand.get(k), dict):
             brand[k].update(v)
         else:

package/scripts/_common/runner.py

@@ -10,6 +10,7 @@ import json
 import os
 import platform
 import argparse
+import contextlib
 import re
 import shutil
 import subprocess
@@ -329,7 +330,7 @@ class Context:
     makes it obvious what run()/emit() depend on and lets tests reset it with ``STATE.reset()``.
     """
 
-    __slots__ = ("dry_run", "json", "json_brief", "progress", "fast", "duration_hint", "commands", "timeout", "overwrite", "written", "preexisting", "plan", "plan_written", "plan_inputs", "codec", "alpha_line",
+    __slots__ = ("dry_run", "json", "json_brief", "progress", "fast", "duration_hint", "commands", "timeout", "overwrite", "written", "preexisting", "checked", "plan", "plan_written", "plan_inputs", "codec", "alpha_line",
                  "hw", "hw_source", "hw_notes", "hw_swaps", "hw_fallback", "hw_env_ignored", "hw_stages", "hw_auto",
                  "notes", "warnings", "fallbacks", "skipped", "audit_log", "stage_verification", "first_input", "audio_inputs", "video_inputs",
                  "source_timecode", "smpte_hint", "delivered", "expected_timecode")
@@ -356,6 +357,7 @@ class Context:
         self.overwrite = False                       # --overwrite: an existing output may be replaced
         self.written: set = set()                    # output paths this process has written itself
         self.preexisting: dict = {}                  # output path -> (size, mtime_ns) of a file that was there before we ran
+        self.checked: dict = {}                      # real output path -> owned_identity() at its output check (None: absent), or as this run left it; refuse_changed_output() compares it at the replace
         self.plan: Optional[str] = None              # --plan FILE: write the dry-run as a plan document (implies --dry-run)
         self.plan_written = False                    # write_plan() ran (emit or the exit hook), so the hook does not write twice
         self.plan_inputs: List[str] = []             # side inputs (srt/ass/lut/font files) a tool named through escape_filter_path
@@ -1226,6 +1228,9 @@ def refuse_existing_outputs(paths: Sequence[str]) -> None:
             real = os.path.realpath(output)
         except OSError:
             continue
+        # what the decision below is about: compared again where the file is replaced
+        # (refuse_changed_output), so one put there during the run is not replaced unasked
+        _record_checked(output, _checked_state(output) if exists else None)
         if not exists or real in STATE.written:
             continue
         size = mtime_ns = None
@@ -1259,11 +1264,163 @@ def _remember_output(cmd: Sequence[str]) -> None:
     output = cmd[-1]
     if output == "-" or output.startswith("pipe:") or output.startswith("-"):
         return
+    _remember_identity(output)
+    report_committed(output)
+
+
+def _checked_key(path: str) -> str:
+    """The place a check is about: `path`'s directory resolved, its last component as named, so a
+    symlink created at an absent target since the check is still that target (#480 review)."""
+    full = os.path.abspath(path)
+    return os.path.join(os.path.realpath(os.path.dirname(full)), os.path.basename(full))
+
+
+def _parent(path: str) -> str:
+    return os.path.realpath(os.path.dirname(os.path.abspath(path)))
+
+
+def _checked_state(path: str) -> "Optional[Tuple[Optional[Dict[str, int]], bool]]":
+    """What is at `path` now: (owned_identity, is a symlink), or None when nothing is there."""
+    if not os.path.lexists(path):
+        return None
+    return (owned_identity(path), os.path.islink(path))
+
+
+def _record_checked(path: str, state: Any) -> None:
+    """Record what a check (or this run's own write) found at `path`, with the directory the path
+    resolved to then, under the resolved place and under the path as named: a directory symlink
+    switched since is then found by the name and refused, not looked up as a place never checked."""
+    entry = (_parent(path), state)
+    key = _checked_key(path)
+    STATE.checked[key] = entry
+    STATE.checked[os.path.abspath(path)] = entry
+    # the same file reached by another spelling of its path (a write through the resolved name
+    # after a check through a link) is the same record: a later replace through either matches
+    # -- only a record made in the same directory: one whose link has been switched since keeps
+    # what it saw, so the replace through it is still refused
+    for named in [k for k in STATE.checked if k != key]:
+        try:
+            if _checked_key(named) == key and STATE.checked[named][0] == entry[0]:
+                STATE.checked[named] = entry
+        except OSError:
+            pass
+
+
+def _remember_identity(path: str) -> None:
+    """Count `path` as this run's own and record the identity this run left it with, which a
+    later replace of it compares (refuse_changed_output)."""
     try:
-        STATE.written.add(os.path.realpath(output))
+        real = os.path.realpath(path)
+        STATE.written.add(real)
     except OSError:
-        pass
-    report_committed(output)
+        return
+    _record_checked(path, _checked_state(path))
+
+
+def refuse_changed_output(path: str, cleanup: "Optional[Callable[[], None]]" = None) -> None:
+    """Refuse to replace `path` when it is no longer the file its output check decided about.
+
+    refuse_existing_outputs() decides before the encode whether an existing target may be
+    replaced (--overwrite, this run's own file, batch.py's own delivery) and records the
+    target's identity (owned_identity(), None when absent); _remember_identity() records it again
+    when this run writes it. Called under the output's lock just before the replace: a file
+    another process put there meanwhile -- a different file at an existing target, or one at a
+    target that was absent -- is refused (`kind: input`, `reason: output_exists`) and `cleanup`
+    removes the new output's temp, unless --overwrite gave consent to replace whatever is at the
+    path (as batch.py's deliver() does). A path with no recorded check is left alone."""
+    if STATE.overwrite or not path or path == "-" or path.startswith("pipe:") or path.startswith("-"):
+        return
+    try:
+        key, named, real = _checked_key(path), os.path.abspath(path), os.path.realpath(path)
+        # the name first: a resolved place another path also reached says nothing about this one
+        recorded = STATE.checked.get(named) or STATE.checked.get(key)
+        if recorded is None:
+            return
+        (parent_then, expected), parent_now, now = recorded, _parent(path), _checked_state(path)
+    except OSError:
+        return
+    if now == expected and parent_now == parent_then:
+        return
+    if cleanup:
+        cleanup()
+    if parent_now != parent_then:
+        why = (f"is now in another directory ({parent_now!r}, checked in {parent_then!r}): a directory "
+               "link on its path was changed during the run")
+    elif expected is None:
+        why = "did not exist when the run checked it and another process created it during the run"
+    elif now is None:
+        why = "was removed or replaced by something that is not a regular file during the run"
+    else:
+        why = "changed during the run (another process wrote or replaced it after the output check)"
+    refuse("input", "output_exists",
+           f"refusing to replace {path!r}: it {why}; the new output was not put there. Pass --overwrite to "
+           "replace it anyway, or choose another -o path",
+           hint="pass --overwrite, or choose another -o path",
+           outputs=[{"path": path, "resolved": real, "changed_during_run": True,
+                     "expected": expected, "found": now}])
+
+
+def _remove_quietly(path: Optional[str]) -> None:
+    if path:
+        try:
+            os.remove(path)
+        except OSError:
+            pass
+
+
+def replace_checked(tmp: str, final: str) -> None:
+    """os.replace(tmp, final) for a file a tool writes itself (a time map, a normalised export):
+    under `final`'s output lock, after refuse_changed_output(), which removes `tmp` when it
+    refuses."""
+    replace_checked_together([(tmp, final)])
+
+
+def replace_checked_together(pairs: "Sequence[Tuple[str, str]]") -> None:
+    """Replace each (tmp, final) only once every final has passed refuse_changed_output(), all
+    under their output locks: files that belong together (a fill and its key). A file already at a
+    final is moved aside first and put back if a later replace fails, so a failed pair leaves
+    what was there. Every tmp is removed on a refusal, a refused lock or a failed replace (#480
+    review)."""
+    def cleanup() -> None:
+        for tmp, _final in pairs:
+            _remove_quietly(tmp)
+    aside: List[Tuple[str, Optional[str]]] = []  # (final, where its earlier file went, or None)
+    try:
+        with contextlib.ExitStack() as stack:
+            for final in sorted({final for _tmp, final in pairs}):
+                stack.enter_context(_OutputLock(final))
+            for _tmp, final in pairs:
+                refuse_changed_output(final, cleanup)
+            try:
+                for tmp, final in pairs:
+                    kept = None
+                    if len(pairs) > 1 and os.path.lexists(final):
+                        d, base = os.path.split(final)
+                        stem, ext = os.path.splitext(base)
+                        kept = reserve_sibling(d, stem, ext, "keep")
+                        os.replace(final, kept)
+                    try:
+                        os.replace(tmp, final)
+                    except BaseException:
+                        if kept:
+                            os.replace(kept, final)
+                        raise
+                    aside.append((final, kept))  # replaced: undone below if a later one fails
+            except BaseException:
+                for final, kept in reversed(aside):
+                    if kept:
+                        try:
+                            os.replace(kept, final)
+                        except OSError:
+                            pass
+                    elif os.path.exists(final):
+                        _remove_quietly(final)
+                raise
+            for _final, kept in aside:
+                _remove_quietly(kept)
+    except BaseException:
+        cleanup()
+        raise
 
 
 # set only by batch.py for the steps it runs: the path of a JSON file {"replaceable": {real path:
@@ -1376,10 +1533,7 @@ def remember_written(*paths: Optional[str]) -> None:
     as replacing someone else's file (#415)."""
     for path in paths:
         if path and os.path.isfile(path):
-            try:
-                STATE.written.add(os.path.realpath(path))
-            except OSError:
-                pass
+            _remember_identity(path)
             report_committed(path)
 
 
@@ -1638,6 +1792,9 @@ def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True, ctx: "Op
     if is_ffmpeg:
         flush_drawtext_textfiles(cmd)
     with _OutputLock(cmd[-1] if is_ffmpeg else "-"):
+        if is_ffmpeg:
+            # a file put at the output since the check above is not ours to stage over
+            refuse_changed_output(cmd[-1])
         exec_cmd, final, tmp = _stage_existing_output(cmd) if is_ffmpeg else (list(cmd), None, None)
         def even_retry(proc: subprocess.CompletedProcess, ran: List[str]) -> "Tuple[subprocess.CompletedProcess, List[str]]":
             """An attempt that failed on odd dimensions, run again with an even scale: after the
@@ -1694,6 +1851,9 @@ def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True, ctx: "Op
             _fail(tried, proc.returncode, proc.stderr or "", ctx=ctx, retried=retried)
         if final and tmp:
             if proc.returncode == 0:
+                # still under the lock: the target the check let this run replace, not a file
+                # another process put there during the encode
+                refuse_changed_output(final, lambda: _cleanup_partial_output(exec_cmd))
                 try:
                     os.replace(tmp, final)
                 except OSError as e:
@@ -2104,6 +2264,9 @@ def place_output(src: str, dst: str, move: bool = False) -> None:
     d, base = os.path.split(dst)
     stem, ext = os.path.splitext(base)
     with _OutputLock(dst):
+        # under the lock: the target the check above decided about, not one put there since
+        # (`src` is the caller's to remove, as on every other refusal)
+        refuse_changed_output(dst)
         if move:
             try:
                 os.replace(src, dst)
@@ -2114,6 +2277,7 @@ def place_output(src: str, dst: str, move: bool = False) -> None:
         tmp = None
         try:
             tmp = copy_to_sibling(src, dst)
+            refuse_changed_output(dst, lambda: _remove_quietly(tmp))
             os.replace(tmp, dst)
         except OSError as e:
             if tmp:
@@ -2323,15 +2487,27 @@ def _read_ff_list(flag: str, pattern: str) -> set:
     return names
 
 
+_LINE_END = re.compile(r"\r*\n|\r")
+
+
+def normalize_text(text: str) -> str:
+    """A caller's text as every reader here takes it: a leading UTF-8 BOM dropped, and every line
+    ending `\\n`. `\\r\\r\\n` is one line end, as ffmpeg's text demuxers read it (a CRLF file passed
+    through a second CRLF conversion); a lone `\\r` (classic Mac) is one too. Only these: a line is
+    never split at U+2028, U+0085, \\v or \\f, which str.splitlines() also splits at."""
+    return _LINE_END.sub("\n", text.lstrip("\ufeff"))
+
+
 def read_text_or_die(path: str, flag: str) -> str:
     """Read a caller-supplied UTF-8 text file (a cue list, chapters, notes) or fail as kind input
-    with the flag named, instead of a FileNotFoundError / UnicodeDecodeError traceback."""
+    with the flag named, instead of a FileNotFoundError / UnicodeDecodeError traceback. The text
+    comes back through normalize_text(): no BOM, `\\n` line ends."""
     if os.path.isdir(path):
         # checked first: Windows raises PermissionError, not IsADirectoryError, for a directory
         die(f"{flag}: {path} is a directory, not a text file")
     try:
-        with open(path, "r", encoding="utf-8") as fh:
-            return fh.read()
+        with open(path, "r", encoding="utf-8", newline="") as fh:
+            return normalize_text(fh.read())
     except FileNotFoundError:
         die(f"{flag}: {path} does not exist")
     except IsADirectoryError:
@@ -2343,6 +2519,44 @@ def read_text_or_die(path: str, flag: str) -> str:
     return ""  # unreachable
 
 
+# Deeper than any project, recipe, brand, plan or transcript this skill reads (those are four or
+# five levels); a file nested past it is refused before code that walks it recursively
+# (copy.deepcopy, json.dumps) can raise RecursionError.
+JSON_MAX_DEPTH = 64
+
+
+class JsonTooDeep(ValueError):
+    """parse_json()'s refusal of a document nested past JSON_MAX_DEPTH: a ValueError, so callers
+    that catch ValueError refuse it as malformed JSON; one that falls back on a non-JSON file (a
+    media file) can tell this apart, since the file was JSON."""
+
+
+def parse_json(text: str) -> Any:
+    """json.loads for a caller's file: a BOM is dropped, and every way the text can fail to be a
+    document this skill can walk raises ValueError -- malformed JSON (json's own ValueError),
+    nesting too deep for the parser (RecursionError) or deeper than JSON_MAX_DEPTH. Callers that
+    already catch ValueError therefore refuse all three as they refuse malformed JSON."""
+    try:
+        data = json.loads(text.lstrip("\ufeff"))
+    except RecursionError:
+        raise JsonTooDeep(f"nested more than {JSON_MAX_DEPTH} levels deep") from None
+    stack = [(data, 1)]
+    while stack:
+        value, depth = stack.pop()
+        if isinstance(value, (dict, list)):
+            if depth > JSON_MAX_DEPTH:
+                raise JsonTooDeep(f"nested more than {JSON_MAX_DEPTH} levels deep")
+            stack.extend((v, depth + 1) for v in (value.values() if isinstance(value, dict) else value))
+    return data
+
+
+def read_json(path: "os.PathLike[str] | str") -> Any:
+    """parse_json() of a UTF-8 file. Raises OSError for a file that cannot be read and ValueError
+    (UnicodeDecodeError is one) for anything else, so `except (OSError, ValueError)` covers it."""
+    with open(path, "r", encoding="utf-8") as fh:
+        return parse_json(fh.read())
+
+
 # Deferred to the foot of the module on purpose. runner is the first module the package loads and
 # emit needs runner's Context/STATE/ERROR_CODE, so the two form a cycle that has to be cut
 # somewhere: by the time this line runs every name emit reads from runner above is defined, and

package/scripts/_contract.py

@@ -443,6 +443,8 @@ ERROR_REASONS = {
     "plan_unknown_tool": "render.py PLAN: the plan names no tool render.py can run; details: {plan, plan_sha256, checked_at, tool, audit_log}",
     "plan_cwd_missing": "render.py PLAN: the directory the plan was made in is gone; details: {plan, plan_sha256, checked_at, cwd, audit_log}",
     "plan_argv_invalid": "render.py PLAN: argv is not a list; details: {plan, plan_sha256, checked_at, argv_type, audit_log}",
+    "plan_field_invalid": "render.py PLAN: inputs, unbound_inputs, verify (objects), commands (strings) or cwd has the wrong JSON type; "
+                          "details: {plan, plan_sha256, checked_at, field, field_type, audit_log}",
     "decoder_missing": "color.py / graphics.py / overlay.py: a VP9 source or --video layer stored with an alpha layer, on a build with no libvpx-vp9 decoder (FFmpeg's own VP9 decoder drops the alpha), kind missing_tool; details: {name}",
     "encoder_missing": "--codec av1/prores: the build's encoder list was read and has no encoder for the codec (kind missing_tool; details: {codec, encoders}); or ffmpeg itself reported \"Unknown encoder\" for the encoder the command named (kind ffmpeg; details: {name}; the hint points at doctor)",
     "asr_engine_missing": "kind missing_tool: --transcribe (caption.py; silence.py with --filler or a sentence flag) found no local speech-to-text engine; the message lists the install lines; details: {}",

package/scripts/batch.py

@@ -33,7 +33,7 @@ from pathlib import Path
 from typing import Any, Dict, List, Optional
 
 from _common import STATE, add_common, apply_common, child_args, die, emit, info, run_tool, MEDIA_EXT as _MEDIA_EXT
-from _common.runner import (HW_FORCED_ENV, OWNED_ENV, _OutputLock, add_hw_orchestrator_args, copy_to_sibling, env_hw,
+from _common.runner import (HW_FORCED_ENV, OWNED_ENV, _OutputLock, add_hw_orchestrator_args, copy_to_sibling, env_hw, read_json,
                             owned_identity, stop_children)
 from _common.emit import absorb_stage_hw, audit, note, shown, steps_encoder_report, warn
 from _common.decision import rebase_project_paths
@@ -235,6 +235,39 @@ def intermediate_ext(src: Path) -> str:
     return src.suffix.lstrip(".") if src.suffix.lower() in (".wav", ".mp3", ".m4a", ".flac") else "mp4"
 
 
+# the recipe keys the run reads as a string: a path, a glob, a file-name part
+RECIPE_STRINGS = ("glob", "project", "output_dir", "suffix", "ext")
+
+
+def check_recipe_types(recipe: Dict[str, Any]) -> None:
+    """Refuse a recipe value of the wrong JSON type before anything runs (A18): a number where a
+    path or glob goes, an absolute glob (pathlib refuses it), a step that is not a list. Each was
+    a traceback, or a failure of every item naming the step's first character."""
+    for key in RECIPE_STRINGS:
+        value = recipe.get(key)
+        if value is not None and not isinstance(value, str):
+            die(f'recipe "{key}" must be a string, got {type(value).__name__} {value!r:.60}', kind="input")
+    glob = recipe.get("glob")
+    if glob and (os.path.isabs(glob) or glob.startswith(("/", "\\"))):
+        die(f'recipe "glob" {glob!r} is an absolute path: it matches names inside the batch folder, e.g. "*.mp4" '
+            'or "sub/*.mov"', kind="input")
+    key = recipe.get("clip_key")
+    try:
+        index = int(key) if key is not None and not isinstance(key, (bool, float)) else (0 if key is None else -1)
+    except (TypeError, ValueError):
+        index = -1
+    if index < 0:
+        die(f'recipe "clip_key" must be a clip index (0, 1, ...), got {key!r:.60}', kind="input")
+    steps = recipe.get("steps")
+    if steps is not None and not isinstance(steps, list):
+        die(f'recipe "steps" must be a list of steps, each ["script.py", args...], got {type(steps).__name__}',
+            kind="input")
+    for i, st in enumerate(steps or []):
+        if not isinstance(st, list) or not st:
+            die(f'recipe step {i} must be a list ["script.py", args...], got {type(st).__name__} {st!r:.60}',
+                kind="input")
+
+
 def step_writes(step: Any) -> bool:
     """Whether a recipe step writes a file: it names {out} (check.py and probe.py do not)."""
     return isinstance(step, list) and any("{out}" in str(a) for a in step[1:])
@@ -382,14 +415,14 @@ def process(src: Path, recipe: Dict[str, Any], outdir: Path, work: Path,
         return max(1.0, deadline - time.monotonic())
     if recipe.get("project"):
         try:
-            proj = json.loads(Path(str(recipe["project"])).read_text(encoding="utf-8"))
+            proj = read_json(str(recipe["project"]))  # too deep is a ValueError too (A20)
         except (OSError, ValueError) as e:
             raise ItemError({"step": None, "tool": "render.py", "kind": "input", "reason": "recipe_project_unreadable",
                              "message": f"recipe.project: {recipe['project']} could not be read as JSON: {e}"})
         if not isinstance(proj, dict):
             raise ItemError({"step": None, "tool": "render.py", "kind": "input", "reason": "recipe_project_unreadable",
                              "message": f"recipe.project: {recipe['project']} is not a JSON object"})
-        idx = int(recipe.get("clip_key", 0))
+        idx = int(recipe.get("clip_key") or 0)  # null is clip 0, as check_recipe_types() reads it
         proj.setdefault("clips", [{}])
         while len(proj["clips"]) <= idx:
             proj["clips"].append({})
@@ -539,11 +572,12 @@ def main() -> int:
     if not folder.is_dir():
         die(f"not a folder: {folder}")
     try:
-        recipe = json.loads(Path(args.recipe).read_text(encoding="utf-8"))
+        recipe = read_json(args.recipe)  # too deep is a ValueError too (A20)
     except (OSError, ValueError) as exc:
-        die(f"cannot read recipe: {exc}")
+        die(f"cannot read recipe: {exc}", kind="input")
     if not isinstance(recipe, dict):
-        die("cannot read recipe: not a JSON object")
+        die("cannot read recipe: not a JSON object", kind="input")
+    check_recipe_types(recipe)
     if recipe.get("project") and not os.path.isabs(recipe["project"]):
         recipe["project"] = str((Path(args.recipe).resolve().parent / recipe["project"]))
     # a recipe error is the same for every item: refuse it once, before any item runs, rather than

package/scripts/caption.py

@@ -59,6 +59,8 @@ from _common.runner import subtitle_codec_for, subtitle_container_holds
 from _common.fonts import font_choice, record_font_choice
 from _common import (ASR_INSTALL_HINT, die_no_engine, parse_srt, transcribe, whisper_word_timings,
                      write_srt)
+from _common.asr import srt_blocks
+from _common.runner import normalize_text
 from _common import (SAFE_WIDTH_FRACTION, ORPHAN_MIN_EM, WRAP_MODES, wrap_text, wrap_variants, best_break,
                      fit_size, line_em_for_size, MIN_CAPTION_FRACTION,
                      break_penalty, _is_weak_line, _atoms, _join, _break_spaced, _bare_word, _function_words,
@@ -83,10 +85,21 @@ ALIGN = {"bottom": 2, "top": 8, "center": 5, "bottom-left": 1, "bottom-right": 3
 FORCE_STYLE_ALIGN = {"bottom": 2, "top": 6, "center": 10, "bottom-left": 1, "bottom-right": 3, "top-left": 5, "top-right": 7}
 
 TIME_RE = re.compile(
-    r"^\s*(?P<a>[\d:.,@]+)\s*(?:-->|-|–|to)\s*(?P<b>[\d:.,@]+)\s+(?P<text>.+)$"  # @ = the 1.9 @fps suffix
+    r"^\s*(?P<a>[\d:.,@]+)\s*(?P<sep>-->|-|–|to)\s*(?P<b>[\d:.,@]+)\s+(?P<text>.+)$"  # @ = the 1.9 @fps suffix
 )
 
 
+def cue_times_match(line: str) -> "Optional[re.Match[str]]":
+    """TIME_RE's match of a --text line, or None when the line is caption text. The documented
+    separators are "-" and "-->", and with them bare seconds are times ("0-1.5 Hello"). "to" is
+    also an English word: "3 to 5 apples" is text, so with "to" both sides must be clock times
+    (a ':' in each, "0:03 to 0:05 Hello")."""
+    m = TIME_RE.match(line)
+    if m and m.group("sep") == "to" and not (":" in m.group("a") and ":" in m.group("b")):
+        return None
+    return m
+
+
 # an SRT timing line: the times alone, the cue text on the lines after it
 DROP_FRAME_RE = re.compile(r"^\s*\d+:\d{2}:\d{2};\d+")
 SRT_TIMING_RE = re.compile(r"^\s*\d+:\d{2}:\d{2}[,.]\d+\s*-->\s*\d+:\d{2}:\d{2}[,.]\d+\s*$")
@@ -95,9 +108,11 @@ SRT_TIMING_RE = re.compile(r"^\s*\d+:\d{2}:\d{2}[,.]\d+\s*-->\s*\d+:\d{2}:\d{2}[
 def parse_text_cues(path: str, auto_seconds: float, gap: float, fps: Optional[float] = None) -> List[Tuple[float, float, str]]:
     cues: List[Tuple[float, float, str]] = []
     cursor = 0.0
-    lines = read_text_or_die(path, "--text").lstrip("\ufeff").splitlines(True)
+    # split at "\n" only: splitlines() also breaks a cue at U+2028, U+0085, \v and \f, which
+    # made the rest of the line an auto-timed cue of its own
+    lines = read_text_or_die(path, "--text").split("\n")
     for n, raw in enumerate(lines, 1):
-        if SRT_TIMING_RE.match(raw.rstrip("\r\n")):
+        if SRT_TIMING_RE.match(raw):
             # a cue file puts the text on the line with its times; this line has the times alone, so
             # the file is an SRT. Read as a cue file, its numbers and timing lines would be burned in
             # as captions, auto-timed 3 s apart (#396)
@@ -107,11 +122,10 @@ def parse_text_cues(path: str, auto_seconds: float, gap: float, fps: Optional[fl
             # TIME_RE has no ';', so the line would be burned as caption text, auto-timed
             die(f"--text: line {n} has a drop-frame timecode (';'), which is not read: write it as "
                 "hh:mm:ss:ff@29.97 or in seconds", kind="input")
-    for raw in lines:
-        line = raw.rstrip("\n")
+    for line in lines:
         if not line.strip():
             continue
-        m = TIME_RE.match(line)
+        m = cue_times_match(line)
         if m:
             try:
                 start, end = parse_time(m.group("a"), fps), parse_time(m.group("b"), fps)
@@ -535,7 +549,7 @@ def max_line_em(args, play_w: Optional[int], play_h: Optional[int]) -> Optional[
 def parse_ass_dialogue(path: str) -> str:
     """The spoken text of an ASS file, for script detection -- style/override blocks stripped."""
     text = []
-    for line in read_text_or_die(path, "--ass").lstrip("\ufeff").splitlines():
+    for line in read_text_or_die(path, "--ass").split("\n"):
         if not line.startswith("Dialogue:"):
             continue
         fields = line.split(",", 9)
@@ -557,7 +571,7 @@ def parse_ass_cues(path: str, stats: Optional[dict] = None) -> List[Tuple[float,
     # the [Events] Format line names the columns; Text is always last (libass reads it the same
     # way), and a file without one gets the standard ten
     names = ["layer", "start", "end", "style", "name", "marginl", "marginr", "marginv", "effect", "text"]
-    for line in read_text_or_die(path, "--ass").lstrip("\ufeff").splitlines():
+    for line in read_text_or_die(path, "--ass").split("\n"):
         if line.startswith("Format:") and "text" in line.lower():
             names = [n.strip().lower() for n in line.partition(":")[2].split(",")]
             continue
@@ -601,7 +615,8 @@ def count_visible_cues(cues, duration) -> Tuple[int, int]:
 def shift_ass_file(src: str, dst: str, offset: float) -> Tuple[int, int]:
     """Copy an ASS file with every Dialogue start/end moved by `offset` seconds; (lines shifted,
     Dialogue lines copied unshifted because their timestamps could not be read)."""
-    text, n, unshifted = shift_ass_text(Path(src).read_text(encoding="utf-8-sig"), offset)
+    # read as the dry run reads it: a file that is not UTF-8 is refused as kind input on both
+    text, n, unshifted = shift_ass_text(read_text_or_die(src, "--ass"), offset)
     Path(dst).write_text(text, encoding="utf-8-sig")
     return n, unshifted
 
@@ -621,7 +636,9 @@ def shift_ass_text(source: str, offset: float) -> Tuple[str, int, int]:
 
     n = unshifted = 0
     out = []
-    for line in source.splitlines():
+    # lines end at "\n" only (libass reads them so); a U+2028 inside a Dialogue's text is text
+    body = normalize_text(source)
+    for line in (body[:-1] if body.endswith("\n") else body).split("\n"):
         if line.startswith("Dialogue:"):
             head, sep, rest = line.partition(":")
             fields = rest.split(",")
@@ -929,12 +946,9 @@ def srt_timings_shared_grammar(path: str) -> bool:
     """True when every timing line of the SRT at `path` reads the same to ffmpeg's SRT demuxer as
     to parse_srt(). ffmpeg refuses `00:01,000` (no hours) and reads `00:00:01,5` as 1.005 s, where
     parse_srt() reads 1.5 s (#414); such a file is handed to ffmpeg as a rewritten copy."""
-    text = read_text_or_die(path, "--srt").lstrip("\ufeff").replace("\r\n", "\n")
-    # a cue's timing line is its first line with "-->", as parse_srt() reads it (and ffmpeg too);
-    # a later line holding "-->" is dialogue, not a timing this check should judge
-    blocks = [[ln for ln in b.split("\n") if ln.strip()] for b in re.split(r"\n\s*\n", text)]
-    timings = [next((ln for ln in b if "-->" in ln), None) for b in blocks]
-    return all(_SHARED_SRT_TIMING.match(line) for line in timings if line is not None)
+    # the timing lines parse_srt() reads, grouped as it groups them (srt_blocks()): a later line
+    # that only holds "-->" is dialogue, not a timing this check should judge
+    return all(_SHARED_SRT_TIMING.match(times) for times, _body in srt_blocks(read_text_or_die(path, "--srt")))
 
 
 def mux_subtitle_codec(output: str) -> str:
@@ -1461,7 +1475,7 @@ def main() -> int:
     if args.ass and args.offset and os.path.exists(args.ass):
         shifted = os.path.splitext(output)[0] + "_offset.ass"
         if STATE.dry_run:
-            _text, n, unshifted = shift_ass_text(read_text_or_die(args.ass, "--ass").lstrip("\ufeff"), args.offset)
+            _text, n, unshifted = shift_ass_text(read_text_or_die(args.ass, "--ass"), args.offset)
             info(f"[dry-run] would write {shifted} ({n} cues shifted by {args.offset:+g} s)")
         else:
             n, unshifted = shift_ass_file(args.ass, shifted, args.offset)

package/scripts/cut.py

@@ -58,7 +58,7 @@ import tempfile
 import zlib
 from typing import List, Tuple
 
-from _common.runner import fail_if_classified
+from _common.runner import JsonTooDeep, fail_if_classified, read_json
 from _common import (beat_grid, snap_points, decode_pcm_mono, rms_envelope, BEAT_MIN_CONFIDENCE)
 from _common import require_tool
 from _common.probe import TS_EXTS, signatures_match, stream_signature
@@ -1199,11 +1199,15 @@ def _grid_from_source(path: str, min_confidence: float) -> "dict":
     """The beat grid of `path`: a scenes.py --json document if that is what it is, otherwise a
     media file to measure. Reading a document is how a caller avoids a second decode."""
     try:
-        with open(path, "r", encoding="utf-8") as fh:
-            doc = json.load(fh)
+        doc = read_json(path)   # a media file is not UTF-8 or not JSON: a ValueError, then measured
+    except JsonTooDeep as exc:
+        die(f"--snap-source {path}: {exc}", kind="input")
     except (OSError, ValueError):
         doc = None
     if isinstance(doc, dict) and doc.get("beat_grid"):
+        if not isinstance(doc["beat_grid"], dict) or not isinstance(doc.get("beats") or [], list):
+            die(f"--snap-source {path}: beat_grid must be an object and beats a list "
+                "(regenerate it with `scenes.py MUSIC --beats --json`)", kind="input")
         grid = dict(doc["beat_grid"])
         grid["beats"] = doc.get("beats") or []
         # A scenes.py document carries the supported subset since 1.17; one written by an older

package/scripts/export.py

@@ -51,7 +51,7 @@ from _common import STATE, run_analysis, add_common, apply_common, bt709_label_f
 from _common.decision import hw_preset_video, restate_last_swap
 from _common.emit import note, record_fallback, record_skip, warn
 from _common.probe import square_pixels, square_pixels_note
-from _common.runner import ffmpeg_encoders, guard_sidecar, remember_written, reserve_sibling, run_analysis as _run_analysis, subtitle_codec_for
+from _common.runner import ffmpeg_encoders, guard_sidecar, remember_written, replace_checked, replace_checked_together, reserve_sibling, run_analysis as _run_analysis, subtitle_codec_for
 from _common.emit import file_identity
 from check import SPECS as PLATFORMS, measure_loudness
 from _platforms import ALIASES as _ALIASES, PLATFORMS as PLATFORM_TABLE, TP_TOLERANCE_DB, resolve as resolve_platform
@@ -209,23 +209,32 @@ def _key_fill(args, p: Dict, meta: Dict, output: str, cmd: List[str], vf: List[s
     # the fill is always written to a hidden sibling and moved into place only after the encode
     # succeeds: run() stages and cleans up only ffmpeg's last output (the key), so a failed encode
     # left a partial new fill (the retry was refused as output_exists) or truncated an existing one
-    fill_tmp = None
+    # the key is staged the same way, and both are committed together: a fill refused at its
+    # replace never leaves a new key beside it (which a retry would then refuse as existing)
+    fill_tmp = key_tmp = None
     if not STATE.dry_run:
         d, base = os.path.split(output)
         stem, ext = os.path.splitext(base)
         fill_tmp = reserve_sibling(d, stem, ext, "fill")  # created exclusively: never through a planted link
+        kd, kbase = os.path.split(key)
+        kstem, kext = os.path.splitext(kbase)
+        key_tmp = reserve_sibling(kd, kstem, kext, "key")
+        # this run's own placeholder: run()'s output check must not refuse it as someone's file
+        STATE.written.add(os.path.realpath(key_tmp))
     cmd += (p["audio"] if has_audio else ["-an"]) + [fill_tmp or output]
-    cmd += ["-map", "[key]"] + p["video"] + tc_args + cfr_args(meta) + ["-an", key]
+    cmd += ["-map", "[key]"] + p["video"] + tc_args + cfr_args(meta) + ["-an", key_tmp or key]
     try:
         run(cmd)
-        if fill_tmp:
-            os.replace(fill_tmp, output)
+        if fill_tmp and key_tmp:
+            # under both locks, and only while each is the file guard_sidecar() decided about
+            replace_checked_together([(fill_tmp, output), (key_tmp, key)])
     finally:
-        if fill_tmp:
-            # the command is recorded with the path the caller asked for, not the temp name
-            STATE.commands[:] = [c.replace(fill_tmp, output) for c in STATE.commands]
-            if os.path.exists(fill_tmp):
-                os.remove(fill_tmp)
+        for tmp, final in ((fill_tmp, output), (key_tmp, key)):
+            if tmp:
+                # the command is recorded with the path the caller asked for, not the temp name
+                STATE.commands[:] = [c.replace(tmp, final) for c in STATE.commands]
+                if os.path.exists(tmp):
+                    os.remove(tmp)
     remember_written(output, key)
     extra: Dict[str, object] = {"alpha_mode": args.alpha_mode or "straight", "key": {"output": key}}
     # a fill and a key for a switcher carry the picture and the sound; the source's subtitle and
@@ -746,7 +755,8 @@ def main() -> int:
                     die(f"--normalize: loudness.py failed: {why} ({kept_clause()})",
                         code=child_exit_code(child, proc.returncode) if proc.returncode else 1,
                         kind=err.get("kind") or "ffmpeg", output=output, hint=err.get("hint"))
-                os.replace(tmp, output)
+                # the export this run wrote, unless another process replaced it during the pass
+                replace_checked(tmp, output)
                 m = measure_loudness(output)
                 if not m:
                     # the file changed: the measurement before --normalize no longer describes it

package/scripts/join.py

@@ -44,6 +44,7 @@ from fractions import Fraction
 from typing import Any, Dict, List, Optional, Tuple
 
 from _common.probe import SILENT_PEAK_DBFS, signatures_match, stream_signature
+from _common.runner import read_text_or_die
 from _common import STATE, AUDIO_MEDIA_EXT, concat_list_line, guard_sidecar, place_output, refuse, sibling_temp, as_limited, draws_chroma, drawn_chain, label_chain, matrix_chain, range_chain, video_args, aac_args, add_common, apply_common, audio_codec_for, default_output, die, dry_run_input_pending, emit, ffmpeg_base, info, measured_level_dbfs, is_audio_output, probe, require_tool, run, validate_color, X264_PRESETS, fmt_secs
 from _common.emit import note, warn
 from _common.decision import av_clip_length, av_trim, stream_starts
@@ -280,13 +281,12 @@ def read_list(path: str) -> List[str]:
     """--list FILE: one segment per line, in order, relative to the list file's own folder.
     Blank lines and # comments are ignored, and ffmpeg's concat-demuxer spelling
     (`file 'part 01.wav'`) is accepted, so a list written for `ffmpeg -f concat` works as is."""
-    try:
-        text = open(path, encoding="utf-8").read()
-    except OSError as exc:
-        die(f"cannot read --list {path}: {exc}")
+    # the shared reader: a BOM, CRLF and a file that is not UTF-8 are read or refused as every
+    # other text input is, and a line ends at "\n" only
+    text = read_text_or_die(path, "--list")
     base = os.path.dirname(os.path.abspath(path))
     entries: List[str] = []
-    for line in text.splitlines():
+    for line in text.split("\n"):
         line = line.strip()
         if not line or line.startswith("#"):
             continue

package/scripts/metadata.py

@@ -43,7 +43,7 @@ def parse_chapters(path: str, duration: float) -> List[Dict[str, Any]]:
     start inside the file, the last chapter running to the file's end."""
     text = read_text_or_die(path, "--chapters")
     entries: List[Dict[str, Any]] = []
-    for n, raw in enumerate(text.splitlines(), start=1):
+    for n, raw in enumerate(text.split("\n"), start=1):  # not splitlines(): a title may hold U+2028
         line = raw.strip()
         if not line or line.startswith("#"):
             continue

package/scripts/render.py

@@ -75,7 +75,7 @@ from typing import Any, Dict, List, Optional, Sequence
 from export import PRESETS, PLATFORM_OF
 from _platforms import PLATFORMS, caption_defaults, resolve as resolve_platform
 from _common import guard_sidecar, STATE, add_common, aspect_ratio, brand_caption_style, load_brand, apply_common, child_args, die, emit, info, option_args, probe, require_tool, run, run_tool, place_output, refuse_output_is_input, _check_existing_output, _check_output_path, fingerprint, PLAN_VERSION, ffmpeg_version, X264_PRESETS
-from _common.runner import HW_ENV, HW_FORCED_ENV, add_hw_orchestrator_args, child_exit_code, found_exe, kept_clause, kept_deliverables, mark_delivered, remember_written
+from _common.runner import HW_ENV, HW_FORCED_ENV, add_hw_orchestrator_args, child_exit_code, found_exe, kept_clause, kept_deliverables, mark_delivered, read_json, remember_written
 from _common.emit import absorb_stage, audit, record_fallback, record_skip, refuse, warn
 from _common.decision import rebase_project_paths
 import subprocess
@@ -182,7 +182,7 @@ def load_template(name: str) -> Dict[str, Any]:
     if not path.is_file():
         die(f"unknown template {name!r}", hint="templates: " + ", ".join(template_names()) + " (or 'all')")
     try:
-        return json.loads(path.read_text(encoding="utf-8"))
+        return read_json(path)
     except (OSError, ValueError) as exc:
         die(f"cannot read template {path}: {exc}")
     return {}
@@ -504,7 +504,7 @@ def project_input_files(proj: Dict[str, Any], rel: Any) -> List[str]:
         # the brand's own logo and font_file are read by the overlay and caption stages, resolved
         # against the brand file as load_brand() resolves them; an unreadable brand is left to them
         try:
-            data = json.loads(Path(rel(brand)).read_text(encoding="utf-8"))
+            data = read_json(rel(brand))
         except (OSError, ValueError):
             data = None
         if isinstance(data, dict):
@@ -565,6 +565,14 @@ def validate_project(proj: Dict[str, Any], timeline: bool = False, stop_after: O
             require_object(proj.get(name), name)
         check_keys(proj.get(name), name, name)
     check_keys((proj.get("audio") or {}).get("stems"), "audio.stems", "audio.stems")
+    # the values the run reads with .get() or as a dict key: a list there was a traceback (A13)
+    audio = proj.get("audio")
+    if "audio" in read and isinstance(audio, dict):
+        require_object(audio.get("stems"), "audio.stems")
+    export = proj.get("export")
+    if "export" in read and isinstance(export, dict) and export.get("preset") and not isinstance(export["preset"], str):
+        die(f"export.preset: must be a preset name (a string), got {type(export['preset']).__name__} "
+            f"{export['preset']!r:.60}")
     if isinstance(proj.get("chapters"), list):
         # Every other project error is raised here, before the first ffmpeg call; a chapter typo
         # found inside the last stage costs a whole render and leaves an unchaptered file behind.
@@ -590,6 +598,14 @@ def validate_project(proj: Dict[str, Any], timeline: bool = False, stop_after: O
             # every clip stage starts from rel(c["src"]): without one it was a KeyError traceback
             if not item.get("src"):
                 die(f"clips[{i}]: no src")
+            if item.get("speed") and not timeline:
+                # the clips stage reads float(speed): "fast" or [2] was a traceback there (A13)
+                try:
+                    spd = float(item["speed"])
+                except (TypeError, ValueError):
+                    spd = float("nan")
+                if not (0 < spd < float("inf")):
+                    die(f"clips[{i}]: speed must be a positive number, got {item['speed']!r:.60}")
             if item.get("snap") is not None:
                 # the render reads a clip's snap only on a clip it cuts (in/out), the export never
                 if not timeline and (item.get("in") is not None or item.get("out") is not None):
@@ -984,6 +1000,19 @@ def execute_plan(plan: Dict[str, Any], path: str) -> int:
         _reject_plan(path, digest, "plan_version_unsupported",
                      f"{path}: plan_version {plan.get('plan_version')!r} is not {PLAN_VERSION}",
                      plan_version=plan.get("plan_version"), supported=[PLAN_VERSION])
+    # the fields below are walked as lists of objects or strings: a wrong type was a traceback
+    # with no audit record (A14), and is refused like every other plan error
+    for field, want, item in (("inputs", list, None), ("unbound_inputs", list, None), ("verify", list, dict),
+                              ("commands", list, str), ("cwd", str, None)):
+        value = plan.get(field)
+        if value is None:
+            continue
+        bad = not isinstance(value, want) or (item is not None and not all(isinstance(v, item) for v in value))
+        if bad:
+            shape = {"inputs": "a list", "unbound_inputs": "a list", "verify": "a list of objects",
+                     "commands": "a list of strings", "cwd": "a string"}[field]
+            _reject_plan(path, digest, "plan_field_invalid", f"{path}: {field} must be {shape}, got {type(value).__name__}",
+                         field=field, field_type=type(value).__name__)
     tool = str(plan.get("tool") or "")
     script = HERE / f"{tool}.py"
     if not re.fullmatch(r"[a-z][a-z0-9_]*", tool) or not script.exists() or tool == "render":
@@ -1238,9 +1267,10 @@ def main() -> int:
             if value:
                 die(f"{flag} belongs to --template NAME INPUT; a project.json states it in the project itself")
         try:
-            proj = json.loads(Path(args.project).read_text(encoding="utf-8"))
+            # read_json(): nesting too deep is a ValueError too, refused here, not a RecursionError
+            proj = read_json(args.project)
         except (OSError, ValueError) as exc:
-            die(f"cannot read project: {exc}")
+            die(f"cannot read project: {exc}", kind="input")
         if not isinstance(proj, dict):
             die(f"{args.project}: not a project or plan object (top level is {type(proj).__name__})")
         if "plan_version" in proj:

package/scripts/report.py

@@ -126,7 +126,7 @@ def pack_report(args) -> int:
     text = read_text_or_die(args.pack, "--pack")
     rows: List[List[str]] = []
     header: List[str] = []
-    for line in text.splitlines():
+    for line in text.split("\n"):
         line = line.strip()
         if not line.startswith("|"):
             continue
@@ -233,7 +233,9 @@ def main() -> int:
             if meta and meta.get("video"):
                 sheets[which], why = sheet_b64(path)
                 section("contact_sheet", which, why, f"{which} contact sheet")
-    commands = read_text_or_die(args.commands, "--commands").splitlines() if args.commands else []
+    # one per line, split at "\n" only (a command may hold U+2028 or \f; splitlines() split it)
+    command_text = read_text_or_die(args.commands, "--commands") if args.commands else ""
+    commands = command_text.removesuffix("\n").split("\n") if command_text else []
     notes = read_text_or_die(args.notes, "--notes") if args.notes else ""
     title = args.title or f"Delivery report — {Path(args.after).name}"
 

package/scripts/sequence.py

@@ -18,11 +18,13 @@ import argparse
 import re
 import sys
 import tempfile
+from fractions import Fraction
 from pathlib import Path
 
 from _common import add_common, apply_common, default_output, die, emit, ffmpeg_base, info, probe, run, video_args, X264_PRESETS, concat_list_line, fmt_secs
 from _common.emit import note, warn
 from _common.probe import display_size, square_pixels_note
+from _common.timeline import TimelineError, exact_rate
 
 
 def even(n: float) -> int:
@@ -34,6 +36,30 @@ def _concat_list_line(path: Path) -> str:
     return concat_list_line(str(path))
 
 
+def frame_durations(count: int, rate: Fraction) -> list:
+    """The concat-list duration of each of `count` frames at `rate`, in whole microseconds: frame
+    i lasts round(start(i+1)) - round(start(i)) with start(i) = i/rate, each position rounded
+    once, so the demuxer's running sum is frame i's exact start to within half a microsecond at
+    every frame (#474: 1/30 written 0.033333 fell 3.3e-7 s behind per frame, half a frame after
+    about 50,000 frames)."""
+    def at(i: int) -> int:
+        return round(i * 1_000_000 / rate)
+    return [at(i + 1) - at(i) for i in range(count)]
+
+
+def concat_list(frames: list, rate: Fraction) -> str:
+    """The concat-demuxer list for `frames` (paths) shown one frame each at `rate`."""
+    lines = []
+    framerate = f"option framerate {rate.numerator}/{rate.denominator}"
+    for f, us in zip(frames, frame_durations(len(frames), rate)):
+        lines.append(_concat_list_line(f))
+        lines.append(framerate)
+        lines.append(f"duration {us // 1_000_000}.{us % 1_000_000:06d}")
+    lines.append(_concat_list_line(frames[-1]))  # concat demuxer: last entry's duration is ignored, so repeat it
+    lines.append(framerate)
+    return "\n".join(lines)
+
+
 def natural_key(name: str) -> list:
     """img2 < img10: digit runs compare as numbers, the rest case-insensitively."""
     return [int(t) if t.isdigit() else t.lower() for t in re.split(r"(\d+)", name)]
@@ -70,6 +96,10 @@ def main() -> int:
 
     if args.fps <= 0:
         die("--fps must be > 0")
+    try:
+        rate = exact_rate(args.fps)  # 29.97 is 30000/1001, as every other tool reads it
+    except TimelineError as exc:
+        die(f"--fps: {exc}")
     directory = Path(args.dir)
     if not directory.is_dir():
         die(f"--dir not found or not a directory: {args.dir}")
@@ -123,27 +153,20 @@ def main() -> int:
         out_w, out_h = even(sw), even(sh)
 
     output = args.output or default_output(str(directory).rstrip("/\\") or "sequence", "sequence", "mp4")
-    frame_duration = 1.0 / args.fps
-
     with tempfile.TemporaryDirectory(prefix="ffmpeg-skill-sequence-") as tmp:
         list_path = Path(tmp) / "frames.txt"
-        lines = []
-        for f in frames:
-            lines.append(_concat_list_line(f.resolve()))
-            lines.append(f"duration {frame_duration:.6f}")
-        lines.append(_concat_list_line(frames[-1].resolve()))  # concat demuxer: last entry's duration is ignored, so repeat it
-        list_path.write_text("\n".join(lines), encoding="utf-8")
+        list_path.write_text(concat_list([f.resolve() for f in frames], rate), encoding="utf-8")
 
         cmd = ffmpeg_base() + ["-f", "concat", "-safe", "0", "-i", str(list_path)]
-        vf = [f"scale={out_w}:{out_h}", "setsar=1", f"fps={args.fps:g}"]
+        vf = [f"scale={out_w}:{out_h}", "setsar=1", f"fps={rate.numerator}/{rate.denominator}"]
         cmd += ["-vf", ",".join(vf)]
         # RGB (PNG) frames are converted to the BT.709 the line is tagged with (the first frame's probe)
         cmd += video_args(None, args.crf, args.preset, source=frame_meta)
         # The concat demuxer's trailing repeated-last-file trick (needed so the last real file's
         # duration line takes effect) has been observed to produce an extra frame's worth of
         # duration on some ffmpeg builds -- force the exact intended length rather than trust it.
-        total_duration = len(frames) * frame_duration
-        cmd += ["-t", f"{total_duration:.6f}", "-an", output]
+        total_us = sum(frame_durations(len(frames), rate))
+        cmd += ["-t", f"{total_us // 1_000_000}.{total_us % 1_000_000:06d}", "-an", output]
         run(cmd)
 
     result = probe(output, role="output")

package/scripts/silence.py

@@ -28,6 +28,8 @@ from _common import (filler_spans, FILLER_WORDS, FILLER_AMBIGUOUS, FILLER_DISCOU
                      FILLER_PAD, read_text_or_die)
 from _common import asr as _asr
 from _common.emit import warn
+from _common.asr import _dicts
+from _common.runner import parse_json, replace_checked
 from _common import guard_sidecar, refuse_existing_outputs, refuse_output_is_input, _check_output_path
 from _common.emit import refuse
 from _common import detect_silences as detect, STATE, add_common, apply_common, default_output, die, emit, info, is_audio_output, print_json, probe, X264_PRESETS, measured_level_dbfs, fmt_secs
@@ -114,7 +116,7 @@ def sentence_words(args) -> "Tuple[list, str]":
         return usable(args._words, args._words_source)
     if args.words:
         try:
-            raw = json.loads(read_text_or_die(args.words, "--words"))
+            raw = parse_json(read_text_or_die(args.words, "--words"))
         except ValueError as exc:
             die(f"--words {args.words}: not readable JSON ({exc})", kind="input")
         words, _had_segments, _untimed = _words_from_transcript(raw)
@@ -261,7 +263,8 @@ def write_time_map(path: str, tm: Dict[str, Any]) -> None:
         mask = os.umask(0)  # mkstemp makes the file 0600; give the map the mode open() would have
         os.umask(mask)
         os.chmod(tmp, 0o666 & ~mask)
-        os.replace(tmp, path)
+        # under the map's lock, and only while it is the file refuse_existing_outputs() decided about
+        replace_checked(tmp, path)
     except BaseException:
         try:
             os.remove(tmp)
@@ -346,7 +349,7 @@ def resolve_filler(args, meta):
     untimed: list = []  # transcript words without a usable timing (a --words file can carry them)
     if args.words:
         try:
-            raw = json.loads(read_text_or_die(args.words, "--words"))
+            raw = parse_json(read_text_or_die(args.words, "--words"))
         except ValueError as exc:
             die(f"--words {args.words}: not readable JSON ({exc})", kind="input")
         source = f"whisper-json:{args.words}"
@@ -482,11 +485,13 @@ def _words_from_transcript(data):
     listed word it could not cut instead of dropping it unseen."""
     raw, had_segments = [], False
     if isinstance(data, dict):
-        raw = list(data.get("words") or [])
-        segments = data.get("segments") or []
+        # a "words" or "segments" that is not a list, and a segment that is not an object, carry no
+        # words: the file is then refused for having none, not by a traceback
+        raw = _dicts(data.get("words"))
+        segments = _dicts(data.get("segments"))
         had_segments = bool(segments)
         for seg in segments:
-            raw.extend((seg or {}).get("words") or [])
+            raw.extend(_dicts(seg.get("words")))
     elif isinstance(data, list):
         raw = list(data)
     out, untimed = [], []