ossclip 0.1.7 → 0.1.10

package/src/produce.ts

@@ -1,13 +1,15 @@
 import { createHash } from "node:crypto";
 import { createReadStream } from "node:fs";
 import { mkdir, readFile, writeFile, rename } from "node:fs/promises";
-import { existsSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { z } from "zod/v4";
 import {
   LayoutSchema,
   SceneSchema,
   TimeMap,
+  type KeptSpan,
+  mapFromKeptSpans,
   TranscriptSchema,
   analyze,
   applyOverrides,
@@ -19,6 +21,9 @@ import {
   buildZoomPlan,
   checkGrounding,
   rejectCtaKeyword,
+  concatFolder,
+  folderManifestKey,
+  listFolderVideos,
   coverHeadline,
   cropFilter,
   detectContentRect,
@@ -31,6 +36,7 @@ import {
   defaultTheme,
   detectSilences,
   dropHiddenCues,
+  splitThenDropHidden,
   emptyOverrideDoc,
   extractAudio,
   fillPlainCues,
@@ -40,8 +46,11 @@ import {
   formatGraphicsAccounting,
   findBloopSpans,
   formatBloopSpan,
+  findRetakeGroups,
+  formatRetakeGroup,
   formatUsageLine,
   formatUsageReport,
+  applyUserCuts,
   loadConfig,
   loudnorm,
   MAX_NORMALIZE_UPSCALE,
@@ -146,6 +155,14 @@ export interface ProduceOptions {
    * on camera cuts the attempt it spoiled, back to that sentence's start.
    */
   blooperMarker?: string;
+  /**
+   * `--collapse-retakes` (R27 §128): deterministically collapse consecutive
+   * near-identical sentences — the flub the speaker did NOT mark out loud.
+   * Opt-in, default off for v1: the promotion criterion is clean field runs
+   * recorded in this same report appendix, the mechanism this whole findings
+   * doc uses to decide when an opt-in flag has earned default-on.
+   */
+  collapseRetakes?: boolean;
   /**
    * How the source meets the vertical frame. `cover` (default) crops it to
    * fill; `contain` shows the WHOLE frame inset against the backdrop, which is
@@ -172,6 +189,21 @@ export interface ProduceOptions {
    * window with zero LLM calls. Written by clip runs; not for hand use.
    */
   clipWindow?: string;
+  /**
+   * `<input>` a DIRECTORY: order its clips before concatenating them into the
+   * source produce runs on (folder-input-brief.md). `name` (default) is a
+   * plain codepoint sort, matching `ls`; `mtime` is oldest-first. Ignored for
+   * a file input.
+   */
+  sort?: "name" | "mtime";
+  /**
+   * Whether `--sort` was TYPED, as opposed to commander filling in its
+   * `"name"` default. `sort` alone can't tell those apart, and `--sort` does
+   * nothing on a file input — final-review fix wave, cheap minor c: print a
+   * notice instead of silently ignoring a flag the user explicitly reached
+   * for.
+   */
+  sortExplicit?: boolean;
 }
 
 function sha1File(path: string): Promise<string> {
@@ -184,6 +216,188 @@ function sha1File(path: string): Promise<string> {
   });
 }
 
+/**
+ * Byte-for-byte comparison, used only to decide `planScreenshotSrcCopy`'s
+ * `identical` input for a same-basename `side-images/` collision. Side
+ * images are screenshots, not multi-gigabyte video — a size check plus a
+ * full read is simpler and strictly more correct than hashing (no collision
+ * risk to reason about) at a cost this call site never notices. IO glue,
+ * kept out of the pure decision function on purpose.
+ */
+function filesIdentical(a: string, b: string): boolean {
+  if (statSync(a).size !== statSync(b).size) return false;
+  return readFileSync(a).equals(readFileSync(b));
+}
+
+/**
+ * Where a run's cache/work directory lives, keyed off `identity` — the input
+ * file for an ordinary run, or the FOLDER itself for `produce <folder>`
+ * (folder-input-brief.md: hashing is the caller's job because the two cases
+ * hash different things — a file's bytes vs. a folder's path — this only
+ * places the result). `--workdir` overrides the root; the identity's own
+ * basename still names the subfolder so two different inputs sharing one
+ * `--workdir` don't collide.
+ */
+function deriveWorkdir(
+  identity: string,
+  hash: string,
+  workdirOpt: string | undefined,
+  landscape: boolean,
+): string {
+  const workRoot = workdirOpt ? resolve(workdirOpt) : join(dirname(identity), ".ossclip");
+  return join(
+    workRoot,
+    `${basename(identity).replace(/\.[^.]+$/, "")}-${hash}${landscape ? "-16x9" : ""}`,
+  );
+}
+
+/**
+ * Default output path when `--out` is not given. MUST be derived from the
+ * ORIGINAL input the user typed, never from `input` after a folder run
+ * reassigns it — review fix on the first cut of folder-input-brief.md: `input`
+ * by render time is `<workdir>/source-concat.mp4`, so deriving the default
+ * from it put `ossclip produce ~/Downloads/MyClips`'s output INSIDE the
+ * hidden `.ossclip` workdir (`.../MyClips-<hash>/source-concat.ossclip.mp4`)
+ * instead of beside the folder (`~/Downloads/MyClips.ossclip.mp4`), where a
+ * file input's equivalent default already lands.
+ */
+export function defaultOutPath(originalInput: string): string {
+  return originalInput.replace(/(\.[^.]+)?$/, ".ossclip.mp4");
+}
+
+/**
+ * Which directory the Remotion render will bundle its `publicDir` from,
+ * given the SAME `mezzanineWillBuild` boolean `produce()` computes once and
+ * feeds to the real `renderVideo` assignment further down — passed in,
+ * rather than recomputed here, so the two can never read a different answer
+ * to "will a mezzanine get built" than each other.
+ *
+ * Finding 3 (final-review fix wave): `dirname(renderVideo)` is where
+ * Remotion's `staticFile()` looks; a side-image accepted from some OTHER
+ * directory (a folder run's clips folder, or — the reviewer's pre-existing
+ * "latent" case — a file run's own folder once a mezzanine gets built)
+ * passes the accept check and then 404s inside the render, after the run has
+ * already spent the minutes getting there. `analysisInput` becomes something
+ * other than `input` only via the framing bake, and that bake always writes
+ * into `work`; the mezzanine build is the other path into `work`.
+ */
+export function planRenderPublicDir(p: {
+  input: string;
+  inputIsAnalysisInput: boolean;
+  mezzanineWillBuild: boolean;
+  work: string;
+}): string {
+  return !p.inputIsAnalysisInput || p.mezzanineWillBuild ? p.work : dirname(p.input);
+}
+
+/** Fixed subfolder every copied side-image lands in — see `planScreenshotSrcCopy`. */
+export const SIDE_IMAGE_SUBDIR = "side-images";
+
+/**
+ * An http(s) URL `src` is ScreenshotFrame's own documented territory — the
+ * component resolves `/^https?:\/\//` itself instead of calling
+ * `staticFile()` (ScreenshotFrame.tsx) — so produce must pass it through
+ * untouched: no filesystem lookup, no copy, no rewrite (audit fix: the
+ * safe-src check used to reject a URL as "names a path, not a bare filename",
+ * a misleading message about a shape the renderer explicitly supports).
+ */
+export function isRemoteScreenshotSrc(src: string): boolean {
+  return /^https?:\/\//.test(src);
+}
+
+/** A bare filename: no separator of either flavor, and not a `.`/`..` segment. */
+function isBareSafeName(name: string): boolean {
+  return name.length > 0 && !/[\\/]/.test(name) && name !== "." && name !== "..";
+}
+
+/**
+ * Whether an LLM-authored `ScreenshotFrame` `src` is safe to let drive
+ * filesystem access AT ALL. Checked BEFORE the accept-list lookup, not just
+ * before the copy — a crafted `src` could otherwise use `existsSync` itself
+ * as a path-existence oracle. `src` is unconstrained free text the producer
+ * invents from the transcript (R22 §112's comment on `ScreenshotFrameProps.
+ * src` — "will happily invent... from the transcript"); a value containing a
+ * path separator or a bare `.`/`..` segment is refused outright, never
+ * sanitized down to a bare name and used anyway (CLAUDE.md: values from
+ * outside are parsed, not coerced — a stripped `../../etc/passwd` silently
+ * becoming `passwd` is exactly the kind of "looks handled" bug that rule
+ * exists to prevent).
+ *
+ * ONE exception, and it is exactly one shape: `<SIDE_IMAGE_SUBDIR>/<bare
+ * safe name>` — the self-namespaced form `produce()` itself writes back into
+ * `production.json` post-copy (`planScreenshotSrcCopy`'s `destRel`).
+ * `--scenes <path>` re-ingests a PRIOR run's scenes array as the documented
+ * no-LLM tweak workflow (program.ts: "hand-authored scenes JSON — no LLM in
+ * the loop"), and that array can legitimately already contain this exact
+ * shape from the run it came from. Refusing it here would drop the image to
+ * a placeholder on every `--scenes` re-run of a previously-produced project
+ * — a regression this fix must not introduce while closing the traversal
+ * hole. This is NOT a general "one slash is fine" rule: `side-images/../x`,
+ * `side-images/a/b.png`, and `other/foo.png` all still fail below, since
+ * only a first segment matching the fixed subfolder AND a bare name after
+ * it qualifies.
+ *
+ * Deliberately NOT enforced as a zod `.refine` on `ScreenshotFrameProps.src`
+ * itself: the schema has no notion of "this run's own accepted output," so
+ * it can't distinguish the one safe slash-shape from every unsafe one
+ * without duplicating this exact logic — and getting it wrong there would
+ * reject produce's own accepted output on every future parse (the editor
+ * re-parses `production.json` through this same schema). The boundary that
+ * needs to refuse the LLM's raw guess (and allow its own prior output back
+ * in) is produce()'s, not the schema's.
+ */
+export function isSafeScreenshotSrc(src: string): boolean {
+  if (isBareSafeName(src)) return true;
+  const parts = src.split("/");
+  return parts.length === 2 && parts[0] === SIDE_IMAGE_SUBDIR && isBareSafeName(parts[1]!);
+}
+
+/**
+ * What to do with an accepted side-image that has to leave `foundDir` and
+ * land in the render's public dir. Landing inside a FIXED `side-images/`
+ * subfolder (`SIDE_IMAGE_SUBDIR`, never the public dir's root) makes a
+ * collision with a reserved pipeline filename (`mezzanine.mp4`,
+ * `source-concat.mp4`, …) impossible BY CONSTRUCTION — those artifacts never
+ * live in that subfolder — rather than something this function has to
+ * detect. Important finding (final-review fix wave, second pass on Finding 3):
+ * the original copy wrote straight to `join(publicDir, src)`, so a `src`
+ * equal to `mezzanine.mp4` silently overwrote the real mezzanine BEFORE its
+ * own `existsSync` guard ran, skipping the build and feeding a still image
+ * to the renderer as `renderVideo`; on a folder run with mezzanine off, the
+ * equivalent collision (`source-concat.mp4`) corrupted the actual analyzed
+ * source for the run and every cache reuse after it. What namespacing
+ * doesn't resolve on its own: whether the (now collision-free) destination
+ * is free, already holds the identical bytes (a re-run, or two scenes
+ * sharing one image — skip the redundant copy, still point `src` at it), or
+ * holds something else under that name (two different images that happen to
+ * share a basename — refuse rather than let the second clobber the first).
+ */
+export function planScreenshotSrcCopy(dest: {
+  exists: boolean;
+  identical: boolean;
+}): "copy" | "skip-identical" | "conflict" {
+  if (!dest.exists) return "copy";
+  return dest.identical ? "skip-identical" : "conflict";
+}
+
+/**
+ * The served relative URL a copied side-image is rewritten to. MUST be
+ * POSIX-literal — never `path.join()` — because this string is a SERVED
+ * URL, not a filesystem path: it gets written into `holder.props.src` and
+ * read back by Remotion's `staticFile()`, which splits ONLY on `/`
+ * (`static-file.js`: `path.split('/')`). `path.join()` uses the platform
+ * separator, so on Windows this would silently become
+ * `side-images\foo.png`, which `staticFile()` then encodes as ONE opaque
+ * segment (`side-images%5Cfoo.png`) that matches nothing on disk — every
+ * side-image render breaking on Windows, the exact shape of the 0.1.4→0.1.5
+ * cautionary tale (CLAUDE.md's Releases section). Pulled out as its own
+ * function so this literal can be pinned by a test independent of the
+ * platform running that test.
+ */
+export function sideImageDestRel(src: string): string {
+  return `${SIDE_IMAGE_SUBDIR}/${basename(src)}`;
+}
+
 /**
  * Frame-area share above which a layout's video slot is the SUBJECT rather
  * than an inset. `video-top` is 42% and full-bleed 100%; the pip bubble is 5%.
@@ -204,7 +418,15 @@ async function preflight(bin: string, hint: string): Promise<void> {
 
 export async function produce(inputArg: string, opts: ProduceOptions): Promise<ProduceResult> {
   const cfg = loadConfig();
-  const input = resolve(inputArg);
+  // `let`, not `const`: a folder input is reassigned to the concat
+  // intermediate below (folder-input-brief.md) so nothing past that point has
+  // to know a folder was ever involved. `originalInput` keeps what the user
+  // actually typed — review fix: the default --out path and the "beside the
+  // video" image lookup both used to read the REASSIGNED `input`, which for a
+  // folder run is a file inside the hidden workdir, not anything the user
+  // would recognise.
+  const originalInput = resolve(inputArg);
+  let input = originalInput;
   if (!existsSync(input)) throw new Error(`input not found: ${input}`);
 
   // §93b: the window is an editorial judgement, and there is deliberately no
@@ -235,16 +457,66 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
   const landscape = opts.aspect === "16:9";
   const frame = landscape ? { width: 1920, height: 1080 } : { width: 1080, height: 1920 };
 
-  const hash = (await sha1File(input)).slice(0, 8);
-  const workRoot = opts.workdir ? resolve(opts.workdir) : join(dirname(input), ".ossclip");
-  const work = join(
-    workRoot,
-    `${basename(input).replace(/\.[^.]+$/, "")}-${hash}${landscape ? "-16x9" : ""}`,
-  );
-  await mkdir(work, { recursive: true });
   const tools = { ffmpegPath: cfg.ffmpegPath, ffprobePath: cfg.ffprobePath };
 
+  // Folder input (folder-input-brief.md, 2026-08-05 field request). The
+  // workdir hash is derived from the folder's CONTENT — `folderManifestKey`
+  // over the enumerated clips — not the folder path. Review fix: a path-only
+  // hash is stable across content changes, but everything else this run
+  // caches into the same workdir (audio.wav, transcript.json, the
+  // content-rect cache, the mezzanine) is keyed on EXISTENCE, not content. A
+  // path-only hash meant adding a take rebuilt `source-concat.mp4` correctly
+  // but silently reused all of those against the OLD concat, producing a
+  // video with captions transcribed against a different edit. Hashing the
+  // manifest content gives a folder input the same invariant a file input
+  // already has via `sha1File`: content changes ⇒ a fresh workdir.
+  const isFolder = statSync(input).isDirectory();
+  // Final-review fix wave, cheap minor c: --sort only means anything for a
+  // folder input; on a file it did nothing, silently. Gated on `sortExplicit`
+  // (whether the user TYPED it) rather than on `opts.sort` itself, since
+  // commander's own "name" default would otherwise print this on every plain
+  // file run.
+  if (!isFolder && opts.sortExplicit) {
+    console.log("▸ --sort is ignored — <input> is a file, not a folder of clips");
+  }
+  let folderListing: Awaited<ReturnType<typeof listFolderVideos>> | undefined;
+  let hash: string;
+  if (isFolder) {
+    folderListing = await listFolderVideos(input);
+    hash = createHash("sha1")
+      .update(folderManifestKey(folderListing.entries, opts.sort ?? "name"))
+      .digest("hex")
+      .slice(0, 8);
+  } else {
+    hash = (await sha1File(input)).slice(0, 8);
+  }
+  const work = deriveWorkdir(input, hash, opts.workdir, landscape);
+  await mkdir(work, { recursive: true });
   console.log(`▸ workdir ${work}`);
+
+  if (isFolder && folderListing) {
+    const sort = opts.sort ?? "name";
+    const result = await concatFolder(tools, input, folderListing, work, sort, {
+      w: frame.width,
+      h: frame.height,
+    });
+    console.log(
+      `▸ folder: ${result.clips.length} clip(s), sorted by ${sort}, ` +
+        `concat ${result.durationSec.toFixed(1)}s${result.cached ? " (cached)" : ""}`,
+    );
+    if (result.nonVideoCount > 0) {
+      console.log(
+        `  ${result.nonVideoCount} non-video file${result.nonVideoCount === 1 ? "" : "s"} ignored`,
+      );
+    }
+    // Order visible immediately (folder-input-brief.md) — a wrong order is a
+    // silent bug otherwise, invisible until someone watches the whole thing.
+    result.clips.forEach((c, i) => {
+      console.log(`  ${i + 1}. ${c.name} (${c.durationSec.toFixed(2)}s)`);
+    });
+    input = result.path;
+  }
+
   const sourceProbe = await probe(tools, input);
   console.log(
     `▸ source ${sourceProbe.width}x${sourceProbe.height} @ ${sourceProbe.fps.toFixed(2)}fps · ${sourceProbe.duration.toFixed(2)}s`,
@@ -345,14 +617,61 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
     );
     for (const b of bloops) console.log(`  ▸ ${formatBloopSpan(transcript, b)}`);
   }
+  // Deterministic retake collapse (R27 §128) — the flub the speaker did NOT
+  // mark. Same RAW-transcript-before-repair ordering as the blooper marker
+  // above and for the same reason: repair reading a stray restart as an
+  // oddity would rewrite the exact pattern this looks for.
+  let retakeGroups = opts.collapseRetakes
+    ? findRetakeGroups(transcript, analysis, { transparentMarker: opts.blooperMarker })
+    : [];
+  let retakes = retakeGroups.flatMap((g) => g.cuts);
+  if (opts.collapseRetakes) {
+    // `exact` never cuts anything — buildCutlist's own early return collapses
+    // to one whole-duration `keep` regardless of what's in `retakes` — so
+    // "N group(s), M take(s) cut" here was a claim the run never honored.
+    // Same fact `valveFired` below already checks; gated the same way
+    // (final-review fix wave, cheap minor b).
+    if (opts.cleanup === "exact") {
+      console.log("▸ collapse-retakes: --cleanup exact wins — nothing cut");
+    } else {
+      console.log(
+        retakeGroups.length > 0
+          ? `▸ collapse-retakes: ${retakeGroups.length} group(s), ${retakes.length} take(s) cut`
+          : "▸ collapse-retakes: no retakes found",
+      );
+      for (const g of retakeGroups) {
+        for (const line of formatRetakeGroup(transcript, g).split("\n")) console.log(`  ▸ ${line}`);
+      }
+    }
+  }
   let cutlist: Segment[] = buildCutlist({
     transcript,
     analysis,
     duration: sourceProbe.duration,
     level: opts.cleanup,
     bloops,
+    retakes,
   });
   let map = new TimeMap(cutlist);
+  // Known limit (§128): the sanity valve can cancel a legitimate retake cut
+  // along with everything else if analysis went haywire elsewhere. Silence
+  // there would be wrong — a collapse the user asked for quietly vanished.
+  // Detected directly off buildCutlist's own valve shape (one `keep` segment
+  // spanning the whole duration) rather than "no retake reason survived":
+  // the merge step reassigns a removal's `reason` to whichever piece is
+  // LONGER when it folds two removals together (cutlist.ts, `curDur >
+  // prevDur`), so a retake genuinely cut but merged into a longer silence
+  // removal would read as "no retake reason survived" even though the cut
+  // happened — a false alarm the direct check can't produce.
+  // `exact` also collapses to this exact single-keep shape (buildCutlist's
+  // own early return) and is not the valve — "touch nothing" is the ask, not
+  // a failure, so it's excluded here rather than misreported as one.
+  const valveFired = opts.cleanup !== "exact" && cutlist.length === 1 && cutlist[0]!.kind === "keep";
+  if (retakes.length > 0 && valveFired) {
+    console.log(
+      "  ⚠ collapse-retakes found a retake, but the sanity valve reset the whole cutlist — nothing was cut",
+    );
+  }
 
   // ---- Transcript repair (FINDINGS §17/§21) --------------------------------
   // Deliberately AFTER the cutlist: the cut is computed from raw ASR, so the
@@ -587,6 +906,10 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
       // Re-detect on the SLICE: word indices moved, so the spans found against
       // the full take no longer address the same words.
       bloops = opts.blooperMarker ? findBloopSpans(rawTranscript, opts.blooperMarker) : [];
+      retakeGroups = opts.collapseRetakes
+        ? findRetakeGroups(rawTranscript, analysis, { transparentMarker: opts.blooperMarker })
+        : [];
+      retakes = retakeGroups.flatMap((g) => g.cuts);
       cutlist = boundCutlistToWindow(
         buildCutlist({
           transcript: rawTranscript,
@@ -594,6 +917,7 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
           duration: sourceProbe.duration,
           level: opts.cleanup,
           bloops,
+          retakes,
         }),
         clipWindow,
         sourceProbe.duration,
@@ -813,6 +1137,67 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
     if (varied > 0) console.log(`▸ ${varied} scene(s) re-laid out for variety`);
   }
 
+  // ---- The user's edit layer: loaded here for `cuts` (PLAN 2026-08-04
+  // Task 4) -------------------------------------------------------------
+  // Everything ELSE the doc carries (scene props, splits, retyped captions)
+  // still applies further down, AFTER assembly and routing, exactly as
+  // before this feature existed — see the comment there. `cuts` is the one
+  // exception: it changes `map` itself, and every downstream consumer of
+  // `map` below this point (assembly, captions, the zoom plan, render-props)
+  // must see the POST-cut timeline, so the file has to be read and the cut
+  // applied before any of that runs.
+  const overridesPath = join(work, "overrides.json");
+  let overrideDoc = emptyOverrideDoc();
+  if (existsSync(overridesPath)) {
+    const parsed = OverrideDocSchema.safeParse(
+      JSON.parse(await readFile(overridesPath, "utf8")),
+    );
+    if (!parsed.success) {
+      // Hand-editable user data: refuse rather than silently resetting it.
+      throw new Error(`${overridesPath} is not valid: ${parsed.error.message}`);
+    }
+    overrideDoc = parsed.data;
+  }
+  // `applyUserCuts`'s `priorMap`: a cut's `startSec`/`endSec` (when it has
+  // no `src` yet) and any already-re-anchored splits/pins are expressed
+  // relative to whatever render-props the user was LAST looking at, not the
+  // fresh automatic `map` this run just rebuilt — reusing `map` as "the
+  // frame the doc is in" gets it wrong the moment ANYTHING drifts (review
+  // fix wave finding 1 — confirmed for real on the dogfood workdir, where an
+  // unrelated blooper-matching change put "output 31s" 5.8s away from where
+  // the user actually pointed when they drew the cut). The PREVIOUS run's
+  // `render-props.json` is exactly that frame; `null` (no readable
+  // render-props.json — first-ever produce, or a corrupt workdir) is passed
+  // through as-is rather than defaulting to `map` — `applyUserCuts` needs to
+  // tell "no prior frame to compare against" apart from "available and
+  // happens to equal `map`" (finding 3's re-anchor gate depends on it).
+  const priorRenderProps = join(work, "render-props.json");
+  let priorMap: TimeMap | null = null;
+  if (existsSync(priorRenderProps)) {
+    try {
+      const prev = JSON.parse(await readFile(priorRenderProps, "utf8")) as { spans?: KeptSpan[] };
+      if (prev.spans) priorMap = mapFromKeptSpans(prev.spans);
+    } catch {
+      // Unreadable/corrupt — treated the same as no prior run.
+    }
+  }
+  const cutResult = applyUserCuts(overrideDoc, cutlist, map, priorMap);
+  cutlist = cutResult.cutlist;
+  map = cutResult.map;
+  overrideDoc = cutResult.doc;
+  if (overrideDoc.cuts.length > 0) {
+    console.log(
+      `▸ ${overrideDoc.cuts.length} user cut(s) removed ${cutResult.removedSec.toFixed(1)}s ` +
+        `of output (${map.outputDuration.toFixed(1)}s remaining)`,
+    );
+  }
+  // Printed regardless of `cutResult.changed`: a missing-render-props
+  // fallback (see `resolveCutSourceRanges`) is a decision worth saying out
+  // loud even on a run that ends up writing nothing. The actual
+  // `overrides.json` write — gated on `changed` — happens further down,
+  // beside `render-props.json`'s own write (see the comment there for why).
+  for (const r of cutResult.reports) console.log(`  ⚠ ${r}`);
+
   const { cues: assembled, dropped } = assembleScenes(scenes, transcript, map);
   for (const d of dropped) console.log(`  ⚠ scene ${d.id} dropped: ${d.reason}`);
 
@@ -858,6 +1243,12 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
   };
   /** The picture's dimensions — what every geometric consumer reasons about. */
   const content = { width: contentRect.w, height: contentRect.h };
+  // Computed ONCE and reused by both the accepted-side-image public-dir
+  // check below and the real mezzanine build further down — one boolean,
+  // not two independent copies of the same condition that could silently
+  // drift apart (Finding 3, final-review fix wave: that drift is exactly
+  // what let an accepted image 404 inside Remotion's staticFile()).
+  const mezzanineWillBuild = analysisInput === input && (opts.mezzanine || !contentRect.full);
 
   // Face measurement (FINDINGS §13): one static crop offset per source,
   // measured rather than guessed; cached in the workdir like the transcript.
@@ -980,24 +1371,19 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
   }
 
   // ---- The user's edit layer (SPEC: direct manipulation) -------------------
-  // Read AFTER assembly so hand edits sit on top of whatever the producer just
-  // planned, and never in production.json — that file is ours to overwrite.
-  const overridesPath = join(work, "overrides.json");
-  let overrideDoc = emptyOverrideDoc();
-  if (existsSync(overridesPath)) {
-    const parsed = OverrideDocSchema.safeParse(
-      JSON.parse(await readFile(overridesPath, "utf8")),
-    );
-    if (!parsed.success) {
-      // Hand-editable user data: refuse rather than silently resetting it.
-      throw new Error(`${overridesPath} is not valid: ${parsed.error.message}`);
-    }
-    overrideDoc = parsed.data;
-  }
+  // `overrideDoc` was already loaded above (before assembly, so `cuts` could
+  // reshape `map` in time) — applied here, AFTER assembly and routing, so
+  // hand edits sit on top of whatever the producer just planned. Never
+  // written to production.json — that file is ours to overwrite.
   const { cues: editedCues } = applyOverrides(routed.cues, overrideDoc);
   // Scenes the user deleted in the editor drop here — their windows become
   // plain takes in the fill below, which is Task C's payoff for Task A.
-  const { cues: visibleCues, hidden: hiddenIds } = dropHiddenCues(editedCues, overrideDoc);
+  // `splitThenDropHidden`, not a bare `dropHiddenCues`: this runs before
+  // `splitCues` below, so a hidden ROOT id (`scene-6`) used to erase its
+  // whole pre-split window — both the half it names and the half a stored
+  // split (R16 §61) had already carved off — before that split ever got a
+  // chance to separate them (PLAN 2026-08-04 Task 1, bug 3).
+  const { cues: visibleCues, hidden: hiddenIds } = splitThenDropHidden(editedCues, overrideDoc);
   if (hiddenIds.length > 0) {
     console.log(`▸ ${hiddenIds.length} scene(s) hidden by the edit layer: ${hiddenIds.join(", ")}`);
   }
@@ -1029,15 +1415,22 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
     clipStarts: map.spans.map((s) => s.outIn),
   });
   // User splits (R16 §61) — after the fill so takes split like scenes, and
-  // before the final override pass so edits on the `id@ms` halves land.
+  // before the final override pass so edits on the `id@ms` halves land. A
+  // split whose ROOT was a graphic scene already happened once inside
+  // `splitThenDropHidden` above (PLAN 2026-08-04 Task 1) — re-running it here
+  // is a no-op for that scene (the split point sits exactly on the joint
+  // between the two halves, matching neither), so this call stays the one
+  // that actually cuts TAKE ids, which don't exist until the fill just ran.
   const split = splitCues(filled, overrideDoc.splits);
   if (overrideDoc.splits.length > 0) {
     console.log(`▸ ${overrideDoc.splits.length} scene split(s) from the edit layer`);
   }
   const { cues: mergedCues, orphans: rawOrphans } = applyOverrides(split, overrideDoc);
-  // Halves the user deleted AFTER splitting: their hidden override targets an
-  // `id@ms` id that only exists post-split, so the first drop above never saw
-  // it. Same order as the editor's live memo.
+  // Halves of a TAKE the user deleted after splitting: a take id only exists
+  // once the fill above runs, so its `id@ms` half couldn't have been seen by
+  // `splitThenDropHidden` earlier (that pass only ever saw graphic scenes).
+  // Scene halves were already caught above; this is a no-op for them. Same
+  // order as the editor's live memo.
   const { cues: sceneCues, hidden: hiddenHalves } = dropHiddenCues(mergedCues, overrideDoc);
   if (hiddenHalves.length > 0) {
     console.log(`▸ ${hiddenHalves.length} split half(s) hidden by the edit layer`);
@@ -1110,27 +1503,132 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
   // render error, so the whole run died at 40% after four minutes of work.
   // The prop is optional and the component already draws a styled
   // placeholder without it, so dropping the bad reference degrades exactly
-  // the way the schema intended. Checked against the two directories that
-  // can become the render's public dir: the workdir (mezzanine path) and
-  // the source's own folder (--no-mezzanine).
-  const srcRejections: Array<{ sceneId: string; src: string }> = [];
+  // the way the schema intended. Checked against the directories that can
+  // become the render's public dir: the workdir (mezzanine path) and the
+  // source's own folder (--no-mezzanine) — which for a FOLDER run is
+  // `dirname(input)` no longer, review fix: `input` was already reassigned
+  // to `source-concat.mp4` inside `work` by this point, so `dirname(input)`
+  // IS `work` and that branch was silently checking the same directory
+  // twice. `originalInput` (the folder itself) is the natural place someone
+  // would actually drop an image for a folder run.
+  //
+  // Finding 3 (final-review fix wave): accepting an image from a sideDir is
+  // NOT the same as the render being able to load it — Remotion's
+  // `staticFile()` only ever looks in ONE directory, `dirname(renderVideo)`.
+  // `planRenderPublicDir` computes that same directory from the
+  // `mezzanineWillBuild` boolean set above (shared with the real
+  // `renderVideo` assignment further down, so the two can't disagree about
+  // which directory wins). An image accepted from a sideDir that isn't THAT
+  // directory used to pass this check and then 404 mid-render — a failure
+  // that surfaced only after the whole pipeline had already spent its budget
+  // getting there. The fix is to make the two agree by construction: copy
+  // the file into the render's public dir the moment it's accepted from
+  // anywhere else. This also retires the "latent" file-input+mezzanine case
+  // the reviewer found pre-existing: an image beside a source video that
+  // then gets mezzanine'd (the default) was accepted from `dirname(input)`
+  // but the mezzanine's public dir is `work` — same failure shape, one
+  // branch earlier.
+  //
+  // Second pass (Important, unsanitized copy destination): `src` drove a
+  // read-only `existsSync` before this fix, which was an acceptable risk;
+  // once it also drove `mkdirSync(recursive) + copyFileSync` destinations,
+  // an unconstrained LLM-authored string became a write primitive. Every
+  // `src` is checked with `isSafeScreenshotSrc` BEFORE the lookup (not just
+  // before the copy), and every copy lands under `SIDE_IMAGE_SUBDIR` via
+  // `planScreenshotSrcCopy` — see those two functions for why.
+  const srcRejections: Array<{
+    sceneId: string;
+    src: string;
+    reason: "unsafe" | "not-found" | "conflict";
+  }> = [];
+  const srcCopies: Array<{ src: string; from: string; destRel: string }> = [];
+  const sideDirs = isFolder ? [work, originalInput] : [work, dirname(input)];
+  const renderPublicDirPath = planRenderPublicDir({
+    input,
+    inputIsAnalysisInput: analysisInput === input,
+    mezzanineWillBuild,
+    work,
+  });
   for (const holder of [...scenes, ...graphicCues]) {
     const src = holder.props?.src;
     if (typeof src !== "string" || src.length === 0) continue;
-    if (existsSync(join(work, src)) || existsSync(join(dirname(input), src))) continue;
-    delete (holder.props as Record<string, unknown>).src;
-    srcRejections.push({ sceneId: holder.id, src });
+    // A remote URL is the renderer's job, not a file to look up or copy —
+    // see `isRemoteScreenshotSrc` for why this must come before the safe-src
+    // check (which would otherwise reject it with a misleading message).
+    if (isRemoteScreenshotSrc(src)) continue;
+    if (!isSafeScreenshotSrc(src)) {
+      delete (holder.props as Record<string, unknown>).src;
+      srcRejections.push({ sceneId: holder.id, src, reason: "unsafe" });
+      continue;
+    }
+    const foundDir = sideDirs.find((dir) => existsSync(join(dir, src)));
+    if (!foundDir) {
+      delete (holder.props as Record<string, unknown>).src;
+      srcRejections.push({ sceneId: holder.id, src, reason: "not-found" });
+      continue;
+    }
+    if (foundDir === renderPublicDirPath) continue; // already where the render will look
+    // `sideImageDestRel` is POSIX-literal (see its own comment for why);
+    // `destAbs` below is a normal `join()` since it IS a filesystem path,
+    // not a served URL.
+    const destRel = sideImageDestRel(src);
+    const destAbs = join(renderPublicDirPath, destRel);
+    const sourceAbs = join(foundDir, src);
+    const destExists = existsSync(destAbs);
+    const plan = planScreenshotSrcCopy({
+      exists: destExists,
+      identical: destExists && filesIdentical(sourceAbs, destAbs),
+    });
+    if (plan === "conflict") {
+      // A DIFFERENT file already answers to this basename in side-images/ —
+      // refuse rather than let one scene's image silently clobber another's
+      // (same "warn + drop" treatment as not-found, not an overwrite).
+      delete (holder.props as Record<string, unknown>).src;
+      srcRejections.push({ sceneId: holder.id, src, reason: "conflict" });
+      continue;
+    }
+    if (plan === "copy") {
+      mkdirSync(dirname(destAbs), { recursive: true });
+      copyFileSync(sourceAbs, destAbs);
+      srcCopies.push({ src, from: foundDir, destRel });
+    }
+    // `skip-identical` and `copy` both end with the file at `destAbs` —
+    // rewrite the prop so `staticFile()` resolves the NEW location, not the
+    // original bare name (which no longer lives at the public dir's root).
+    (holder.props as Record<string, unknown>).src = destRel;
   }
   for (const r of [...new Map(srcRejections.map((r) => [r.src, r])).values()]) {
+    const why =
+      r.reason === "unsafe"
+        ? "names a path, not a bare filename — refusing to let it drive a file lookup"
+        : r.reason === "conflict"
+          ? `a DIFFERENT file already answers to "${basename(r.src)}" in ${SIDE_IMAGE_SUBDIR}/`
+          : `not found in the workdir or ${isFolder ? "the source folder" : "beside the source video"}`;
+    console.log(`  ⚠ image "${r.src}" ${why} — rendering the frame as a placeholder instead`);
+  }
+  for (const c of [...new Map(srcCopies.map((c) => [c.src, c])).values()]) {
+    console.log(`  ▸ image "${c.src}" copied into ${c.destRel} (found in ${c.from})`);
+  }
+  // Audit fix: on a --no-mezzanine file run the render's public dir is the
+  // source video's OWN folder, so the copies above just wrote a
+  // `side-images/` subfolder into a directory the user owns — say so rather
+  // than leaving them to discover an unexplained folder beside their input.
+  if (srcCopies.length > 0 && renderPublicDirPath !== work) {
     console.log(
-      `  ⚠ image "${r.src}" does not exist beside the video — ` +
-        "rendering the frame as a placeholder instead",
+      `  ▸ note: rendering without a mezzanine serves images from the source's folder — ` +
+        `created ${SIDE_IMAGE_SUBDIR}/ in ${renderPublicDirPath}`,
     );
   }
 
   const production: Production = {
     version: 1,
-    source: { path: input, probe: sourceProbe, audioPath, face: faceBox },
+    // `originalInput`, not `input`: for a folder run `input` is by now
+    // `<workdir>/source-concat.mp4`, and `source.path` only feeds
+    // `report.txt`'s printed "source:" line (checked — nothing resolves a
+    // file against it) — so it should say what the user actually pointed
+    // produce at (final-review fix wave, cheap minor a), same fix shape as
+    // `defaultOutPath` above.
+    source: { path: originalInput, probe: sourceProbe, audioPath, face: faceBox },
     cleanup: opts.cleanup,
     intent: opts.intent,
     // The RAW transcript, because `analysis` and `cutlist` index into it —
@@ -1171,6 +1669,28 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
       bloops.map((b) => `  ${formatBloopSpan(rawTranscript, b)}`).join("\n") +
       "\n";
   }
+  // §128: same reasoning as §122's block above, for the flub the speaker did
+  // NOT say a marker over — kept / cut (with similarity) / ignored as a
+  // hallucination (with its silence fraction), in the words `report.txt`
+  // already trusts. Also the record `--collapse-retakes`'s opt-in default
+  // is promoted from: a clean run here is the evidence.
+  if (retakeGroups.length > 0) {
+    report +=
+      "\nretakes collapsed (--collapse-retakes — FINDINGS §128):\n" +
+      retakeGroups.map((g) => formatRetakeGroup(rawTranscript, g)).join("\n") +
+      "\n";
+  }
+  // PLAN 2026-08-04 Task 4: the removed ranges themselves are already in the
+  // report above (`formatCutReport` walks `production.cutlist`, and the
+  // subtracted spans carry `reason: "user"`) — this section is specifically
+  // for what a cut MOVED: a decision that landed on a cut edge must be
+  // visible here, never silently repositioned.
+  if (cutResult.changed && cutResult.reports.length > 0) {
+    report +=
+      "\noverrides re-anchored by your cut (nothing moved silently):\n" +
+      cutResult.reports.map((r) => `  ${r}`).join("\n") +
+      "\n";
+  }
   const landed = repairs.filter((r) => r.applied);
   if (landed.length > 0) {
     report +=
@@ -1324,7 +1844,11 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
   // A NORMALIZED source skips this outright: the bake already carries the
   // mezzanine's encode settings, and re-encoding it would be a second
   // generation of loss for nothing.
-  if (analysisInput === input && (opts.mezzanine || !contentRect.full)) {
+  // `mezzanineWillBuild` (computed once, above, with `contentRect`) — not a
+  // second copy of this condition — so this can't drift from what
+  // `planRenderPublicDir` already decided the accepted-image check against
+  // (Finding 3, final-review fix wave).
+  if (mezzanineWillBuild) {
     const mezz = join(work, contentRect.full ? "mezzanine.mp4" : "mezzanine-content.mp4");
     if (!existsSync(mezz)) {
       console.log(
@@ -1416,13 +1940,49 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
   };
   await writeFile(join(work, "render-props.json"), JSON.stringify(props, null, 2));
 
+  // The one sanctioned overrides.json write (PLAN 2026-08-04 Task 4; see
+  // `applyUserCuts`'s doc comment for why it's allowed at all) — computed
+  // way back when `cutResult` was built, but the actual write waits until
+  // HERE, immediately after `render-props.json`'s own write, deliberately
+  // adjacent (review fix wave finding 2). A crash or Ctrl-C anywhere in
+  // between (assembly, LLM captions, ffmpeg, face measurement — several
+  // hundred lines of I/O that can throw) used to be able to land between the
+  // OLD ordering's early overrides.json write and this one: overrides.json
+  // would already describe the NEW (post-cut) frame while render-props.json
+  // on disk still described the OLD one, so the NEXT run's `priorMap` —
+  // reconstructed from that stale render-props.json — would be off by
+  // exactly the cut's duration and silently double-shift every split and
+  // pin. Writing render-props.json FIRST means the worst a crash between the
+  // two can do is leave overrides.json one run stale relative to it — the
+  // next run's `priorMap` then sees drift and re-anchors again, the same
+  // recovery path finding 3 already has to support — never a false "nothing
+  // changed" that quietly corrupts positions.
+  if (cutResult.changed) {
+    // Keep a `.bak` of whatever was on disk first — the same safety net
+    // `saveConfigPatch` keeps for a config file it's about to replace —
+    // before overwriting the user's own data. Atomic write via tmp+rename,
+    // matching the edit server's own `PUT /overrides` handler: the producer
+    // or a live editor session may read this file at any moment, and a
+    // half-written document would be worse than a stale one.
+    try {
+      const raw = await readFile(overridesPath, "utf8");
+      await writeFile(`${overridesPath}.bak`, raw);
+    } catch {
+      // Nothing on disk to back up (first cut ever applied here) — fine.
+    }
+    const tmp = `${overridesPath}.tmp`;
+    await writeFile(tmp, JSON.stringify(overrideDoc, null, 2));
+    await rename(tmp, overridesPath);
+    console.log("▸ overrides.json re-anchored to the new cut and saved (previous copy kept as .bak)");
+  }
+
   if (!opts.render) {
     console.log(`▸ skipping render (--no-render). Props at ${join(work, "render-props.json")}`);
     console.log(editHint(work));
     return { workdir: work, rendered: false };
   }
 
-  const outPath = resolve(opts.out ?? input.replace(/(\.[^.]+)?$/, ".ossclip.mp4"));
+  const outPath = resolve(opts.out ?? defaultOutPath(originalInput));
   const rawPath = join(work, "render-raw.mp4");
   console.log("▸ rendering…");
   let lastPct = -10;