ossclip 0.1.17 → 0.1.19

package/src/interactive/picker.ts

@@ -0,0 +1,286 @@
+import { VIDEO_EXTENSIONS, run } from "@ossclip/core";
+import { binOnPath } from "../llm-detect";
+
+/**
+ * The native file/folder dialog (§136). Typing a path was the one step a
+ * non-technical user could not get past — the blocker was never the flags,
+ * it was the very first prompt.
+ *
+ * Split the way `open.ts` is split, and for the same reason: the platform
+ * matrix is decided by pure functions with a table test, so a Linux or
+ * Windows user is not the one who discovers the command was wrong. The
+ * `ossclip edit` crash that shipped in 0.1.4 for every non-macOS user is what
+ * this shape exists to prevent.
+ */
+
+export type PickMode = "file" | "folder";
+
+export interface PickerDeps {
+  platform: NodeJS.Platform;
+  env: NodeJS.ProcessEnv;
+  hasBin: (bin: string) => boolean;
+}
+
+export const livePickerDeps = (): PickerDeps => ({
+  platform: process.platform,
+  env: process.env,
+  hasBin: (bin) => binOnPath(bin),
+});
+
+/** `*.mov *.mp4 …` — the shape zenity and kdialog both want, space-joined. */
+const globs = (): string => VIDEO_EXTENSIONS.map((e) => `*.${e}`).join(" ");
+
+/**
+ * A PowerShell single-quoted string has exactly one escape: a literal `'` is
+ * written `''`. Nothing else is special in there — not `$`, not a backtick,
+ * not the `\` that fills every Windows path — which is why single quotes are
+ * what the script uses and why this is the whole escape rather than a table.
+ * `C:\Users\Ahsan's videos` is the case that makes it necessary.
+ */
+const psQuote = (s: string): string => s.replace(/'/g, "''");
+
+/**
+ * Is there a dialog to open at all? Probed rather than attempted, because
+ * offering a "Browse…" row that cannot work is worse than not offering it —
+ * the menu drops the row entirely when this is false.
+ */
+export function pickerAvailable(d: PickerDeps): boolean {
+  // Truthiness not presence, matching `isInteractive`'s treatment of CI.
+  if (d.env.OSSCLIP_NO_PICKER) return false;
+  // "Am I over SSH" is a PROXY for a signal these two platforms don't have
+  // (§136): neither macOS nor Windows exposes anything that says whether a
+  // reachable window server exists, so the remote-session hint is the best
+  // available stand-in. It has to be applied here, not just on darwin: macOS
+  // fails loudly — `choose file` returns -1743 (not authorized) — but Windows
+  // fails the dangerous way. It ships an in-box OpenSSH server, and
+  // ShowDialog() on a non-interactive window station blocks forever on a
+  // window nobody can see. `run()` has no timeout, so that is a CLI hung
+  // until Ctrl-C, the exact failure the -STA comment below exists to prevent.
+  //
+  // Note this deliberately does NOT cover Linux, which is handled below.
+  // osascript and WinForms are always installed, so there is nothing else to
+  // detect on either.
+  if (d.platform === "darwin" || d.platform === "win32") {
+    return !d.env.SSH_CONNECTION && !d.env.SSH_TTY;
+  }
+  // Linux is exempt from the SSH proxy above because it HAS the real signal.
+  // `ssh -X` sets DISPLAY=localhost:10.0 and zenity genuinely draws on the
+  // caller's local screen through the tunnel — a configuration that works.
+  // Layering the proxy on top of the evidence would override that evidence
+  // with a guess and break it.
+  //
+  // Both halves are required, and the display check is also what covers WSL
+  // without WSLg: zenity may well be installed there and still draw nowhere.
+  if (!d.env.DISPLAY && !d.env.WAYLAND_DISPLAY) return false;
+  return d.hasBin("zenity") || d.hasBin("kdialog");
+}
+
+export function pickerCommand(
+  d: PickerDeps,
+  mode: PickMode,
+  startDir?: string,
+): { bin: string; args: string[] } {
+  if (d.platform === "darwin") {
+    // Bare extensions, verified on macOS 26.3 — matching files stay
+    // selectable and the rest are dimmed. The UTI form {"public.movie"} was
+    // the alternative and is NOT used: its mkv coverage is unconfirmed, and
+    // mkv is in VIDEO_EXTENSIONS.
+    const types = VIDEO_EXTENSIONS.map((e) => `"${e}"`).join(",");
+    const clause =
+      mode === "folder"
+        ? 'choose folder with prompt "Pick a folder of clips"'
+        : `choose file with prompt "Pick your video" of type {${types}}`;
+    // startDir is always process.cwd(), never user text — but JSON.stringify
+    // still escapes it, because AppleScript string syntax is close enough to
+    // JSON's that this is the cheap correct thing rather than concatenation.
+    const loc = startDir === undefined ? "" : ` default location POSIX file ${JSON.stringify(startDir)}`;
+    return { bin: "osascript", args: ["-e", `POSIX path of (${clause}${loc})`] };
+  }
+
+  if (d.platform === "win32") {
+    // -STA is load-bearing: WinForms dialogs deadlock on the MTA thread that
+    // `powershell -Command` uses by default, and a deadlock here looks
+    // exactly like a hung CLI. `powershell` (5.1, in-box) rather than
+    // `pwsh`, which is not installed by default.
+    // startDir is honoured here too, under different property names on the
+    // two dialogs. Without it a Windows user standing in D:\shoots\raw opens
+    // at Desktop while darwin, zenity and kdialog all land in the project
+    // folder — the same flag, three platforms agreeing and one not.
+    const start =
+      startDir === undefined
+        ? ""
+        : mode === "folder"
+          ? // FolderBrowserDialog seeds its start folder from SelectedPath —
+            // the same property it hands the answer back in.
+            `$d.SelectedPath = '${psQuote(startDir)}'; `
+          : `$d.InitialDirectory = '${psQuote(startDir)}'; `;
+    const script =
+      mode === "folder"
+        ? "Add-Type -AssemblyName System.Windows.Forms; " +
+          "$d = New-Object System.Windows.Forms.FolderBrowserDialog; " +
+          start +
+          "if ($d.ShowDialog() -eq [System.Windows.Forms.DialogResult]::OK) { $d.SelectedPath }"
+        : "Add-Type -AssemblyName System.Windows.Forms; " +
+          "$d = New-Object System.Windows.Forms.OpenFileDialog; " +
+          `$d.Filter = 'Video|${VIDEO_EXTENSIONS.map((e) => `*.${e}`).join(";")}|All files|*.*'; ` +
+          start +
+          "if ($d.ShowDialog() -eq [System.Windows.Forms.DialogResult]::OK) { $d.FileName }";
+    return { bin: "powershell", args: ["-NoProfile", "-STA", "-Command", script] };
+  }
+
+  // Linux. zenity first because it is the GTK/GNOME default and far more
+  // widely installed; kdialog is the KDE equivalent and its filter syntax is
+  // a DIFFERENT shape — `Name(*.ext)` parentheses, not zenity's pipe.
+  if (d.hasBin("zenity")) {
+    const args = [
+      "--file-selection",
+      mode === "folder" ? "--title=Pick a folder of clips" : "--title=Pick your video",
+    ];
+    if (mode === "folder") args.push("--directory");
+    else args.push(`--file-filter=Video | ${globs()}`, "--file-filter=All files | *");
+    // The trailing slash is what makes zenity read this as a starting
+    // DIRECTORY rather than a pre-filled filename.
+    if (startDir !== undefined) args.push(`--filename=${startDir}/`);
+    return { bin: "zenity", args };
+  }
+
+  if (mode === "folder") {
+    // --getexistingdirectory accepts a start dir and nothing else; passing a
+    // filter here is an error, not an ignored argument.
+    return { bin: "kdialog", args: ["--getexistingdirectory", startDir ?? "."] };
+  }
+  return {
+    bin: "kdialog",
+    args: ["--getopenfilename", startDir ?? ".", `Video files(${globs()})`],
+  };
+}
+
+/**
+ * Emptiness is the signal: no path came back. Exit codes cannot carry it —
+ * zenity and kdialog exit non-zero when dismissed, but PowerShell exits 0 and
+ * simply emits nothing, because the `if` guarding ShowDialog() just doesn't
+ * fire. So the caller passes `allowNonZero` and reads stdout, on every
+ * platform.
+ *
+ * What "no path came back" does NOT distinguish is a cancel from a silent
+ * backend failure — osascript hitting -1743 in a launchd or tmux context that
+ * sets neither SSH var, or Add-Type failing on a Windows box. That conflation
+ * is deliberate: no backend gives us a reliable way to tell the two apart
+ * (stderr is prose that varies by version and locale), and the caller's
+ * fallback is the typed-path prompt, which is the right next step either way.
+ */
+export function parsePickerResult(stdout: string): string | undefined {
+  const picked = stdout.trim();
+  return picked === "" ? undefined : picked;
+}
+
+/**
+ * How much of stderr a user is shown. A zenity or osascript failure is one
+ * short sentence, but a PowerShell one is a multi-line exception with a
+ * banner, and pasting that above a wizard prompt is its own kind of unusable.
+ */
+const MAX_STDERR_CHARS = 160;
+
+/**
+ * AppleScript's user-cancelled error. Escape in `choose file` raises -128,
+ * which osascript writes to STDERR and exits 1 — verified on darwin 25.3.0
+ * (§136): `osascript -e 'error "User canceled." number -128'` prints
+ * `6:22: execution error: User canceled. (-128)`. So on the most common
+ * platform a cancel is the LOUDEST empty-handed return, not the quietest.
+ */
+const OSASCRIPT_CANCEL = /\(-128\)/;
+
+/**
+ * Toolkit chatter, not failure. GTK and Qt print these on a perfectly good
+ * dialog — `Gtk-Message: … Failed to load module "canberra-gtk-module"`,
+ * `Gdk-CRITICAL`, `qt.qpa.wayland:`, `kf.kio…` — and they are still sitting in
+ * stderr when the user cancels. Matched per LINE rather than against the whole
+ * blob, so a real error arriving alongside chatter still surfaces (§136).
+ */
+const BENIGN_STDERR_PREFIXES = ["Gtk-Message:", "Gdk-", "qt.", "kf."];
+
+/**
+ * The one line to print when the dialog came back with nothing and stderr says
+ * something went wrong. `parsePickerResult` above explains why stdout alone
+ * cannot tell a cancel from a silent backend failure; stderr can, but only
+ * after the noise is stripped, and the noise is backend-specific (§136):
+ *
+ * - **osascript** is NOT silent on a cancel — it emits error -128 (above).
+ *   This was got wrong once, and the bug was that every Escape in the Finder
+ *   dialog told a user whose picker works perfectly that it was broken.
+ * - **zenity / kdialog** exit 1 with empty stdout and *usually* empty stderr,
+ *   but GTK and Qt leave launch chatter there routinely, cancel or not.
+ * - **PowerShell** is the only one the naive reading holds for: exit 0, empty
+ *   stdout, empty stderr, because the `if` guarding ShowDialog() just does not
+ *   fire.
+ *
+ * Deliberately NOT keyed on the exit code: this function is not given one, and
+ * PowerShell shows why it would be wrong anyway — it exits 0 on a cancel and
+ * would exit 0 on some failures too.
+ *
+ * Without a notice at all the user is in a feedback-free loop (§136, final
+ * review): a plain `ssh` into a box whose `~/.bashrc` exports `DISPLAY=:0`
+ * passes `pickerAvailable`, so `Browse…` is offered, prints "look for a new
+ * window", and returns to the menu with no window and no output — identically,
+ * forever, on every retry. The return value stays `undefined` either way; it
+ * was only ever the silence that was wrong.
+ *
+ * Pure so the wording is pinned without a dialog, which blocks on a human.
+ */
+export function pickerFailureNotice(
+  bin: string,
+  stdout: string,
+  stderr: string,
+): string | undefined {
+  if (parsePickerResult(stdout) !== undefined) return undefined;
+  if (OSASCRIPT_CANCEL.test(stderr)) return undefined;
+  const real = stderr
+    .split("\n")
+    .map((l) => l.trim())
+    .filter((l) => l !== "" && !BENIGN_STDERR_PREFIXES.some((p) => l.startsWith(p)));
+  // First real line only: the rest is a stack or a usage dump on every backend
+  // that produces more than one.
+  const first = real[0];
+  if (first === undefined) return undefined; // a genuine cancel
+  const detail = first.length > MAX_STDERR_CHARS ? `${first.slice(0, MAX_STDERR_CHARS)}…` : first;
+  return `▸ ${bin} could not open a picker: ${detail} — type the path instead`;
+}
+
+/**
+ * Open the dialog and wait. The ONLY I/O in this module.
+ *
+ * The notice before the spawn is not decoration: a dialog that opens behind
+ * the terminal is indistinguishable from a hung CLI, and the wait here is
+ * unbounded by design — a human is deciding.
+ *
+ * The returned path is deliberately unvalidated (§136); `validateInputPath`
+ * owns existence and extension for the typed branch and this one alike, so
+ * the two cannot drift apart.
+ */
+export async function pickPath(
+  mode: PickMode,
+  deps: PickerDeps = livePickerDeps(),
+  startDir: string = process.cwd(),
+): Promise<string | undefined> {
+  const { bin, args } = pickerCommand(deps, mode, startDir);
+  console.log("▸ file picker open — look for a new window");
+  try {
+    // allowNonZero: a cancel exits non-zero on zenity and kdialog — and 0 with
+    // empty stdout on PowerShell (see parsePickerResult above, and §136). The
+    // flag covers the first shape; emptiness is what actually decides.
+    const { stdout, stderr } = await run(bin, args, { allowNonZero: true });
+    // A backend that started and then failed says so on stderr and nowhere
+    // else. Say it back, or the user is told to look for a window that will
+    // never appear and is given nothing to act on (§136).
+    const notice = pickerFailureNotice(bin, stdout, stderr);
+    if (notice !== undefined) console.log(notice);
+    return parsePickerResult(stdout);
+  } catch {
+    // `run` only rejects when the binary would not start. pickerAvailable
+    // said yes, so this is a broken install or a PATH that changed under us —
+    // fall through to typing rather than failing the whole wizard, the same
+    // call openInBrowser makes about a box with no browser on it.
+    console.log("▸ couldn't open a file picker here — type the path instead");
+    return undefined;
+  }
+}

package/src/interactive/produce-wizard.ts

@@ -1,5 +1,6 @@
 import { basename } from "node:path";
-import { existsSync, readdirSync, statSync } from "node:fs";
+import { existsSync, readdirSync } from "node:fs";
+import { askInput } from "./ask-input";
 import { produceArgv, type ProduceAnswers, type ProduceExtras } from "./produce-argv";
 import { assertInteractive, confirm, intro, multiselect, select, text, unwrap } from "./prompts";
 
@@ -145,27 +146,10 @@ export async function produceWizard(
   // dropped it and asked again — the re-ask is where "./Anyhropic c Compiler"
   // became "./" (all of ~/Downloads). The router checks existence before the
   // wizard ever opens, so a prefilled path skips the prompt entirely.
-  const input =
-    cfg.input ??
-    (unwrap(
-      await text({
-        // Finding 1 (final-review fix wave): `ossclip produce <folder>` shipped
-        // (folder-input-brief.md) but this prompt still rejected a directory —
-        // the wizard was the only way in that couldn't do what the CLI could.
-        // A folder is concatenated by name (codepoint order, like `ls`); --sort
-        // mtime reorders it but stays a typed flag, not a wizard question (see
-        // the file-level comment above for why).
-        message: "Video file, or a folder of clips to concatenate (by name; --sort mtime is a typed flag)",
-        placeholder: "./raw/take1.mp4",
-        validate: (v) => {
-          if (!v) return "a path is required";
-          if (!existsSync(v)) return `no such path: ${v}`;
-          const st = statSync(v);
-          if (!st.isFile() && !st.isDirectory()) return `${v} is neither a video file nor a folder`;
-          return undefined;
-        },
-      }),
-    ) as string);
+  //
+  // Everything else now lives in ask-input.ts (§136): suggestions, the native
+  // picker, and typing, all converging on one validator.
+  const input = cfg.input ?? (await askInput());
 
   const aspect = unwrap(
     await select({

package/src/interactive/suggest-inputs.ts

@@ -0,0 +1,164 @@
+import { readdir, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, extname, join } from "node:path";
+import { VIDEO_EXTENSIONS } from "@ossclip/core";
+
+/**
+ * The rows above "Browse…" in the input prompt (§136). A non-technical user
+ * has just hit record and wants the file they made thirty seconds ago; it is
+ * nearly always the newest video in the working directory, Downloads, or
+ * Movies. Offering it by name beats any picker.
+ *
+ * Deliberately stateless: no recents file to keep, migrate or privacy-audit,
+ * and — the reason that mattered — a recents list is EMPTY on the very first
+ * run, which is the exact run a new user needs the help on.
+ */
+
+export interface CandidateFile {
+  path: string;
+  mtimeMs: number;
+  size: number;
+}
+
+export interface Suggestion {
+  path: string;
+  label: string;
+  hint: string;
+}
+
+const VIDEO_EXT_SET = new Set<string>(VIDEO_EXTENSIONS);
+
+/**
+ * Base-1000 like Finder and Explorer report it, not base-1024.
+ *
+ * The thresholds are the ROUNDING boundary (999_500), not the unit boundary
+ * (1_000_000): `Math.round` carries into the next unit while a unit-boundary
+ * check has already committed to the current one, so a 999.7 MB screen
+ * recording printed "1000 MB" next to a sibling's "1.1 GB".
+ */
+export function humanSize(bytes: number): string {
+  if (bytes < 1_000) return `${bytes} B`;
+  if (bytes < 999_500) return `${Math.round(bytes / 1_000)} kB`;
+  if (bytes < 999_500_000) return `${Math.round(bytes / 1_000_000)} MB`;
+  return `${(bytes / 1_000_000_000).toFixed(1)} GB`;
+}
+
+export function relativeAge(msInput: number): string {
+  // A file copied off a camera with an unset clock carries an mtime years
+  // ahead, which reaches here as a NEGATIVE age. Clamped rather than special
+  // cased: "just now" is the honest label for "not older than now". Such
+  // files are deliberately still ranked (highest, by mtime) rather than
+  // filtered — a few seconds of clock skew is ordinary and the file is real.
+  const ms = Math.max(0, msInput);
+  if (ms < 60_000) return "just now";
+  if (ms < 3_600_000) return `${Math.floor(ms / 60_000)}m ago`;
+  if (ms < 86_400_000) return `${Math.floor(ms / 3_600_000)}h ago`;
+  return `${Math.floor(ms / 86_400_000)}d ago`;
+}
+
+export function tildeify(path: string, home: string): string {
+  return path.startsWith(`${home}/`) ? `~${path.slice(home.length)}` : path;
+}
+
+export function likelyDirs(d: {
+  platform: NodeJS.Platform;
+  cwd: string;
+  home: string;
+}): string[] {
+  // Movies on macOS, Videos everywhere else — the OS's own recording default.
+  const media = join(d.home, d.platform === "darwin" ? "Movies" : "Videos");
+  return [...new Set([d.cwd, join(d.home, "Downloads"), media])];
+}
+
+export function rankSuggestions(
+  files: CandidateFile[],
+  nowMs: number,
+  home: string,
+  limit = 3,
+): Suggestion[] {
+  return files
+    .filter((file) => {
+      const name = basename(file.path);
+      if (name.startsWith(".")) return false;
+      // ossclip's own output. Cutting an already-cut video compounds the
+      // trims and is never what somebody means to do from this menu.
+      if (name.toLowerCase().endsWith(".ossclip.mp4")) return false;
+      // Case-folded before the lookup because VIDEO_EXTENSIONS is lowercase
+      // and cameras and screen recorders write `.MP4`/`.MOV` — the same fold
+      // `listFolderVideos` does, for the same reason.
+      return VIDEO_EXT_SET.has(extname(name).slice(1).toLowerCase());
+    })
+    .sort((a, b) => b.mtimeMs - a.mtimeMs)
+    .slice(0, limit)
+    .map((file) => ({
+      path: file.path,
+      label: tildeify(file.path, home),
+      hint: `${humanSize(file.size)} · ${relativeAge(nowMs - file.mtimeMs)}`,
+    }));
+}
+
+/** How many files to `stat` per directory. See the placement note below. */
+const MAX_STATS_PER_DIR = 2_000;
+
+/**
+ * The only filesystem in this module, and non-recursive on purpose: this
+ * runs before the first prompt paints, so a deep walk of somebody's
+ * Downloads would show up as the CLI hanging on startup.
+ */
+export async function scanLikelyDirs(
+  dirs: string[] = likelyDirs({ platform: process.platform, cwd: process.cwd(), home: homedir() }),
+): Promise<CandidateFile[]> {
+  const out: CandidateFile[] = [];
+  for (const dir of dirs) {
+    let names: string[];
+    try {
+      names = (await readdir(dir, { withFileTypes: true }))
+        // Symlinks are followed, matching `listFolderVideos` in concat.ts: a
+        // folder of symlinks into another drive is a normal way to stage
+        // takes. The `stat` below resolves the target, and a dangling link
+        // throws into the per-file catch there.
+        .filter((e) => e.isFile() || e.isSymbolicLink())
+        .map((e) => e.name)
+        // Case-folded because VIDEO_EXTENSIONS is lowercase and recorders
+        // write `.MP4`/`.MOV`, the same fold `listFolderVideos` does.
+        .filter((name) => VIDEO_EXT_SET.has(extname(name).slice(1).toLowerCase()))
+        // The cap sits AFTER the filter on purpose: `readdir` has already
+        // materialised every dirent, so capping before it saves no I/O and
+        // throws away videos at random — readdir order is filesystem order,
+        // not mtime, so the take recorded 30 seconds ago is as likely to land
+        // in the discarded tail as anything else. Here it bounds the only
+        // real cost, the per-file stat.
+        .slice(0, MAX_STATS_PER_DIR);
+    } catch {
+      // A missing ~/Movies or an unreadable directory is ordinary. The
+      // suggestions are a convenience; nothing here may fail the wizard.
+      continue;
+    }
+    // Stat'd in parallel: awaited one at a time, a directory of 400 clips on
+    // an SMB share or an iCloud "Optimize Storage" ~/Movies is seconds of
+    // dead terminal before the first prompt paints, which is the startup hang
+    // non-recursion alone does not prevent. try/catch inside each task rather
+    // than allSettled because the recovery is identical for every failure —
+    // drop that one file — and this keeps the settled result already typed.
+    const stats = await Promise.all(
+      names.map(async (name): Promise<CandidateFile | undefined> => {
+        const path = join(dir, name);
+        try {
+          const st = await stat(path);
+          // A symlink to a DIRECTORY named `takes.mp4` passes the dirent
+          // check above and stats fine; without this it would be offered
+          // carrying the directory's size and mtime. concat.ts:346-353 —
+          // the parity this module claims — resolves and drops it too.
+          if (!st.isFile()) return undefined;
+          return { path, mtimeMs: st.mtimeMs, size: st.size };
+        } catch {
+          // Raced with a delete between readdir and stat, or a dangling
+          // symlink — skips this file only, never the whole directory.
+          return undefined;
+        }
+      }),
+    );
+    for (const file of stats) if (file !== undefined) out.push(file);
+  }
+  return out;
+}

package/src/overrides-write.ts

@@ -0,0 +1,77 @@
+import { readFile, rename, writeFile } from "node:fs/promises";
+import type { OverrideDoc } from "@ossclip/core";
+
+/**
+ * The one sanctioned `overrides.json` write (PLAN 2026-08-04 Task 4), and the
+ * rule about when it may spend the `.bak`.
+ *
+ * Lifted out of `produce.ts` so the backup rule is testable at all: nothing in
+ * the repo invokes `produce()` (it needs ffmpeg, a transcript, a workdir and a
+ * render), and "the previous copy is still on disk, byte for byte" is a claim
+ * about a FILE — there is no pure form of it. `produce.ts` keeps the decision
+ * of WHETHER to write, the ordering relative to `render-props.json`, and the
+ * `console.log`.
+ */
+
+/**
+ * Replace `overrides.json`, optionally refreshing `overrides.json.bak` first.
+ *
+ * REFRESHING THE BACKUP IS NOT PART OF WRITING (final review round 2, Critical
+ * 2 residual). The `.bak` is single-generation, so every refresh SPENDS
+ * whatever it held, and the two writers have very different claims on it:
+ *
+ *  - A CUT re-anchoring rewrites absolute output-second VALUES all over the
+ *    doc — split times, pins, framing — from a frame the pipeline just
+ *    recomputed. That is unreadable in a diff and irreversible by hand, so the
+ *    copy it replaces is worth keeping and this is the write the `.bak` exists
+ *    for.
+ *  - A CAPTION-KEY migration differs from the copy on disk in caption KEYS
+ *    only, every one of which the run just printed by name, and (since
+ *    `captionEditsToKeep`) it deletes nothing. There is nothing in the old
+ *    copy worth recovering — while the `.bak` it would overwrite may be the
+ *    user's last PRE-CUT save, which on the §137 field workdir is the only
+ *    artefact holding `splits: [0.6]` and so the only route back to the split
+ *    half they deleted (`legacySplitId` can no longer derive `600` from a
+ *    re-anchored `splits: [0]`).
+ *
+ * The first cut of the §137 fix refreshed unconditionally, which meant the
+ * branch's own marquee scenario — three of that user's four retypes recovered
+ * — destroyed the evidence for the other half of the same bug. Gating the
+ * WRITE on work done (`produce.ts`) only removed the zero-repair case; this is
+ * the rest of it.
+ *
+ * Atomic via tmp+rename either way, 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.
+ */
+export async function writeOverrideDoc(
+  overridesPath: string,
+  doc: OverrideDoc,
+  opts: { refreshBackup: boolean },
+): Promise<void> {
+  if (opts.refreshBackup) {
+    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(doc, null, 2));
+  await rename(tmp, overridesPath);
+}
+
+/**
+ * What the run says about that write. Pure, and separate from the write for
+ * the house reason — but also because the two halves of this sentence are the
+ * two halves of the decision above, and a line that claims a backup nobody
+ * took is how a user finds out too late (final review round 2).
+ */
+export function overridesWriteLine(cutChanged: boolean): string {
+  return cutChanged
+    ? "▸ overrides.json re-anchored to the new cut and saved (previous copy kept as .bak)"
+    : "▸ overrides.json re-anchored to source-time caption keys and saved " +
+        "(overrides.json.bak left alone — it may be an older, pre-cut copy worth more than this one)";
+}