ffmpeg-skill 3.1.7 → 3.1.8

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.1.7`) | any release |
+| `skill.version` | the npm / package.json version (`3.1.8`) | 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.1.7", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "3.1.8", "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"},
@@ -204,6 +204,11 @@ One entry per tool under `tools`, sorted by id. Tool ids are stable:
 | `execution` (writes a new artifact) | cut, fit, caption, overlay, graphics, multicam, audio, join, color, export, render, batch |
 | `verification` (checks or shows an artifact) | check, look, verify, report |
 
+`batch` writes one artifact per input only when a recipe step names `{out}` (or the recipe is a
+render project): a recipe in which no step does (a QC pass of `check.py`/`probe.py`) writes none,
+and each `results` row carries `written: false` beside its usual `output` path, which stays a
+string (#415).
+
 ### Verification policy
 
 The workflow in `SKILL.md` is "probe first, verify last". The contract states it per tool:
@@ -882,6 +887,14 @@ caller never parses the prose:
 A tool that runs another (`render.py` stages and plans) forwards the child's `reason` and
 `details` in its own `error`. Both are absent on a failure that is not a refusal, like `hint`.
 
+A `timeout` or `interrupted` failure exits 124, or 130/143, whether the tool or a child tool it ran
+was stopped (`export.py --normalize`'s loudness pass, `render.py`'s stages, check, executed plan and
+pack destinations, `waveform.py`'s title and captions pass the child's code on). Its message ends "nothing was written" only when
+that is so: once a tool has written its deliverable and runs a further step on it
+(`export.py --normalize`, `render.py`'s chapters and check stages), the message names the file,
+says it is kept without the step that was stopped, and the document carries it as `output`
+(3.1.6, #415).
+
 **Diagnostics.** What a run decided on its own -- a warning, a fallback it took, a step it
 skipped -- is recorded as it happens (a stderr line too) and lands in the document as
 `diagnostics: {warnings, fallbacks, skipped}`, each entry `{code, message, ...facts}`; it is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "3.1.7",
+  "version": "3.1.8",
   "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": [
     "ffmpeg",

package/references/scripts.md

@@ -1240,10 +1240,18 @@ above the cap is clamped with a note, not refused, and both `jobs` and
   earlier has no such record and is processed again once, `entry_unverifiable`).
   A `.ffskill_cache.json` that does not parse is started empty with a
   `batch_cache_reset` warning and a line in `output_dir/.ffskill-audit.jsonl`.
-- With `--jobs > 1` each item gets its own work subdirectory
-  `<workdir>/<index>-<stem>/`, because step file names are stem-derived and two
-  sources sharing a stem would otherwise write over each other. `--jobs 1` (the
-  default) keeps the flat layout and is 1.16's path exactly.
+- Each item's intermediates go in a new directory of its own under the work
+  directory (`<workdir>/<index>-<random>/`), removed with them when the item
+  ends, whatever the outcome (3.1.6, #415): step file names are stem-derived, so
+  `clip.mp4` and `clip.mov` sharing a directory, or a rerun meeting an earlier
+  run's files, were refused as someone else's. A step that names no `{out}`
+  (`check.py`) passes its input on; when the last step writes nothing, the last
+  file written is delivered as the item's output, under its own extension (`.mp4`
+  for a video source) unless the recipe sets `ext`. A recipe in which no step names
+  `{out}` (a QC pass: `check.py`/`probe.py` on every file) writes nothing: each
+  row has `written: false` (`output` keeps its path string), a note says so, and `ok` follows the steps' exit codes.
+  Final names that differ only in case are a
+  collision (they are one file on macOS and Windows).
 - `--watch` composes: each pass is parallel, passes are sequential.
 
 ### caption.py --transcribe — optional local speech-to-text

package/scripts/_common/decision.py

@@ -114,9 +114,21 @@ def frame_size(ratio: Optional[Fraction], width: Optional[int], height: Optional
 SVT_PRESET = {"ultrafast": 12, "superfast": 11, "veryfast": 10, "faster": 9, "fast": 8, "medium": 6, "slow": 4, "slower": 3, "veryslow": 2, "placebo": 1}
 
 
+# Source containers the tools' own encoders (x264/x265/SVT-AV1 and AAC) cannot be written into: WebM
+# takes only VP8/VP9/AV1 and Vorbis/Opus. A default output name keeps the source's extension
+# except for these, whose default is .mp4 (#415): the dry run planned `clip_loudnorm.webm` and the
+# real run then failed in the muxer.
+NO_DEFAULT_ENCODE_EXT = {".webm"}
+
+
 def default_output(input_path: str, suffix: str, ext: Optional[str] = None) -> str:
     p = Path(input_path)
-    new_ext = ext if ext else p.suffix.lstrip(".") or "mp4"
+    if ext:
+        new_ext = ext
+    elif p.suffix.lower() in NO_DEFAULT_ENCODE_EXT:
+        new_ext = "mp4"
+    else:
+        new_ext = p.suffix.lstrip(".") or "mp4"
     return str(p.with_name(f"{p.stem}_{suffix}.{new_ext}"))
 
 

package/scripts/_common/runner.py

@@ -14,7 +14,7 @@ import re
 import shutil
 import subprocess
 import sys
-from typing import Any, Dict, List, Optional, Sequence, Tuple
+from typing import Any, Callable, Dict, List, Optional, Sequence, Tuple
 
 
 INSTALL_HINTS = {
@@ -108,6 +108,13 @@ _FFMPEG_VERSION: "Optional[Tuple[int, int]]" = None
 _FFMPEG_VERSION_IS_RELEASE = False   # ffmpeg_version() read a release number, not the libavutil major
 
 
+def _probe_limit() -> float:
+    """The ceiling for a short read-only ffprobe/ffmpeg query run outside run(): PROBE_TIMEOUT, or
+    the caller's --timeout when that is lower (#415). Never unlimited: a version or stream-list read
+    that hangs is a stall, whatever --timeout 0 asks of the encodes."""
+    return min(PROBE_TIMEOUT, STATE.timeout) if STATE.timeout else PROBE_TIMEOUT
+
+
 def ffmpeg_version() -> "Tuple[int, int]":
     """(major, minor) of the FFmpeg build on PATH, parsed once from `ffprobe -version`; (0, 0)
     when it cannot be read. ffprobe rather than ffmpeg because --dry-run promises never to run
@@ -120,7 +127,7 @@ def ffmpeg_version() -> "Tuple[int, int]":
         _FFMPEG_VERSION = (0, 0)
         try:
             out = subprocess.run([found_exe("ffprobe"), "-version"], stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True, encoding="utf-8", errors="replace",
-                                 timeout=PROBE_TIMEOUT).stdout
+                                 timeout=_probe_limit()).stdout
             m = re.search(r"ffprobe version\s+n?(\d+)\.(\d+)", out)
             if m:
                 _FFMPEG_VERSION = (int(m.group(1)), int(m.group(2)))
@@ -158,7 +165,7 @@ def ffmpeg_release() -> "Optional[Tuple[int, int, int]]":
         _FFMPEG_RELEASE_READ = True
         try:
             out = subprocess.run([found_exe("ffprobe"), "-version"], stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True, encoding="utf-8", errors="replace",
-                                 timeout=PROBE_TIMEOUT).stdout
+                                 timeout=_probe_limit()).stdout
             m = re.search(r"ffprobe version\s+n?(\d+)\.(\d+)(?:\.(\d+))?", out)
             if m:
                 _FFMPEG_RELEASE = (int(m.group(1)), int(m.group(2)), int(m.group(3) or 0))
@@ -325,7 +332,7 @@ class Context:
     __slots__ = ("dry_run", "json", "json_brief", "progress", "fast", "duration_hint", "commands", "timeout", "overwrite", "written", "preexisting", "plan", "plan_written", "plan_inputs", "codec",
                  "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")
+                 "source_timecode", "smpte_hint", "delivered")
 
     def __init__(self) -> None:
         self.reset()
@@ -337,6 +344,7 @@ class Context:
         self.video_inputs = set()  # real paths of the inputs probed that have a picture: with two or more, which one the output shows is the tool's choice (sync --trim-second, a join)
         self.source_timecode = None  # (start timecode, duration) of the first input probed that carries one (time_arg's SMPTE hint)
         self.smpte_hint = None    # what die() says when an hh:mm:ss:ff flag read past the end looks like a source timecode (#411)
+        self.delivered: List[str] = []  # deliverables written before a later step (export --normalize, render's chapters/check): a stop then keeps them (#415)
         self.audio_inputs = set()  # real paths of the inputs probed that have sound: with two or more, whose tracks an output should keep is the tool's choice (grid --audio-from, a mix)
         self.json_brief = False   # --json-brief: the same document trimmed to the fields a caller acts on
         self.progress = False     # run() streams percent / ETA to stderr for ffmpeg
@@ -533,12 +541,52 @@ def stop_children() -> None:
     _CHILDREN.clear()
 
 
+def mark_delivered(path: str) -> None:
+    """Record that this run has written its deliverable and still has a step to run on it (export's
+    --normalize, render's chapters and check stages): a timeout or an interrupt from then on says the
+    file is there and kept, instead of "nothing was written" (#415)."""
+    if path and path not in STATE.delivered:
+        STATE.delivered.append(path)
+
+
+def child_exit_code(doc: Any, returncode: Optional[int]) -> int:
+    """The exit code a tool passes on from a child tool that failed: the code its document states,
+    else its process's own, else 1. A child killed by a signal has a negative returncode (-9), which
+    as an exit code wraps (247); it is passed on as the shell reports it, 128 + the signal (137)."""
+    code = (doc.get("exit_code") if isinstance(doc, dict) else None) or returncode or 1
+    try:
+        code = int(code)
+    except (TypeError, ValueError):
+        return 1
+    return 128 - code if code < 0 else code
+
+
+def kept_deliverables() -> List[str]:
+    """The deliverables mark_delivered() named that are on disk."""
+    return [p for p in STATE.delivered if os.path.isfile(p)]
+
+
+def kept_clause() -> str:
+    """How a stopped run's message ends: "nothing was written", or which deliverable it had already
+    written and keeps (not the finished result: the step that was stopped did not run on it)."""
+    kept = kept_deliverables()
+    if not kept:
+        return "nothing was written"
+    return (f"{', '.join(kept)} had already been written by this run and {'is' if len(kept) == 1 else 'are'} kept, "
+            "without the step that was stopped (pass --overwrite to make it again)")
+
+
+def _kept_fields() -> Dict[str, Any]:
+    kept = kept_deliverables()
+    return {"output": kept[-1]} if kept else {}
+
+
 def _on_signal(signum: int, frame: Any) -> None:
     import signal as _signal
     name = {getattr(_signal, "SIGINT", None): "SIGINT", getattr(_signal, "SIGTERM", None): "SIGTERM"}.get(signum, str(signum))
     stop_children()
-    die(f"interrupted by {name}: the running command was stopped and its partial output removed; nothing was written",
-        code=128 + signum, kind="interrupted")
+    die(f"interrupted by {name}: the running command was stopped and its partial output removed; {kept_clause()}",
+        code=128 + signum, kind="interrupted", **_kept_fields())
 
 
 def install_signal_handlers() -> None:
@@ -895,10 +943,13 @@ class _OutputLock:
     the hour ran from the lock's creation, so a legitimate run longer than an hour lost its lock
     to a second writer. A takeover is recorded (`diagnostics.fallbacks`, stderr, and the audit
     log); so is running without a lock where none can be created (`diagnostics.warnings`)."""
-    def __init__(self, output: str) -> None:
+    def __init__(self, output: str, on_locked: "Optional[Callable[[str, str, Dict[str, Any]], None]]" = None) -> None:
+        # on_locked(message, hint, details): a caller that must not exit (batch.py's item worker)
+        # raises its own error for a held lock instead of the refusal below
         self.path: Optional[str] = None
         self.fd: Optional[int] = None
         self.output = output
+        self.on_locked = on_locked
         if output == "-" or output.startswith("pipe:") or output.startswith("-"):
             return
         d, base = os.path.split(os.path.abspath(output))
@@ -931,12 +982,14 @@ class _OutputLock:
                         taken = holder
                         continue
                 name = os.path.basename(self.path)[1:-len(".ffskill-lock")]
-                refuse("input", "output_locked",
-                       f"another run is writing {name!r} right now (lock {self.path}"
-                       + (f", pid {holder['pid']}" if holder.get("pid") else "") + "); wait for it or choose a different --output/-o path",
-                       hint=("wait for that run, or choose another -o path; if pid "
-                             f"{holder.get('pid')} is not an ffmpeg-skill run, delete {self.path}"),
-                       lock=self.path, output=os.path.abspath(self.output), **{k: v for k, v in holder.items() if k != "stale"})
+                msg = (f"another run is writing {name!r} right now (lock {self.path}"
+                       + (f", pid {holder['pid']}" if holder.get("pid") else "") + "); wait for it or choose a different --output/-o path")
+                hint = ("wait for that run, or choose another -o path; if pid "
+                        f"{holder.get('pid')} is not an ffmpeg-skill run, delete {self.path}")
+                details = dict(lock=self.path, output=os.path.abspath(self.output), **{k: v for k, v in holder.items() if k != "stale"})
+                if self.on_locked:
+                    self.on_locked(msg, hint, details)
+                refuse("input", "output_locked", msg, hint=hint, **details)
             except OSError as exc:
                 # an unlockable location (a read-only directory surfaces elsewhere): the run goes
                 # on without a lock, and says so -- two runs could now both write this output
@@ -1110,11 +1163,28 @@ def _remember_output(cmd: Sequence[str]) -> None:
         pass
 
 
+def remember_written(*paths: Optional[str]) -> None:
+    """Count files a child tool of this run wrote (render.py's stages, batch.py's steps) as this
+    run's own, as run() counts its ffmpeg outputs: a later stage that replaces one is not refused
+    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
+
+
 def _timed_out(cmd: Sequence[str], seconds: float) -> "None":
     _cleanup_partial_output(cmd)
-    die(f"{os.path.basename(cmd[0])} exceeded the {seconds:.0f} s time limit and was killed; nothing was written. "
-        f"Raise --timeout (or FFMPEG_SKILL_TIMEOUT) if the job is genuinely that long, or check the input for a stall",
-        code=124, kind="timeout")
+    if _is_ffmpeg(cmd) or seconds < PROBE_TIMEOUT:
+        advice = "Raise --timeout (or FFMPEG_SKILL_TIMEOUT) if the job is genuinely that long, or check the input for a stall"
+    else:
+        # a probe's own ceiling, which a higher --timeout does not raise: a read this long is a stall (#415)
+        advice = (f"A probe is limited to {PROBE_TIMEOUT:g} s whatever --timeout says, so this is a stall, not a long "
+                  "job: check that the input is readable (a network share, a file still being written)")
+    die(f"{os.path.basename(cmd[0])} exceeded the {seconds:g} s time limit and was killed; {kept_clause()}. {advice}",
+        code=124, kind="timeout", **_kept_fields())
 
 
 def _stage_existing_output(cmd: Sequence[str]) -> Tuple[List[str], Optional[str], Optional[str]]:
@@ -1446,7 +1516,7 @@ def run_tool(argv: Sequence[str], *, per_call: Optional[float] = None) -> subpro
         child.communicate()
         _unwatch(child)
         name = os.path.basename(str(argv[0]))
-        msg = f"{name} did not finish within {limit:.0f} s (4x the per-ffmpeg --timeout plus 60 s) and was killed"
+        msg = f"{name} did not finish within {limit:g} s (4x the per-ffmpeg --timeout plus 60 s) and was killed"
         doc = {"status": "failed", "exit_code": 124,
                "error": {"kind": "timeout", "message": msg, "code": ERROR_CODE["timeout"], "retryable": ERROR_RETRYABLE},
                "commands": []}
@@ -1479,13 +1549,22 @@ def _has_non_av_streams(cmd: Sequence[str]) -> bool:
     try:
         out = subprocess.run([found_exe("ffprobe"), "-v", "error", "-show_entries", "stream=codec_type", "-of", "csv=p=0", src],
                              stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True, encoding="utf-8", errors="replace",
-                             timeout=PROBE_TIMEOUT).stdout
+                             timeout=_probe_limit()).stdout
     except (OSError, subprocess.TimeoutExpired):
         return True
     kinds = {ln.strip() for ln in out.splitlines() if ln.strip()}
     return not kinds or bool(kinds & {"subtitle", "data", "attachment"})
 
 
+def fail_if_classified(proc: subprocess.CompletedProcess) -> None:
+    """Stop with a failed attempt's own error when ffmpeg named a cause a second encode would hit
+    the same way (a full disk, a missing encoder or filter, an unreadable input): the rule
+    run_keeping_subtitles() follows since #389, for every copy-then-re-encode or keep-then-drop
+    fallback (#415). Returns when the failure is unclassified, so the caller's retry runs."""
+    if proc.returncode != 0 and classify_ffmpeg_failure(proc.stderr or ""):
+        _fail(proc.args, proc.returncode, proc.stderr or "")
+
+
 # eia_608 (a QuickTime c608 caption track) decodes to text, so it converts like one (ffmpeg 6.1)
 TEXT_SUBTITLES = frozenset({"mov_text", "subrip", "srt", "ass", "ssa", "webvtt", "text", "eia_608"})
 MP4_FAMILY = frozenset({"mp4", "m4v", "mov"})
@@ -1550,10 +1629,11 @@ def run_keeping_subtitles(cmd: List[str], output: str) -> bool:
 
 
 def _limit_for(cmd: Sequence[str]) -> Optional[float]:
-    """The wall-clock ceiling for this command: ffprobe (and other read-only probes) get a fixed
-    short one, ffmpeg the configured one; None means unlimited."""
+    """The wall-clock ceiling for this command: ffprobe (and other read-only probes) get a short
+    one, PROBE_TIMEOUT or --timeout when that is lower (as _read_ff_list() does: a caller's
+    --timeout 2 bounds every child, #415), ffmpeg the configured one; None means unlimited."""
     if not _is_ffmpeg(cmd):
-        return PROBE_TIMEOUT if STATE.timeout else None
+        return min(PROBE_TIMEOUT, STATE.timeout) if STATE.timeout else None
     return STATE.timeout or None
 
 
@@ -1927,7 +2007,7 @@ def _read_ff_list(flag: str, pattern: str) -> set:
     tool = "ffprobe" if STATE.dry_run else "ffmpeg"
     # --timeout bounds this read too: on Apple Silicon every CPU re-encode asks for the list
     # (#314), so a deadlocked ffmpeg must not outlive the limit the caller set before the encode
-    limit = min(PROBE_TIMEOUT, STATE.timeout) if STATE.timeout else PROBE_TIMEOUT
+    limit = _probe_limit()
     _LIST_ERRORS.pop(flag, None)
     names: set = set()
     why = None

package/scripts/_contract.py

@@ -219,7 +219,7 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
     "render": dict(role="execution", inputs=["project.json (clips, transitions, captions, overlays, audio, loudness, export, check)", "media asset plus --template NAME (a shipped delivery template)"], outputs=["final video artifact", "one artifact per destination plus a pack table (--template all)", "work directory of stage outputs (--keep / --work)", "editor timeline (.fcpxml / .edl / .otio) instead of a render (--export-timeline)"],
                    required=FF, optional=[{"capability": "delegated", "when": "each stage (and each destination of --template) runs cut / join / fit / caption / graphics / overlay / audio / loudness / export / check with their capabilities"}],
                    video_required=False, audio_only=True, visual=True, verify=["probe", "check", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
-    "batch": dict(role="execution", inputs=["folder of media", "batch.json recipe (steps or a render project)"], outputs=["one artifact per input file in the recipe's output_dir", "content-hash cache"],
+    "batch": dict(role="execution", inputs=["folder of media", "batch.json recipe (steps or a render project)"], outputs=["one artifact per input file in the recipe's output_dir (none for a steps recipe, not a render project, in which no step names {out}: its rows carry written: false)", "content-hash cache"],
                   required=FF, optional=[{"capability": "delegated", "when": "each recipe step runs the named script with its capabilities"}],
                   video_required=False, audio_only=True, visual=False, verify=["probe"], produces_artifact=True, idempotency="cached", deterministic=True),
     "verify": dict(role="verification", inputs=["media files and/or folders"], outputs=["PASS/FAIL JSON per step", "Markdown report (--report)", "step outputs (--out / --keep)"],

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, add_hw_orchestrator_args, env_hw, stop_children
+from _common.runner import HW_FORCED_ENV, _OutputLock, add_hw_orchestrator_args, env_hw, stop_children
 from _common.emit import absorb_stage_hw, audit, note, shown, steps_encoder_report, warn
 
 HERE = Path(__file__).resolve().parent
@@ -59,6 +59,30 @@ def file_key(path: Path) -> str:
     return h.hexdigest()
 
 
+def side_inputs_key(recipe: Dict[str, Any]) -> str:
+    """The files a recipe's steps name besides {in}/{out} (check.py --compare REF, a LUT, a logo),
+    keyed by their own content: editing or removing one is a change the cache must see, or a QC
+    pass is served its old verdict against a reference that changed or is gone (#428 review).
+    Read on every pass, so a --watch loop sees the edit too."""
+    h = hashlib.sha1(usedforsecurity=False)
+    for step in recipe.get("steps") or []:
+        for arg in step[1:] if isinstance(step, list) else []:
+            if not isinstance(arg, str) or "{" in arg:
+                continue
+            value = arg.split("=", 1)[1] if arg.startswith("-") and "=" in arg else arg
+            if value.startswith("-") or not value:
+                continue
+            path = Path(value)
+            try:
+                if path.is_file():
+                    h.update(f"{value}\0{file_key(path)}\0".encode())
+                    continue
+            except OSError:
+                pass
+            h.update(f"{value}\0-\0".encode())  # absent now: different from when it existed
+    return h.hexdigest()[:8]
+
+
 def recipe_key(recipe: Dict[str, Any]) -> str:
     # A "project" recipe is just {"project": "<path>", "clip_key": N} -- the actual settings
     # (export preset, captions, everything) live in the file at that path, not in this dict.
@@ -182,9 +206,80 @@ def final_path(src: Path, recipe: Dict[str, Any], outdir: Path) -> Path:
     # detection of its own; see one_pass()'s pre-flight check, which uses this same computation
     # to catch that before any file is actually processed (and the earlier one silently clobbered).
     final_ext = recipe.get("ext") or src.suffix.lstrip(".") or "mp4"
+    steps = recipe.get("steps") or []
+    if not recipe.get("ext") and not recipe.get("project") and steps and not step_writes(steps[-1]) and not writes_nothing(recipe):
+        # the last step writes nothing, so what is delivered is an intermediate: its name says its
+        # container (a .webm source's fit.py step writes MP4, which must not be named .webm)
+        final_ext = intermediate_ext(src)
     return outdir / f"{src.stem}{suffix}.{final_ext}"
 
 
+def intermediate_ext(src: Path) -> str:
+    """The extension of an item's intermediate step files: the source's own for an audio file,
+    else mp4 (the tools' encoders write x264/AAC, which .webm and friends do not take)."""
+    return src.suffix.lstrip(".") if src.suffix.lower() in (".wav", ".mp3", ".m4a", ".flac") else "mp4"
+
+
+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:])
+
+
+def writes_nothing(recipe: Dict[str, Any]) -> bool:
+    """A steps recipe in which no step names {out}: it measures each file and writes none."""
+    return not recipe.get("project") and not any(step_writes(st) for st in recipe.get("steps") or [])
+
+
+def row_output(src: Path, recipe: Dict[str, Any], outdir: Path) -> Dict[str, Any]:
+    """An item's output fields for its row: `output` is always the final path, a string as it has
+    been since 1.x (a --json key never changes type within a major), and a recipe that writes
+    nothing adds `written: false` (#415, #428 review)."""
+    fields: Dict[str, Any] = {"output": str(final_path(src, recipe, outdir))}
+    if writes_nothing(recipe):
+        fields["written"] = False
+    return fields
+
+
+def deliver(src: str, final: Path) -> None:
+    """Move an item's last written intermediate to its final path, under the output guard every
+    tool applies: an existing file is replaced only with --overwrite. A dry run writes nothing."""
+    if STATE.dry_run:
+        # the refusal the real run would meet, as a step writing {out} plans it (#428 review)
+        if final.exists() and not STATE.overwrite:
+            raise ItemError({"step": None, "tool": None, "kind": "input", "reason": "output_exists",
+                             "message": f"refusing to overwrite existing output {str(final)!r}: pass --overwrite to replace it"})
+        log(f"  [dry-run] would deliver the last written file to {final}")
+        return
+
+    def locked(msg: str, hint: str, details: Dict[str, Any]) -> None:
+        raise ItemError({"step": None, "tool": None, "kind": "input", "reason": "output_locked",
+                         "message": msg, "hint": hint, "details": details})
+    # under the output lock every tool's write holds, so the existence check and the move are one
+    # step for another run delivering or writing the same path
+    with _OutputLock(str(final), on_locked=locked):
+        if final.exists() and not STATE.overwrite:
+            raise ItemError({"step": None, "tool": None, "kind": "input", "reason": "output_exists",
+                             "message": f"refusing to overwrite existing output {str(final)!r}: pass --overwrite to replace it"})
+        try:
+            os.replace(src, final)
+        except OSError:
+            # another filesystem: copy beside the final path and rename, so a copy that fails part
+            # way never leaves a truncated file where the caller's was
+            import shutil
+            tmp = final.with_name(f".{final.stem}.ffskill-{os.getpid()}-{threading.get_ident()}{final.suffix}")
+            try:
+                shutil.copyfile(src, tmp)
+                os.replace(tmp, final)
+            except OSError as exc:
+                try:
+                    os.remove(tmp)
+                except OSError:
+                    pass
+                raise ItemError({"step": None, "tool": None, "kind": "output",
+                                 "message": f"could not deliver {src} to {final}: {exc}"})
+    log(f"  delivered the last written file to {final}")
+
+
 def process(src: Path, recipe: Dict[str, Any], outdir: Path, work: Path,
             deadline: "Optional[float]" = None) -> Dict[str, Any]:
     final = final_path(src, recipe, outdir)
@@ -211,7 +306,7 @@ def process(src: Path, recipe: Dict[str, Any], outdir: Path, work: Path,
             proj["clips"].append({})
         proj["clips"][idx]["src"] = str(src.resolve())
         proj["output"] = str(final.resolve())
-        pj = work / f"{src.stem}_project.json"
+        pj = work / "project.json"
         pj.write_text(json.dumps(proj, indent=2), encoding="utf-8")
         ok, _doc = run_step(["render.py", str(pj)], budget())
         step_docs = [("render", _doc)]
@@ -231,7 +326,11 @@ def process(src: Path, recipe: Dict[str, Any], outdir: Path, work: Path,
         cut_reasons = []
         for i, step in enumerate(steps):
             last = i == len(steps) - 1
-            out = str(final) if last else str(work / f"{src.stem}_step{i}.{'mp4' if src.suffix.lower() not in ('.wav', '.mp3', '.m4a', '.flac') else src.suffix.lstrip('.')}")
+            # the item's directory is its own, so the name needs no stem (a long one overflowed it)
+            out = str(final) if last else str(work / f"step{i}.{intermediate_ext(src)}")
+            # a step that names no {out} (check.py, probe.py) writes nothing: the next step reads
+            # what this one read, and when it is the last, the last file written is delivered (#415)
+            writes = step_writes(step)
             argv = [str(a).replace("{in}", cur).replace("{out}", out) for a in step]
             step_ok, doc = run_step(argv, budget())
             step_docs.append((Path(str(argv[0])).stem if argv else "step", doc))
@@ -246,8 +345,16 @@ def process(src: Path, recipe: Dict[str, Any], outdir: Path, work: Path,
                 ok = False
                 failure = step_error(i, str(argv[0]) if argv else None, doc)
                 break
-            cur = out
-    result: Dict[str, Any] = {"file": str(src), "output": str(final), "ok": ok, "seconds": round(time.time() - t0, 1)}
+            if writes:
+                cur = out
+        if ok and cur != str(final) and not writes_nothing(recipe):
+            # the last step wrote nothing: the item's deliverable is the last file a step wrote,
+            # which is in this item's work directory and would be removed with it (#415)
+            try:
+                deliver(cur, final)
+            except ItemError as exc:
+                ok, failure = False, exc.error
+    result: Dict[str, Any] = {"file": str(src), **row_output(src, recipe, outdir), "ok": ok, "seconds": round(time.time() - t0, 1)}
     if failure:
         result["error"] = failure
     # `ok` is "every step completed" (design-decisions: a spec miss a tool cannot fix is completed +
@@ -291,6 +398,8 @@ def cached_output_changed(hit: Dict[str, Any]) -> "Optional[Dict[str, Any]]":
     output_missing, output_changed (size or mtime differ: something replaced or edited it) or
     entry_unverifiable (an entry written by 2.10.11 or earlier recorded no identity, so nothing can say
     the file is the one it describes)."""
+    if hit.get("written") is False or ("output" in hit and hit["output"] is None):
+        return None  # a recipe that writes nothing (check.py over a folder): no file to have changed
     out = str(hit.get("output") or "")
     now = output_identity(out) if out else None
     if now is None:
@@ -344,9 +453,22 @@ def main() -> int:
             if not isinstance(name, str) or name not in ALLOWED_STEP_SCRIPTS:
                 die(f"recipe step names a script that isn't one of this skill's own tools: {name!r} "
                     f"(must be a bare filename like 'silence.py', found in scripts/)")
+        if writes_nothing(recipe):
+            # a QC batch (check.py / probe.py on every file): its rows carry written: false, and its
+            # cache entries claim no file, so they are served rather than missed as output_missing (#415)
+            note("no recipe step names {out}: the steps only read each file, so no output is written "
+                 "(each row says written: false; its output path is not created)")
     outdir = Path(recipe.get("output_dir") or (folder / "out"))
     if not outdir.is_absolute():
         outdir = folder / outdir
+    # resolved, so an alias of the input folder ("sub/..", a symlink) is recognised as one: the
+    # input scan below excludes outdir's files by parentage, and the input check by resolved path
+    outdir = outdir.resolve()
+    if outdir == folder:
+        # the scan skips files under outdir, so it found nothing here, and with suffix "" a
+        # final path was the source itself, which --overwrite replaced (#428 review)
+        die(f"output_dir {recipe.get('output_dir')!r} is the input folder {folder}: its outputs would mix with "
+            "or replace the batch inputs -- set an \"output_dir\" outside it (the default is out/)", kind="input")
     work = Path(args.work) if args.work else outdir / ".work"
     # the children refuse an output whose directory does not exist, under --dry-run too, so the
     # directories are created for the plan as well -- and removed again afterwards when a dry
@@ -435,23 +557,47 @@ def main() -> int:
         # collapsing e.g. clip.mp4 and clip.mov to the same clip_out.mp4) -- catch that before
         # processing anything, rather than letting the later one silently overwrite the earlier
         # one's finished output with the cache still recording both as "ok".
-        by_final: Dict[Path, List[Path]] = {}
+        # Compared case-folded: Clip_out.mp4 and clip_out.mp4 are one file on macOS's and
+        # Windows' default filesystems, so a batch that only works on Linux is refused everywhere (#415).
+        by_final: Dict[str, List[Path]] = {}
         for src in files:
-            by_final.setdefault(final_path(src, recipe, outdir), []).append(src)
-        collisions = {dst: srcs for dst, srcs in by_final.items() if len(srcs) > 1}
+            by_final.setdefault(str(final_path(src, recipe, outdir)).casefold(), []).append(src)
+        collisions = {key: srcs for key, srcs in by_final.items() if len(srcs) > 1 and not writes_nothing(recipe)}
         if collisions:
-            detail = "; ".join(f"{dst.name} <- {', '.join(s.name for s in srcs)}" for dst, srcs in collisions.items())
-            die(f"{len(collisions)} output filename collision(s) in this batch -- rename the sources, "
+            detail = "; ".join(" / ".join(sorted({final_path(s, recipe, outdir).name for s in srcs}))
+                               + " <- " + ", ".join(s.name for s in srcs) for srcs in collisions.values())
+            die(f"{len(collisions)} output filename collision(s) in this batch (names that differ only in case are one "
+                f"file on macOS and Windows) -- rename the sources, "
                 f"or add a distinguishing \"suffix\"/\"ext\" per run, or split into separate globs: {detail}")
+        # A final path that is one of the inputs would replace a source -- an output_dir that is
+        # the input folder under another name ("sub/..") with suffix "" -- and --overwrite does
+        # not license that (#428 review). A recipe that writes nothing delivers no file.
+        if not writes_nothing(recipe):
+            inputs = {str(p.resolve()).casefold() for p in files}
+            hits = [s for s in files if str(final_path(s, recipe, outdir).resolve()).casefold() in inputs]
+            if hits:
+                die(f"{len(hits)} final output path(s) would replace a batch input ({', '.join(s.name for s in hits)}); "
+                    "the output_dir is the input folder -- set a different \"output_dir\" or a non-empty \"suffix\"",
+                    kind="input")
         def item_work(i: int, src: Path) -> Path:
-            """Where this item's intermediates go. Parallel items must not share one work dir:
-            the step file names are stem-derived, so two globs holding the same stem would write
-            over each other. Serial runs keep the flat layout 1.16 used, byte for byte."""
-            if jobs == 1:
-                return work
-            sub = work / f"{i}-{src.stem}"
-            sub.mkdir(parents=True, exist_ok=True)
-            return sub
+            """Where this item's intermediates go: a new directory of its own under the work
+            directory, removed with everything in it when the item ends (run_item()). The step
+            file names are stem-derived, so two items with one stem (clip.mp4, clip.mov) sharing a
+            directory refused each other's files, and a later run refused the files an earlier one
+            left there as someone else's (#415); parallel items had their own directories since
+            1.17, serial ones now do too."""
+            import tempfile
+            # no stem in the name: a stem near the 255-byte limit made the directory name too long
+            return Path(tempfile.mkdtemp(prefix=f"{i}-", dir=str(work)))
+
+        def run_item(i: int, src: Path) -> Dict[str, Any]:
+            """process() in the item's own work directory, which goes when it ends, however it ends."""
+            import shutil
+            iw = item_work(i, src)
+            try:
+                return process(src, recipe, outdir, iw, deadline)
+            finally:
+                shutil.rmtree(iw, ignore_errors=True)
 
         def store(key: str, r: Dict[str, Any]) -> None:
             if not (r["ok"] and not STATE.dry_run):
@@ -462,10 +608,10 @@ def main() -> int:
             with cache_lock:
                 # this run just rewrote r["output"]: an entry under another key (another recipe,
                 # the other GPU setting) that names the same file now describes bytes that are gone
-                for stale in [k for k, v in cache.items() if k != key and isinstance(v, dict) and v.get("output") == r["output"]]:
+                for stale in [k for k, v in cache.items() if r["output"] and r.get("written", True) and k != key and isinstance(v, dict) and v.get("output") == r["output"]]:
                     del cache[stale]
                 # the output as this run left it: a later hit is served only while it is unchanged
-                cache[key] = dict(r, output_identity=output_identity(r["output"]))
+                cache[key] = dict(r, output_identity=output_identity(r["output"]) if r["output"] and r.get("written", True) else None)
                 # write_text isn't atomic -- a process killed mid-write (or a --watch loop racing
                 # a concurrent manual run) could leave a truncated file that json.loads() above
                 # then silently treats as "no cache" (a ValueError -> {}), discarding every prior
@@ -483,8 +629,9 @@ def main() -> int:
         slots: "List[Optional[Dict[str, Any]]]" = [None] * len(files)
         pending: List[tuple] = []
         cache_miss: Dict[int, Dict[str, Any]] = {}
+        pass_key = rkey + side_inputs_key(recipe)
         for i, src in enumerate(files):
-            key = f"{file_key(src)}:{rkey}"
+            key = f"{file_key(src)}:{pass_key}"
             hit = cache.get(key)
             if isinstance(hit, dict) and not args.force:
                 why = cached_output_changed(hit)
@@ -503,7 +650,7 @@ def main() -> int:
 
         def timed_out_row(src: Path) -> "Dict[str, Any]":
             timed_out["hit"] = True
-            return {"file": str(src), "output": str(final_path(src, recipe, outdir)),
+            return {"file": str(src), **row_output(src, recipe, outdir),
                     "ok": False, "seconds": 0.0, "skipped": "timeout"}
 
         def failed_row(src: Path, exc: BaseException) -> "Dict[str, Any]":
@@ -522,13 +669,13 @@ def main() -> int:
                 error = {"step": None, "tool": None, "exception": exc.__class__.__name__,
                          "message": (str(exc) or exc.__class__.__name__)[:300]}
             log(f"    failed: {error['message']}")
-            return {"file": str(src), "output": str(final_path(src, recipe, outdir)),
+            return {"file": str(src), **row_output(src, recipe, outdir),
                     "ok": False, "verified": False, "seconds": 0.0, "error": error}
 
         def interrupted_row(src: Path, started: bool, r: "Optional[Dict[str, Any]]" = None) -> "Dict[str, Any]":
             """An item the interrupt reached: `interrupted: true` when it was running (its steps
             were stopped), `skipped: "interrupted"` when it had not started."""
-            row = dict(r) if r else {"file": str(src), "output": str(final_path(src, recipe, outdir)), "seconds": 0.0}
+            row = dict(r) if r else {"file": str(src), **row_output(src, recipe, outdir), "seconds": 0.0}
             row.update(ok=False, verified=False)
             if started:
                 row["interrupted"] = True
@@ -550,7 +697,7 @@ def main() -> int:
                     continue
                 info(f"=== {src.name}")
                 try:
-                    r = process(src, recipe, outdir, item_work(i, src), deadline)
+                    r = run_item(i, src)
                 except KeyboardInterrupt:
                     interrupted["hit"] = True
                     # the running item, then every one not started: each keeps its row
@@ -572,7 +719,7 @@ def main() -> int:
         def work_one(i: int, src: Path, key: str) -> Dict[str, Any]:
             _LOG.buffer = [f"=== {src.name}"]
             try:
-                r = process(src, recipe, outdir, item_work(i, src), deadline)
+                r = run_item(i, src)
                 if not interrupted["hit"]:   # a step the interrupt stopped is no result to keep
                     store(key, r)
                 return with_miss(i, r)
@@ -670,7 +817,7 @@ def main() -> int:
     info(f"{done}/{len(results)} processed, {sum(1 for r in results if r.get('cached'))} from cache")
     if not args.json:
         for r in results:
-            print(f"{'OK  ' if r['ok'] else 'FAIL'} {r['file']} -> {r['output']}" + (" (cached)" if r.get("cached") else ""))
+            print(f"{'OK  ' if r['ok'] else 'FAIL'} {r['file']} -> {r['output'] or '(no output: the steps only read it)'}" + (" (cached)" if r.get("cached") else ""))
     if interrupted["hit"]:
         # Ctrl-C on a batch that already produced files: the user needs the partial table, not a
         # traceback and not "nothing was written". Exit 130 (143 for SIGTERM) with every item:
@@ -684,7 +831,7 @@ def main() -> int:
             timed_out=timed_out["hit"])
     if timed_out["hit"]:
         skipped = [r["file"] for r in results if r.get("skipped") == "timeout"]
-        die(f"the batch's {STATE.timeout:.0f} s budget ran out with {len(skipped)} item(s) not "
+        die(f"the batch's {STATE.timeout:g} s budget ran out with {len(skipped)} item(s) not "
             f"started: {', '.join(os.path.basename(f) for f in skipped[:5])}"
             + (" ..." if len(skipped) > 5 else "")
             + ". --timeout is the whole run's limit, not each item's; raise it or split the folder.",

package/scripts/check.py

@@ -32,6 +32,7 @@ the row set is unchanged.
 """
 import argparse
 import json
+import os
 import re
 import sys
 from fractions import Fraction
@@ -164,6 +165,12 @@ def main() -> int:
 
     # read before anything is measured and again after: a file replaced mid-check is not the one graded
     identity_before = None if dry_run_input_pending(args.input) else file_identity(args.input)
+    if identity_before is None and STATE.dry_run and not os.path.exists(args.input):
+        # a render/batch plan's earlier stage would write this file: there is nothing to grade yet,
+        # and grading the probe's empty answer divided by a 0 height
+        emit(None, platform=args.platform, checks=[], failed=0, warnings=0, ok=False,
+             notes=[f"[dry-run] {args.input} does not exist yet, so nothing was checked"])
+        return 0
     meta = probe(args.input)
     v, a = meta.get("video") or {}, meta.get("audio") or {}
     rows: List[Dict[str, Any]] = []

package/scripts/color.py

@@ -23,6 +23,7 @@ import os
 import sys
 from typing import List, Optional
 
+from _common.runner import fail_if_classified
 from _common import STATE, add_common, analyze_levels, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, ffmpeg_bsfs, info, probe, require_tool, run, run_analysis, run_keeping_subtitles, x264_args, X264_PRESETS, fmt_secs
 from _common.emit import warn
 
@@ -320,6 +321,7 @@ def retag(args: argparse.Namespace, meta: dict, has_audio: bool) -> int:
         cmd += ["-movflags", "+faststart"]
     cmd.append(output)
     proc = run(cmd, check=False)
+    fail_if_classified(proc)  # a full disk fails the re-encode too: its error, not two more encodes (#415)
     notes: List[str] = []
     reencoded = proc.returncode != 0
     if not reencoded and not STATE.dry_run:
@@ -345,6 +347,7 @@ def retag(args: argparse.Namespace, meta: dict, has_audio: bool) -> int:
         cmd = ffmpeg_base() + ["-i", args.input, "-map", "0:v:0", "-map", f"0:a:{args.audio_stream}?",
                                 "-map", "0:s?", "-map", "0:d?"] + label + enc + ["-c:s", "copy", "-c:d", "copy", output]
         proc2 = run(cmd, check=False)
+        fail_if_classified(proc2)
         if proc2.returncode != 0:
             info("re-encode with subtitles/data streams kept also failed; dropping them")
             dropped_streams = True

package/scripts/cut.py

@@ -58,6 +58,7 @@ import tempfile
 import zlib
 from typing import List, Tuple
 
+from _common.runner import fail_if_classified
 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
@@ -893,6 +894,7 @@ def cut_one(src: str, start: float, end: float, dst: str, reencode: bool, crf: i
     proc = run(cmd, check=False)
     if proc.returncode != 0:
         if not reencode:
+            fail_if_classified(proc)  # a full disk fails the re-encode too: its error, not a retry (#415)
             info("stream copy failed, falling back to re-encode")
             return cut_one(src, start, end, dst, True, crf, preset, tolerance, meta, reasons + ["copy_failed"], edit_list_ok)
         die(f"ffmpeg failed:\n{proc.stderr.strip()}", kind="ffmpeg")
@@ -1604,6 +1606,7 @@ def main() -> int:
                         cmd += ["-movflags", "+faststart"]
                     cmd += [joined]
                     proc = run(cmd, check=False)
+                    fail_if_classified(proc)  # #415: a full disk is not a reason to re-cut every segment
                     if proc.returncode != 0:
                         info("concat with stream copy failed; re-cutting every segment from the source into one re-encode")
                         compatible = False

package/scripts/export.py

@@ -38,6 +38,7 @@ import tempfile
 from pathlib import Path
 from typing import Dict, List
 
+from _common.runner import child_exit_code, fail_if_classified, kept_clause, mark_delivered
 from _common import STATE, run_analysis, add_common, apply_common, bt709_label_filter, bt709_matrix_args, bt709_tag_args, child_args, emit, cfr_args, default_output, die, encoder_args, ffmpeg_base, info, probe, require_tool, run, run_tool, validate_color, pad_filters, add_pad_fill_args, fmt_secs
 from _common.decision import hw_preset_video, restate_last_swap
 from _common.emit import note, record_fallback, record_skip, warn
@@ -183,6 +184,9 @@ def _run_keeping_non_av(cmd: List[str], output: str, sub_codecs: List[str], data
         attempt = run(cmd + extra + [output], check=False)
         if attempt.returncode == 0:
             return dropped
+        # a full disk or a missing encoder fails every rung the same way: that error, not a
+        # fallback that blames the subtitles and encodes again (#415, #389's rule)
+        fail_if_classified(attempt)
         error = " | ".join([ln.strip() for ln in (attempt.stderr or "").splitlines() if ln.strip()][-3:])[-500:]
         going = rungs[n + 1][1]
         record_fallback(f"{os.path.basename(output)} could not hold the source's {' and '.join(t for t in ('subtitle', 'data') if t in going)} "
@@ -347,7 +351,9 @@ def main() -> int:
         notes.append("source is %s (%s). This preset outputs SDR BT.709 tags without converting it; run color.py --to-sdr first for correct colours." % (kind, meta["video"].get("hdr_format")))
         warn(notes[-1], "colour_not_converted", preset=args.preset, hdr_format=meta["video"].get("hdr_format"))
     has_audio = bool(meta.get("audio"))
-    output = args.output or default_output(args.input, args.preset, p["ext"])
+    # copy keeps the source's container, so its default name keeps the source's extension (as
+    # metadata.py's does): default_output()'s .webm -> .mp4 is for the re-encoding presets
+    output = args.output or default_output(args.input, args.preset, p["ext"] or Path(args.input).suffix.lstrip(".") or None)
     out_ext = Path(output).suffix.lstrip(".").lower()
 
     vf: List[str] = []
@@ -466,6 +472,10 @@ def main() -> int:
         dropped = _run_keeping_non_av(cmd, output, sub_codecs, len(data)) if (subs or data) else []
         if not (subs or data):
             run(cmd + [output])
+    if not STATE.dry_run:
+        # the export is on disk: a stop in the reads and the --normalize pass that follow keeps it,
+        # and says so (#415)
+        mark_delivered(output)
     result = probe(output, role="output")
     v = result["video"]
     info(f"wrote {output} ({fmt_secs(result['duration'])}, {v['width']}x{v['height']}, {v['codec']})")
@@ -508,7 +518,12 @@ def main() -> int:
                     err = child.get("error") or {}
                     if os.path.exists(tmp):
                         os.remove(tmp)
-                    die(f"--normalize: loudness.py failed: {err.get('message') or proc.stderr.strip()[-300:]}",
+                    # the child's "nothing was written" is about its own temp file; this run's export is
+                    # on disk, and the child's exit code (124 timeout, 130/143 interrupted) is the
+                    # run's, as render.py and waveform.py pass a stage's on (#415)
+                    why = (err.get("message") or proc.stderr.strip()[-300:]).replace("; nothing was written", "")
+                    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)
                 m = measure_loudness(output)

package/scripts/metadata.py

@@ -221,7 +221,8 @@ def main() -> int:
         die(f"chapters file not found: {args.chapters}")
 
     meta = probe(args.input)
-    output = args.output or default_output(args.input, "meta")
+    # streams are copied, so the source's own container always holds them (a .webm stays .webm)
+    output = args.output or default_output(args.input, "meta", Path(args.input).suffix.lstrip(".") or "mp4")
     if os.path.abspath(output) == os.path.abspath(args.input):
         die("output must differ from the input (metadata.py never rewrites a file in place)")
     out_ext = Path(output).suffix.lower()
@@ -249,7 +250,13 @@ def main() -> int:
         cmd += ["-map", "0", "-map_metadata", "0", "-map_chapters", "0"]
     for key, value in tags.items():
         cmd += ["-metadata", f"{key}={value}"]
-    cmd += ["-c", "copy", output]
+    cmd += ["-c", "copy"]
+    if out_ext in (".mp4", ".mov", ".m4v", ".m4a"):
+        # A stream copy into the MPEG-4 family writes the index (moov) after the media unless told
+        # otherwise, so without +faststart a faststart input -- render's export -- came out with
+        # its index at the end (#415; every other MP4 write here is faststart since #279)
+        cmd += ["-movflags", "+faststart"]
+    cmd.append(output)
     run(cmd)
     if tmpdir:
         tmpdir.cleanup()

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, 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, found_exe
+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.emit import absorb_stage, audit, record_fallback, record_skip, refuse, warn
 import subprocess
 from _contract import CONTRACT_VERSION
@@ -351,6 +351,7 @@ def render_pack(names: List[str], args) -> int:
     rows: List[Dict[str, Any]] = []
     outputs: List[str] = []
     failed: List[str] = []
+    stopped: List[Dict[str, Any]] = []  # destinations a timeout stopped: {kind, exit_code}
     for name in names:
         # the destination decides the container: an audio-only destination in a pack must not be
         # handed a .mp4 name the single-template form would never have written (review 12)
@@ -394,6 +395,9 @@ def render_pack(names: List[str], args) -> int:
         outputs.append(out)
         if not ok:
             failed.append(name)
+            err = doc.get("error") or {}
+            if err.get("kind") in ("timeout", "interrupted"):
+                stopped.append({"kind": err["kind"], "exit_code": child_exit_code(doc, proc.returncode)})
     pack = str(outdir / f"{stem}_pack.md")
     lines = [f"# Social pack — {stem}", "",
              "| platform | file | size | duration | check |", "|---|---|---|---|---|"]
@@ -410,8 +414,11 @@ def render_pack(names: List[str], args) -> int:
         Path(pack).write_text("\n".join(lines) + "\n", encoding="utf-8")
     info(("[dry-run] would write " if STATE.dry_run else "wrote ") + pack)
     if failed:
+        # a destination that was stopped makes the pack a stopped run: its kind and exit code (124,
+        # 130/143), as a stage's are render.py's (docs/contract.md); otherwise a verification failure
         die(f"pack: {len(failed)} of {len(rows)} destinations failed: {', '.join(failed)}",
-            kind="verification", output=pack, dry_run=STATE.dry_run, pack=rows, outputs=outputs)
+            code=stopped[0]["exit_code"] if stopped else 1, kind=stopped[0]["kind"] if stopped else "verification",
+            output=pack, dry_run=STATE.dry_run, pack=rows, outputs=outputs)
     emit(pack, pack=rows, outputs=outputs, stages=["pack"],
          verification=[{"step": "check", "ok": r["ok"], "platform": r["platform"]} for r in rows])
     return 0
@@ -577,6 +584,8 @@ def sh(script: str, *argv: Any, extra: List[str] = None, stage: str = None) -> s
             # child's document standing, which a caller reading _LAST_DOC would misattribute.
             _LAST_DOC.clear()
             _LAST_DOC["cached"] = True
+            if not STATE.dry_run:
+                remember_written(dest)  # placed by this run, as a stage's own write would be (#415)
             return dest
         CACHE["misses"].append(stage)
         _refuse_uncached_earlier_stage(stage)
@@ -603,12 +612,27 @@ def sh(script: str, *argv: Any, extra: List[str] = None, stage: str = None) -> s
         extra_fields = {"hint": err["hint"]} if err.get("hint") else {}
         error_extra = absorb_stage(Path(script).stem, doc)  # the stage's reason/details and records ride along
         extra_fields.update(_stage_failure_hw(doc))
-        die(f"{script} failed: {err.get('message') or (proc.stderr.strip().splitlines() or ['?'])[-1][:300]}",
+        why = err.get('message') or (proc.stderr.strip().splitlines() or ['?'])[-1][:300]
+        if kept_deliverables() and err.get("kind") in ("timeout", "interrupted"):
+            # a stage after the delivery (chapters, check): the stage's own "nothing was written"
+            # is about its own file, while the delivery is on disk (#415)
+            why = why.replace("; nothing was written", "") + f" ({kept_clause()})"
+            extra_fields.setdefault("output", kept_deliverables()[-1])
+        elif err.get("kind") in ("timeout", "interrupted") and doc.get("output") and os.path.isfile(str(doc["output"])):
+            # the stage was stopped after writing its own deliverable and kept it (export.py's
+            # --normalize pass): its message says so, and the file is this run's output too
+            extra_fields.setdefault("output", str(doc["output"]))
+        die(f"{script} failed: {why}",
             code=int(doc.get("exit_code") or 1), kind=err.get("kind") or "input", stage=script, error_extra=error_extra, **extra_fields)
     _LAST_DOC.clear()
     _LAST_DOC.update(doc if isinstance(doc, dict) else {})
     absorb_stage(Path(script).stem, doc)  # a stage's GPU facts (ran on VideoToolbox, fell back and why) and its diagnostics reach this result
     out_path = str(doc.get("output") or "")
+    if not STATE.dry_run:
+        # A file a stage of this run wrote is this run's, not someone else's: the chapters stage
+        # places its tagged copy over the export's delivery, which the output guard would
+        # otherwise refuse as an existing file without --overwrite (#415).
+        remember_written(out_path, dest)
     if key:
         cache_store(stage, key, out_path or (dest or ""), time.time() - started, doc)
     return out_path
@@ -951,8 +975,10 @@ def execute_plan(plan: Dict[str, Any], path: str) -> int:
     if proc.returncode != 0 or doc.get("status") != "completed":
         err = doc.get("error") or {}
         error_extra = absorb_stage(tool, doc)  # the tool's reason/details and records ride along
+        # the tool's exit code is the plan's (124 timeout, 130/143 interrupted), as sh() passes a stage's on
         die(f"{tool} failed while executing the plan: {err.get('message') or proc.stderr.strip()[-300:]}",
-            kind=err.get("kind", "ffmpeg"), plan=path, tool=tool, error_extra=error_extra, **_stage_failure_hw(doc))
+            code=child_exit_code(doc, proc.returncode), kind=err.get("kind", "ffmpeg"), plan=path, tool=tool,
+            error_extra=error_extra, **_stage_failure_hw(doc))
     absorb_stage(tool, doc)  # the tool's GPU facts (fell back and why, ran on VideoToolbox) and diagnostics reach this result
     output = doc.get("output") or plan.get("output")
     check_result = None
@@ -1611,6 +1637,8 @@ def main() -> int:
             place_output(current, output)
         info(("[dry-run] would copy" if STATE.dry_run else "copied") + f" final stage to {output}")
     current = output
+    if not STATE.dry_run:
+        mark_delivered(output)  # the chapters and check stages run on it: a stop from here keeps it, and says so (#415)
 
     # ---- chapters (metadata.py on the delivered file: streams copied, markers written)
     ch = proj.get("chapters")
@@ -1648,6 +1676,13 @@ def main() -> int:
             exit_code = 1
         elif check_result.get("error") or check_result.get("status") == "failed":
             err = check_result.get("error")
+            if isinstance(err, dict) and err.get("kind") in ("timeout", "interrupted"):
+                # stopped, not failed: the run exits with check.py's own code (124, 130/143), as a
+                # stage that stopped does, and says the delivery it had written is kept (#415)
+                why = str(err.get("message") or "").replace("; nothing was written", "")
+                die(f"check.py failed: {why} ({kept_clause()})",
+                    code=int(check_result.get("exit_code") or err.get("exit_code") or 1), kind=err["kind"],
+                    stage="check.py", output=output, stages=stages_done)
             info(f"check: could not run check.py — {err.get('message') if isinstance(err, dict) else err}")
             exit_code = 1
         else:

package/scripts/sync.py

@@ -32,6 +32,7 @@ import os
 import sys
 from typing import Dict, List
 
+from _common.runner import fail_if_classified
 from _common import video_args, add_common, apply_common, emit, aac_args, audio_codec_for, default_output, die, ffmpeg_base, info, probe, require_tool, run, run_analysis, x264_args, decode_pcm_mono, rms_envelope
 from _common.emit import record_skip, warn
 from _common.decision import stream_starts
@@ -377,6 +378,7 @@ def main() -> int:
             cmd += ["-af", ",".join(af_parts)]
             cmd += aac_args() + (["-t", f"{ref_dur:.3f}"] if ref_dur else ["-shortest"]) + [output]
             proc = run(cmd, check=False)
+            fail_if_classified(proc)  # a cause the re-encode would hit too is reported, not retried (#415)
             if proc.returncode != 0:
                 cmd = [c for c in cmd if c != "copy"]
                 idx = cmd.index("-c:v"); del cmd[idx]
@@ -389,6 +391,7 @@ def main() -> int:
                     cmd += ["-movflags", "+faststart"]
                 cmd += ["-avoid_negative_ts", "make_zero", output]
                 proc = run(cmd, check=False)
+                fail_if_classified(proc)
                 if proc.returncode != 0:
                     cmd = ffmpeg_base() + ["-ss", f"{head_trim:.4f}", "-i", args.second] + (video_args(probe(args.reference) if args.replace_audio else probe(args.second), args.crf) if has_video else []) + audio_codec_for(output) + [output]
                     run(cmd)

package/scripts/waveform.py

@@ -284,6 +284,14 @@ def main() -> int:
             notes.append(f"the visualisation band and {args.platform}'s bottom safe zone overlap by "
                          f"{overlap}px: the captions or the app's own UI will sit over the waveform "
                          f"(lower --vis-height to {max(0.05, (args.height - safe_px) / args.height):.2f})")
+    if STATE.dry_run and (args.title or args.srt or args.text):
+        # graphics.py / caption.py plan on the render this dry run did not write, whose frame they
+        # cannot measure: their sizes and offsets come out 0 in the plan, and the real run takes
+        # them from the WxH render (#415). Said here, so a plan is not read as the real numbers.
+        later = " and ".join(n for n, on in (("title", args.title), ("captions", args.srt or args.text)) if on)
+        notes.append(f"the {later} stage was planned on the visualisation render this dry run did not write, so the "
+                     f"font sizes and offsets in its planned command are placeholders (0); the real run sizes them "
+                     f"from the {args.width}x{args.height} render")
     if silent_peak is not None:
         warn(f"{args.input} is silent (peak {silent_peak:g} dBFS); the visualisation is a flat line", "silent_input",
              path=args.input, peak_db=silent_peak)