ossclip 0.1.25 → 0.1.27

package/src/produce.ts

@@ -1,7 +1,15 @@
 import { createHash } from "node:crypto";
 import { createReadStream } from "node:fs";
 import { copyFile, mkdir, readFile, writeFile, rm } from "node:fs/promises";
-import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync } from "node:fs";
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  statSync,
+} from "node:fs";
 import { cpus } from "node:os";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { z } from "zod/v4";
@@ -29,8 +37,13 @@ import {
   concatFolder,
   folderManifestKey,
   listFolderVideos,
+  outInsideInputFolderMessage,
+  outPathInsideInput,
+  COVER_PROVENANCE_BASENAME,
   coverDecision,
   coverHeadline,
+  readCoverProvenance,
+  writeCoverProvenance,
   cropFilter,
   detectContentRect,
   letterboxedSeconds,
@@ -79,6 +92,7 @@ import {
   thumbnailDecision,
   thumbnailImageCacheName,
   applyUserCuts,
+  pruneHidesInsideCuts,
   loadConfig,
   loudnorm,
   MAX_NORMALIZE_UPSCALE,
@@ -132,6 +146,7 @@ import {
   type Layout,
   type LlmProvider,
   type Production,
+  ossclipOutputPathFor,
   type ProviderName,
   type Scene,
   type SceneComponentId,
@@ -153,6 +168,13 @@ import {
   workdirBaseName,
 } from "./stranded-overrides";
 import { editHint } from "./interactive/edit-hint";
+import {
+  COVER_FRAME_BASENAME,
+  buildCoverRender,
+  coverBannerText,
+  coverTextHold,
+  provenanceVideoPath,
+} from "./cover";
 import { artifactPath, ensureParentDir, expandHome, moveFile } from "./paths";
 import { portraitOverridePath, resolvePortrait } from "./portrait-override";
 import { approveThumbnailConcept, thumbnailRetryLoop } from "./interactive/thumbnail-approve";
@@ -161,7 +183,8 @@ import { RenderTimelineHUD, StageAnimator, printProductionCompleteBanner } from
 import { reconcileCaptionEdits } from "./caption-report";
 import { overridesWriteLine, writeOverrideDoc } from "./overrides-write";
 import { recordedProduceArgs } from "./replay-argv";
-import { renderCover, renderProduction } from "@ossclip/renderer";
+import { makeCancelSignal, renderCover, renderProduction } from "@ossclip/renderer";
+import type { RenderPhase } from "@ossclip/renderer";
 import {
   DEFAULT_FACE,
   coverTextRect,
@@ -293,6 +316,12 @@ export interface ProduceOptions {
   cover?: boolean;
   /** Explicit cover output path, overriding <out>.cover.jpg. */
   coverPath?: string;
+  /**
+   * `--cover-text-reset` — opt back into the GENERATED cover headline on a
+   * workdir whose `cover.json` holds a user-typed one (`coverTextHold`).
+   * Deleting `cover.json` does the same thing.
+   */
+  coverTextReset?: boolean;
   /** Treat the source as an already-edited reel with burned-in graphics. */
   sourceIsEdited?: boolean;
   /**
@@ -321,6 +350,13 @@ export interface ProduceOptions {
    * platform chrome to dodge and a landscape source needs no cropping at all.
    */
   aspect?: "9:16" | "16:9";
+  /**
+   * `--concurrency <n>`: how many browser tabs the render opens at once,
+   * beating the config's `renderConcurrency` and the cpus-2 default
+   * (`resolveRenderConcurrency`). Already validated by commander
+   * (`concurrencyFlag`), so a number here is always a positive integer.
+   */
+  concurrency?: number;
   /**
    * `--clip <seconds>` (R19 §93): produce only the strongest ~N-second window
    * of a long take, chosen by the producer in the same editorial call as the
@@ -449,21 +485,37 @@ export function resolveYoutube(
 
 /**
  * How many browser tabs the render runs in parallel (2026-08-17 render-speed
- * pass). Default is cpus-2 with a floor of 2: the render is decode-bound —
- * every tab waits on OffthreadVideo's ffmpeg extract workers — so saturating
- * all cores with tabs starves the very processes the tabs block on. The
- * config's `renderConcurrency` overrides for machines where that guess is
- * wrong; validated here at the consumer (the `dictionary` posture: the value
- * comes from hand-editable JSON loadConfig doesn't zod-parse), a positive
- * integer or one warning and the default — never a coerced tab count. Pure
- * so the config × cpu matrix is testable without a config file or real
+ * pass). Precedence: `--concurrency` beats the config's `renderConcurrency`
+ * beats the cpus-2 default (floor 2). The default is cpus-2 because the
+ * render is decode-bound — every tab waits on OffthreadVideo's ffmpeg extract
+ * workers — so saturating all cores with tabs starves the very processes the
+ * tabs block on.
+ *
+ * The flag exists because cpus-2 is a CPU guess with no memory term in it
+ * (2026-08-19 field case): a 14-core / 36GB Mac resolved to 12 tabs on a
+ * 1080×1920 source and Chrome died WHOLE, twelve in-flight frames at a time.
+ * `offthreadVideoCacheSizeInBytes` bounds the cache side of that
+ * (render-options.ts); this is the hatch for the tab side, typed per run
+ * rather than edited into a config file mid-investigation.
+ *
+ * The flag arrives already validated by commander (`concurrencyFlag` in
+ * program.ts rejects a non-positive/non-integer at the front door, §93a), so
+ * only the config value is checked here — the `dictionary` posture, since it
+ * comes from hand-editable JSON loadConfig doesn't zod-parse: a positive
+ * integer, or one warning and the default, never a coerced tab count. Pure so
+ * the flag × config × cpu matrix is testable without a config file or real
  * cpus().
  */
 export function resolveRenderConcurrency(
+  flagValue: number | undefined,
   configValue: unknown,
   cpuCount: number,
 ): { concurrency: number; warning?: string } {
   const fallback = Math.max(2, cpuCount - 2);
+  // Typed-beats-config, and typed also beats a MALFORMED config: the user
+  // asking for 4 tabs on the command line gets 4, not a warning about a
+  // config key they did not touch this run.
+  if (flagValue !== undefined) return { concurrency: flagValue };
   if (configValue === undefined) return { concurrency: fallback };
   if (typeof configValue === "number" && Number.isInteger(configValue) && configValue > 0) {
     return { concurrency: configValue };
@@ -474,6 +526,119 @@ export function resolveRenderConcurrency(
   };
 }
 
+/** What a signal that interrupted the render phase costs the caller. */
+export interface RenderCancellation {
+  /** Partial render output to delete before exiting. */
+  removePaths: string[];
+  /** Shell convention: 128 + the signal's number (SIGINT 2, SIGTERM 15). */
+  exitCode: number;
+  message: string;
+}
+
+/**
+ * The decision half of Ctrl-C-cancels-the-render (2026-08-19 field report:
+ * "Cancelling rerendering doesn't work" — nothing in the CLI handled SIGINT,
+ * and no cancelSignal reached Remotion, so the browser and its ffmpeg
+ * children kept going after the process was told to stop). The signal wiring
+ * itself is I/O and lives at the render call site; what to delete and what to
+ * exit with is decided here so it can be tested without a real render.
+ *
+ * `rawPath` is the workdir's `render-raw.mp4`, which a finished run
+ * loudnorms and only THEN moves to the user's --out — so a cancel never has
+ * an output file to mistake for a finished render. The raw partial is deleted
+ * anyway: it is a truncated mp4 sitting in the workdir under the name the
+ * next run reads, and a stale one there is the kind of thing that gets picked
+ * up by hand and mailed to someone.
+ *
+ * Non-zero exit, because a cancelled render did not produce the video the
+ * caller asked for — but 130/143 rather than 1, so a script can tell a
+ * deliberate stop from a failure (the same distinction the editor's
+ * /api/render/cancel draws, R16 §60).
+ */
+export function renderCancellation(
+  signal: "SIGINT" | "SIGTERM",
+  rawPath: string,
+): RenderCancellation {
+  return {
+    removePaths: [rawPath],
+    exitCode: signal === "SIGINT" ? 130 : 143,
+    message: "▸ cancelled — partial output discarded",
+  };
+}
+
+/**
+ * Where the run is when a signal lands, collapsed to the three cases that
+ * behave differently. `RenderPhase`'s "bundling" and "selecting" both collapse
+ * to "pre-render": neither takes a cancelSignal, so neither can be stopped
+ * cooperatively. "post-render" is the window between `renderMedia` resolving
+ * and the handlers coming off in the `finally`.
+ */
+export type RenderSignalPhase = "pre-render" | "rendering" | "post-render";
+
+/** Map the renderer's phase report onto what a signal can do about it. */
+export function renderSignalPhaseOf(phase: RenderPhase): RenderSignalPhase {
+  return phase === "rendering" ? "rendering" : "pre-render";
+}
+
+/** What the SIGINT/SIGTERM handler should do about the signal it just got. */
+export interface RenderSignalAction {
+  /** Fire the Remotion cancel signal. Free, and only `renderMedia` listens. */
+  cancel: boolean;
+  /**
+   * Tear down and `process.exit` from INSIDE the handler, because nothing
+   * downstream is going to stop on its own.
+   */
+  exitNow: boolean;
+  /** Printed above the cancellation message when the exit needs explaining. */
+  note?: string;
+}
+
+/**
+ * The decision half of "Ctrl-C must never be a no-op" (2026-08-19 review of
+ * the cancel feature). Registering a SIGINT listener SUPPRESSES node's default
+ * terminate, so the cancel feature as first written made Ctrl-C *worse* than
+ * before it existed in every phase the cancelSignal does not reach:
+ *
+ *  - "pre-render" — `bundle()` and `selectComposition()` take no cancelSignal
+ *    in @remotion/renderer 4.0.499 (verified against the installed types; see
+ *    RenderPhase in @ossclip/renderer). A cold bundle is tens of seconds, and
+ *    minutes when Chrome is downloaded on first run, and for all of it Ctrl-C
+ *    did NOTHING while the terminal looked hung. The handler must exit itself.
+ *    That can orphan the Chrome `selectComposition` opened — but a bare Ctrl-C
+ *    before the cancel feature did exactly the same, so it is not a
+ *    regression, and a terminal that ignores Ctrl-C is worse than a stray
+ *    browser process.
+ *  - "rendering" — the one phase that IS cooperative: fire the signal and let
+ *    Remotion tear the browser and its ffmpeg children down.
+ *  - "post-render" — HONORED, not ignored: the caller stops before mastering
+ *    and discards the raw render (see the tail check at the render call site).
+ *
+ * SECOND SIGNAL ALWAYS EXITS, in every phase. If Remotion's teardown wedges,
+ * the user's only remaining move must not be `kill -9` from another terminal.
+ */
+export function renderSignalAction(
+  phase: RenderSignalPhase,
+  signalCount: number,
+): RenderSignalAction {
+  if (signalCount >= 2) {
+    return {
+      cancel: true,
+      exitNow: true,
+      note: "▸ second signal — exiting without waiting for the render to shut down",
+    };
+  }
+  if (phase === "pre-render") {
+    return {
+      cancel: true,
+      exitNow: true,
+      note:
+        "▸ cancelled while preparing the render — that phase cannot be interrupted " +
+        "cleanly, so stopping the process",
+    };
+  }
+  return { cancel: true, exitNow: false };
+}
+
 // Moved to paths.ts (2026-08-17, editor thumbnail panel): the edit server
 // derives `<out>.thumbnail.png` from command.json's recorded out and must not
 // import this module — produce.ts imports edit.ts (recordRecentProject), so
@@ -1209,7 +1374,34 @@ function deriveWorkdir(
  * file input's equivalent default already lands.
  */
 export function defaultOutPath(originalInput: string): string {
-  return originalInput.replace(/(\.[^.]+)?$/, ".ossclip.mp4");
+  // Delegates to core so the refusal message's suggestion and the actual
+  // default can never drift apart (and both strip the tab-completed trailing
+  // slash — the 2026-08-18 hidden-dotfile-inside-the-folder field case).
+  return ossclipOutputPathFor(originalInput);
+}
+
+/**
+ * The ⚠ line a REPLAYED produce prints when it keys to a different workdir
+ * than the one the editor launched it for (2026-08-18 field cascade, part
+ * 3): the edit server sets OSSCLIP_REPLAY_WORKDIR to the workdir whose
+ * command.json it is replaying; if the run then derives another workdir —
+ * the folder's content changed since the record — the edits saved in the
+ * old workdir's overrides.json silently stop applying, and nothing else in
+ * the run says so. Pure (drift decision in, line out) so the comparison is
+ * testable without spawning a replay; null when this isn't a replay or
+ * nothing drifted.
+ */
+export function replayWorkdirWarning(
+  replayedWorkdir: string | undefined,
+  derivedWorkdir: string,
+): string | null {
+  if (replayedWorkdir === undefined || replayedWorkdir === "") return null;
+  if (resolve(replayedWorkdir) === resolve(derivedWorkdir)) return null;
+  return (
+    `⚠ this run's workdir differs from the one the editor replayed — edits ` +
+    `saved in ${join(replayedWorkdir, "overrides.json")} will NOT apply to ` +
+    `this render (the input's content changed since that command was recorded)`
+  );
 }
 
 /**
@@ -1415,6 +1607,9 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
     : resolve(baseCwd, expandHome(inputArg));
   let input = originalInput;
   if (!existsSync(input)) throw new Error(`input not found: ${input}`);
+  // Decided once, here — the out-path gate below and the folder pipeline
+  // further down must read the same answer to "is this a folder run".
+  const isFolder = statSync(input).isDirectory();
 
   // §93b: the window is an editorial judgement, and there is deliberately no
   // heuristic fallback — an automatically-guessed 60 seconds reads as a bug,
@@ -1449,6 +1644,17 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
       ? outArg
       : resolve(baseCwd, outArg)
     : resolve(defaultOutPath(originalInput));
+  // 2026-08-18 field cascade: an --out pointed INSIDE the input folder became
+  // a 7th source clip on the next run — new content hash, fresh workdir,
+  // EMPTY overrides — so the render silently dropped the user's saved edits
+  // and the output duration doubled, three runs in a row. Refused BEFORE
+  // ensureParentDir so the gate can't first mkdir a stray subfolder inside
+  // the very input it is about to refuse. (Unreachable via the default out —
+  // defaultOutPath lands BESIDE the folder — so only a typed --out can trip
+  // it.)
+  if (isFolder && outPathInsideInput(outPath, originalInput)) {
+    throw new Error(outInsideInputFolderMessage(originalInput));
+  }
   ensureParentDir(outPath);
 
   await preflight(cfg.ffmpegPath, "Run `ossclip setup`, install ffmpeg yourself (brew/apt/winget), or set OSSCLIP_FFMPEG.");
@@ -1489,7 +1695,7 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
   // 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();
+  // (`isFolder` itself is decided up top, beside the out-path gate.)
   // 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
@@ -1518,6 +1724,10 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
   );
   await mkdir(work, { recursive: true });
   console.log(`▸ workdir ${work}`);
+  // See replayWorkdirWarning — set only by the edit server's /api/render
+  // spawn, so a terminal run never sees it.
+  const replayWarning = replayWorkdirWarning(process.env.OSSCLIP_REPLAY_WORKDIR, work);
+  if (replayWarning !== null) console.log(replayWarning);
 
   // §131 residue: a folder re-key (clips renamed/added/removed → new content
   // hash) correctly lands in a fresh workdir, but any editor edits saved in
@@ -1566,6 +1776,17 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
         `  ${result.nonVideoCount} non-video file${result.nonVideoCount === 1 ? "" : "s"} ignored`,
       );
     }
+    // Loud, not folded into the non-video count (2026-08-18 field cascade):
+    // an ossclip output sitting in the clips folder means an earlier run
+    // wrote it there, and the user should learn that before it surprises
+    // them elsewhere. The filter itself is pure (isOssclipOutputName) and
+    // runs inside listFolderVideos, before the workdir hash is derived.
+    if (result.ossclipOutputCount > 0) {
+      console.log(
+        `▸ folder: skipped ${result.ossclipOutputCount} ossclip output ` +
+          `file${result.ossclipOutputCount === 1 ? "" : "s"}`,
+      );
+    }
     // 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) => {
@@ -1893,17 +2114,37 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
       .slice(0, 8);
     const repairCache = join(work, `repairs-${rawKey}.json`);
     if (existsSync(repairCache)) {
-      repairs = JSON.parse(await readFile(repairCache, "utf8")) as AppliedRepair[];
-      transcript = applyRepairs(
+      const cached = JSON.parse(await readFile(repairCache, "utf8")) as AppliedRepair[];
+      // Re-DECIDE from the cached PROPOSALS; never replay the stored verdicts
+      // (field case 2026-08-18). What this cache exists to avoid is the LLM
+      // CALL — the gates are code, and code gets fixed. Filtering to
+      // `r.applied` here meant a gate fix could never reach a workdir that had
+      // already cached a refusal: the Urdu run whose 11 correct repairs stayed
+      // refused after the Latin-only `norm` was fixed, because produce replayed
+      // the old verdicts instead of recomputing them. The vouched set rides
+      // along for the same reason it always did — a dictionary-vouched
+      // correction must clear the phonetic gate on replay too.
+      const decided = applyRepairs(
         rawTranscript,
-        repairs.filter((r) => r.applied),
-        // The vouched set must survive the cache: a dictionary-vouched
-        // correction re-runs applyRepairs' guards here, and without the
-        // dictionary the phonetic gate would refuse on replay what it
-        // accepted on the first run.
+        cached.map(({ startWord, endWord, heard, correction }) => ({
+          startWord,
+          endWord,
+          heard,
+          correction,
+        })),
         { dictionary },
-      ).transcript;
-      console.log(`▸ repairs cached (${repairs.filter((r) => r.applied).length})`);
+      );
+      repairs = decided.applied;
+      transcript = decided.transcript;
+      const now = repairs.filter((r) => r.applied).length;
+      const before = cached.filter((r) => r.applied).length;
+      // Re-decided verdicts are the truth from here on: persist them so the
+      // report, the next run and this run cannot disagree about what applied.
+      if (now !== before) await writeFile(repairCache, JSON.stringify(repairs, null, 2));
+      console.log(
+        `▸ repairs cached (${now} applied of ${cached.length} proposed` +
+          `${now === before ? "" : `, re-decided from ${before}`})`,
+      );
     } else {
       const repairAnim = isInteractive()
         ? new StageAnimator(
@@ -2431,6 +2672,23 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
   // beside `render-props.json`'s own write (see the comment there for why).
   for (const r of cutResult.reports) console.log(`  ⚠ ${r}`);
 
+  // Retire hides whose words this run's FINAL cutlist removes (§59b
+  // revisited): the "captions + video" delete writes a hide (instant
+  // preview) plus a cut (this run), and once the cut lands the cut
+  // supersedes the hide — see `pruneHidesInsideCuts`. Pruned HERE, before
+  // `reconcileCaptionEdits` applies the hide layer, so the retired keys
+  // never surface as "the cut removed it" drop lines on this or any later
+  // run. The doc write itself goes through the one sanctioned overrides.json
+  // write further down, gated alongside `cutResult.changed`.
+  const hidePrune = pruneHidesInsideCuts(overrideDoc, cutlist);
+  overrideDoc = hidePrune.doc;
+  const hidesPruned = hidePrune.pruned.length > 0;
+  if (hidesPruned) {
+    console.log(
+      `▸ captions: ${hidePrune.pruned.length} hidden-word override(s) retired — their words are cut`,
+    );
+  }
+
   const { cues: assembled, dropped } = assembleScenes(scenes, transcript, map);
   for (const d of dropped) console.log(`  ⚠ scene ${d.id} dropped: ${d.reason}`);
 
@@ -3537,7 +3795,13 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
   // recovered from (`legacySplitId`). Repairing the captions would destroy the
   // evidence for the split. `writeOverrideDoc` carries the full argument for
   // why a caption-only write has nothing worth backing up.
-  if (cutResult.changed || captionKeysReanchored) {
+  // `hidesPruned` joins the gate for the same reason `captionKeysReanchored`
+  // did: a hide retired by its own cut (`pruneHidesInsideCuts`) changes the
+  // doc without changing the cut entries, and skipping the write would
+  // re-report "the cut removed it" on every later run. It does NOT spend the
+  // `.bak` — retiring a redundant key is not the cut re-anchoring the backup
+  // exists to survive.
+  if (cutResult.changed || captionKeysReanchored || hidesPruned) {
     await writeOverrideDoc(overridesPath, overrideDoc, { refreshBackup: cutResult.changed });
     console.log(overridesWriteLine(cutResult.changed));
   }
@@ -3664,6 +3928,18 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
     }
   }
 
+  // --concurrency, else config renderConcurrency, else cpus-2 with a floor of
+  // 2 (resolveRenderConcurrency has the precedence and the why: leave cores
+  // for the ffmpeg decode workers every tab waits on). Resolved BEFORE the log
+  // line below so the count can go INTO it — the 2026-08-19 whole-browser OOM
+  // took a machine spec and arithmetic to diagnose, because no line of the
+  // render's own output ever said how many tabs it opened.
+  const renderConcurrency = resolveRenderConcurrency(
+    opts.concurrency,
+    cfg.renderConcurrency,
+    cpus().length,
+  );
+  if (renderConcurrency.warning) console.log(renderConcurrency.warning);
   let renderHud: RenderTimelineHUD | null = null;
   if (interactive) {
     renderHud = new RenderTimelineHUD({
@@ -3673,33 +3949,109 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
       aspect: landscape ? "16:9" : "9:16",
     }).start();
   } else {
-    console.log("▸ rendering…");
+    console.log(`▸ rendering… (${renderConcurrency.concurrency} parallel tabs)`);
   }
   let lastPct = -10;
-  // cpus-2 with a floor of 2 (resolveRenderConcurrency has the why: leave
-  // cores for the ffmpeg decode workers every tab waits on). Resolved here,
-  // next to the call it feeds, so the warning prints once per run.
-  const renderConcurrency = resolveRenderConcurrency(cfg.renderConcurrency, cpus().length);
-  if (renderConcurrency.warning) console.log(renderConcurrency.warning);
-  await phases.time("render", () =>
-    renderProduction(props, {
-      publicDir: dirname(renderVideo),
-      outPath: rawPath,
-      browserExecutable: cfg.browserExecutable,
-      concurrency: renderConcurrency.concurrency,
-      onProgress: (p) => {
-        if (renderHud) {
-          renderHud.setProgress(p);
-        } else {
-          const pct = Math.floor(p * 100);
-          if (pct >= lastPct + 10) {
-            lastPct = pct;
-            process.stdout.write(`  ${pct}%\n`);
+  // Ctrl-C must actually stop the render (2026-08-19 field report). Remotion
+  // owns a browser and ffmpeg children that outlive a bare process death, so
+  // stopping means handing renderMedia a cancelSignal and firing it — node's
+  // default SIGINT handling would leave those orphaned.
+  //
+  // Registered around the RENDER PHASE ONLY, and removed in the finally: a
+  // handler that outlived this phase would swallow Ctrl-C during the LLM and
+  // whisper phases, which exit promptly today and must keep doing so.
+  //
+  // SIGTERM is wired for the same reason as SIGINT, plus one of its own: the
+  // editor's /api/render/cancel (edit.ts) kills this process as a child, and
+  // before this handler that kill left the browser behind. That path is
+  // otherwise untouched — it already reports its own cancel. It also inherits
+  // the dead-window fix below: the editor's Cancel button now kills the child
+  // DURING bundling too, where the SIGTERM used to be swallowed and
+  // /api/render kept answering 409 until the bundle finished on its own.
+  const renderCancel = makeCancelSignal();
+  // An array, not a `let`: the handler assigns from inside a closure, and TS's
+  // flow analysis would still read a `let` as null in the catch below (it
+  // narrowed the branch to `never`). First signal wins — hammering Ctrl-C must
+  // not rewrite the verdict while the teardown is already running.
+  const cancellations: RenderCancellation[] = [];
+  // Where renderProduction is, so the handler knows whether the cancel signal
+  // has anyone listening (renderSignalAction has the whole reasoning).
+  // "pre-render" from the start: the handlers go on before the call.
+  let signalPhase: RenderSignalPhase = "pre-render";
+  let signalCount = 0;
+  // Shared by all three places a cancel is finalised — the handler, the
+  // rejected-render catch, and the post-render tail check.
+  const finishCancel = (c: RenderCancellation, note?: string): never => {
+    if (renderHud) renderHud.stop();
+    if (note) console.log(note);
+    // rmSync, not fs/promises rm: the handler path calls this and exits on the
+    // next statement, and an awaited unlink would never get its turn.
+    for (const path of c.removePaths) rmSync(path, { force: true });
+    console.log(c.message);
+    // Exits here rather than throwing: program.ts's catch would record this as
+    // produce_failed and print "✗ <message>", dressing a deliberate stop as a
+    // bug (R16 §60's distinction).
+    process.exit(c.exitCode);
+  };
+  const onCancelSignal = (signal: "SIGINT" | "SIGTERM") => {
+    signalCount += 1;
+    if (cancellations.length === 0) cancellations.push(renderCancellation(signal, rawPath));
+    const action = renderSignalAction(signalPhase, signalCount);
+    if (action.cancel) renderCancel.cancel();
+    if (action.exitNow) finishCancel(cancellations[0]!, action.note);
+  };
+  const onSigint = () => onCancelSignal("SIGINT");
+  const onSigterm = () => onCancelSignal("SIGTERM");
+  process.on("SIGINT", onSigint);
+  process.on("SIGTERM", onSigterm);
+  try {
+    await phases.time("render", () =>
+      renderProduction(props, {
+        publicDir: dirname(renderVideo),
+        outPath: rawPath,
+        browserExecutable: cfg.browserExecutable,
+        concurrency: renderConcurrency.concurrency,
+        cancelSignal: renderCancel.cancelSignal,
+        onPhase: (phase: RenderPhase) => {
+          signalPhase = renderSignalPhaseOf(phase);
+        },
+        onProgress: (p) => {
+          if (renderHud) {
+            renderHud.setProgress(p);
+          } else {
+            const pct = Math.floor(p * 100);
+            if (pct >= lastPct + 10) {
+              lastPct = pct;
+              process.stdout.write(`  ${pct}%\n`);
+            }
           }
-        }
-      },
-    }),
-  );
+        },
+      }),
+    );
+    // renderMedia resolved, so nothing is left to cancel cooperatively. Not a
+    // phase the handler can exit from either — see the tail check below.
+    signalPhase = "post-render";
+  } catch (err) {
+    // A cancelled renderMedia rejects like any other failure; only the
+    // handler above can tell the two apart.
+    const cancellation = cancellations[0];
+    if (!cancellation) throw err;
+    finishCancel(cancellation);
+  } finally {
+    process.off("SIGINT", onSigint);
+    process.off("SIGTERM", onSigterm);
+  }
+  // The TAIL CASE (2026-08-19 review): a signal landing after renderMedia
+  // resolved but before the `finally` above took the handlers off used to be
+  // swallowed outright — nothing threw, the run went on to loudnorm and
+  // mastering, and the user got a complete video having pressed Ctrl-C. We
+  // HONOR it: the user asked to stop, and stopping here costs only the
+  // mastering pass, whereas ignoring it hands them the file they just said
+  // they did not want. Nothing has been written to --out yet (moveFile is
+  // below), so honoring here is still "no output", the same promise every
+  // other cancel makes.
+  const tailCancellation = cancellations[0];
+  if (tailCancellation) finishCancel(tailCancellation);
   if (renderHud) renderHud.stop();
 
   const masterAnim = interactive
@@ -3725,7 +4077,20 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
   {
     // §35's cap applies here too: a cached beat sheet from before the fix, or
     // the hook fallback, must not slip a 13-word paragraph onto a thumbnail.
-    const coverText = coverHeadline(beatSheet?.coverText ?? beatSheet?.hook ?? "");
+    const generatedCoverText = coverHeadline(beatSheet?.coverText ?? beatSheet?.hook ?? "");
+    // A headline someone typed (`ossclip cover --text`, or the editor) is a
+    // user-owned file, exactly like overrides.json and the approved thumbnail
+    // concept: this run does NOT quietly replace it with a fresh beat sheet's
+    // coverText. Read before the decision below, because it decides the text
+    // the decision is made about.
+    const priorCover = await readCoverProvenance(work);
+    const heldCover = coverTextHold({
+      generated: generatedCoverText,
+      persisted: priorCover,
+      reset: opts.coverTextReset === true,
+    });
+    if (heldCover.message) console.log(heldCover.message);
+    const coverText = heldCover.text;
     // Urdu field run 2026-08-05: a run without --produce has no hook text,
     // and skipping the cover for that threw away the part that never needed
     // text — the sharpness-scored face frame. No headline now means a bare
@@ -3752,7 +4117,7 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
       if (!pick) {
         console.log("▸ no usable cover frame found — skipping cover");
       } else {
-        const frameName = "cover-frame.png";
+        const frameName = COVER_FRAME_BASENAME;
         await run(cfg.ffmpegPath, [
           "-v", "error",
           "-ss", pick.timeSec.toFixed(3),
@@ -3786,16 +4151,26 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
             `▸ cover from ${pick.timeSec.toFixed(1)}s ` +
               `(${pick.hasFace ? "face" : "no face"}, sharpness ${pick.sharpness.toFixed(0)})…`,
           );
-          if (sourceTitled) {
-            console.log("  ▸ source already has a title in this frame — shipping it without a banner");
-          } else if (pick.face) {
+          // …unless the headline is the user's own, which §34 does not get to
+          // erase (cover.ts's coverBannerText has the reasoning). Unchanged
+          // for a generated headline, including the line it prints.
+          const banner = coverBannerText({
+            text: coverText,
+            textSource: heldCover.textSource,
+            sourceTitled,
+          });
+          if (banner.note) console.log(banner.note);
+          // The band log is about routing a banner around the face, so it
+          // follows whether there IS a banner — for a §34-suppressed cover
+          // there is none, for a surviving user headline there is.
+          if (banner.text !== "" && pick.face) {
             const band = coverTextRect(pick.face, frame);
             console.log(
               `  ▸ banner in the ${band.y + band.h / 2 < pick.face.centerYFrac ? "band above" : "band below"} ` +
                 `the face (${(band.y * 100).toFixed(0)}-${((band.y + band.h) * 100).toFixed(0)}%)`,
             );
           }
-          bannerText = sourceTitled ? "" : coverText;
+          bannerText = banner.text;
         } else {
           console.log(
             `▸ cover from ${pick.timeSec.toFixed(1)}s ` +
@@ -3803,22 +4178,71 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
               `— no banner text (run --produce for one)`,
           );
         }
-        await renderCover(
-          {
-            frameFileName: frameName,
-            text: bannerText,
-            // The RESOLVED theme — so the cover's banner already carries the
-            // config theme (F6) via resolveTheme's base, no separate wiring.
-            theme,
-            face: pick.face,
-            // The cover is the OUTPUT's thumbnail — a landscape render gets a
-            // landscape cover (R16 §76). The still was already extracted at
-            // this size; only the composition disagreed.
-            frame: { width: frame.width, height: frame.height },
-          },
-          { publicDir: work, outPath: coverPath, browserExecutable: cfg.browserExecutable },
-        );
+        // The shared builder, not an inline props literal: `ossclip cover`
+        // and the editor's regenerate endpoint call the same one, and two
+        // spellings of these arguments drifting apart is the defect that
+        // whole feature exists to prevent (cover.ts).
+        const coverRender = buildCoverRender({
+          frameFileName: frameName,
+          text: bannerText,
+          // The RESOLVED theme — so the cover's banner already carries the
+          // config theme (F6) via resolveTheme's base, no separate wiring.
+          theme,
+          face: pick.face,
+          // The cover is the OUTPUT's thumbnail — a landscape render gets a
+          // landscape cover (R16 §76). The still was already extracted at
+          // this size; only the composition disagreed.
+          frame: { width: frame.width, height: frame.height },
+          publicDir: work,
+          outPath: coverPath,
+          browserExecutable: cfg.browserExecutable,
+        });
+        await renderCover(coverRender.props, coverRender.opts);
         console.log(`✓ cover → ${coverPath}`);
+        // Provenance, so the next headline change costs seconds instead of a
+        // full re-render. Written AFTER the render succeeded and describing
+        // what that render actually used — `pick.face` is the cover-crop
+        // geometry nothing else on disk carries, and `cropVf` is not
+        // reconstructible from the workdir either.
+        //
+        // Additive by contract (§112, the posture the YouTube pack block
+        // below states): the video and the cover are already on disk, so a
+        // failed sidecar write is one loud line, never a dead run.
+        try {
+          await writeCoverProvenance(work, {
+            version: 1,
+            text: bannerText,
+            // "user" only when THIS run kept a headline someone typed
+            // (coverTextHold above) — produce itself never authors one.
+            textSource: heldCover.textSource,
+            frame: {
+              // produce keeps picking from the SOURCE — zero perturbation for
+              // existing users. `ossclip cover` is the one that defaults to
+              // the finished render.
+              source: "source",
+              timeSec: pick.timeSec,
+              face: pick.face ?? null,
+              hasFace: pick.hasFace,
+              sharpness: pick.sharpness,
+              fileName: frameName,
+              // Workdir-relative when the video IS a workdir intermediate (a
+              // folder run's concat mezzanine), absolute otherwise — the rule
+              // `ossclip cover` reads it back with.
+              sourceVideo: provenanceVideoPath(work, input),
+              // cropFilter returns "" for an uncropped source; null says "no
+              // crop" without a caller having to know that convention.
+              cropVf: cropVf || null,
+            },
+            size: { width: frame.width, height: frame.height },
+            out: coverPath,
+          });
+        } catch (err) {
+          console.log(
+            `  ⚠ could not write ${COVER_PROVENANCE_BASENAME} ` +
+              `(${err instanceof Error ? err.message : String(err)}) — ` +
+              `the cover shipped; a later headline change will re-pick the frame`,
+          );
+        }
       }
     }
   }