@ossclip/core 0.1.6 → 0.1.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossclip/core",
-  "version": "0.1.6",
+  "version": "0.1.9",
   "description": "ossclip's framework-free pipeline: schema, transcription, analysis, cutlist, captions, framing, and the LLM producer",
   "type": "module",
   "license": "MIT",

package/src/blooper.ts

@@ -1,5 +1,6 @@
 import { normalizeToken } from "./analyze";
 import { isSentenceStart } from "./clip";
+import { levenshtein } from "./phonetics";
 import type { Transcript } from "./schema";
 
 /**
@@ -14,8 +15,14 @@ import type { Transcript } from "./schema";
  *
  * A marker the speaker says OUT LOUD is the deterministic subset. It needs no
  * judgement: the word is in the transcript or it is not. So this ships the
- * useful half of the feature and leaves the guarantee intact — the semantic
- * detector remains unbuilt, deliberately.
+ * useful half of the feature and leaves the guarantee intact.
+ *
+ * The OTHER half — the flub the speaker did NOT mark — turned out to have a
+ * deterministic formulation too: `retake.ts` (R27 §128) collapses consecutive
+ * near-identical sentences by token similarity, no LLM, same purity
+ * guarantee. What's left unbuilt is narrower than this comment used to claim:
+ * a genuinely REWORDED retake (different words, same idea) is still semantic,
+ * and stays out of scope on purpose (ROADMAP.md).
  *
  * The pattern, from the take that motivated it:
  *
@@ -38,6 +45,57 @@ export interface BloopSpan {
   endSec: number;
   /** How many marker words this span swallowed — 2+ means repeated attempts. */
   markers: number;
+  /** The marker text this span was searched for, normalized — for the report line. */
+  marker: string;
+  /**
+   * Surface forms in this span that matched by sound-alike or edit distance,
+   * not exact text — e.g. ASR wrote "looker" for a "blooper" marker. Every
+   * fuzzy hit must land here: it is what makes fuzzy matching safe to ship
+   * on by default, since a false positive shows up in report.txt instead of
+   * silently cutting a good take (Task 3, editor-dogfood-fixes plan).
+   */
+  matched: string[];
+}
+
+// Fuzzy matching only turns on once the marker is long enough that a false
+// positive is unlikely — a short marker like "cut" sound-alikes ("cat") and
+// sits within edit distance 2 of half the dictionary ("but", "gut", "cot"),
+// so short markers stay exact-only (Task 3, editor-dogfood-fixes plan).
+const FUZZY_MIN_MARKER_LEN = 6;
+// "blooper" → "looker" is exactly this: 2 edits (drop the "b", substitute
+// "p" for "k"). Found in the wild — see the guard test in blooper.test.ts.
+const FUZZY_MAX_DISTANCE = 2;
+
+interface MarkerMatch {
+  /** Normalized text of the transcript word that matched. */
+  surface: string;
+  /** False when this needed sound-alike/edit-distance rather than an exact hit. */
+  exact: boolean;
+}
+
+/**
+ * Whether a transcript word counts as the marker, and how.
+ *
+ * Exact match (today's rule) always wins first. Past that, the only fuzzy
+ * arm is a small edit distance — NOT `soundsSimilar` (§125,
+ * PHASE1-FINDINGS.md). The first field run of this feature paired the two
+ * arms as designed and got the worst of both: `soundsSimilar("builds",
+ * "blooper")` is true (shared "b" onset, score over its 0.34 floor) and cut
+ * 86.8% of a 125.9s video, while the pair `soundsSimilar` exists to catch —
+ * "looker" for "blooper" — is REJECTED by its own onset test (b/l differ)
+ * and only ever matched via Levenshtein anyway. Sound-alike was admitting
+ * garbage and catching nothing real, so it is gone; Levenshtein alone still
+ * catches "looker" (distance 2) and does not catch "builds" (distance 6).
+ */
+function matchMarker(wordText: string, want: string): MarkerMatch | null {
+  const norm = normalizeToken(wordText);
+  if (!norm) return null;
+  if (norm === want) return { surface: norm, exact: true };
+  if (want.length < FUZZY_MIN_MARKER_LEN) return null;
+  if (levenshtein(norm, want) <= FUZZY_MAX_DISTANCE) {
+    return { surface: norm, exact: false };
+  }
+  return null;
 }
 
 /**
@@ -45,7 +103,9 @@ export interface BloopSpan {
  *
  * `marker` is matched with `normalizeToken`, the same normalizer the filler
  * detector uses, so case and trailing punctuation do not matter — ASR writes
- * the word as "blooper." with the period riding on it.
+ * the word as "blooper." with the period riding on it. Beyond exact text, a
+ * marker of at least `FUZZY_MIN_MARKER_LEN` characters also matches an ASR
+ * mishearing — see `matchMarker`.
  *
  * Returns spans in transcript order, non-overlapping.
  */
@@ -53,11 +113,15 @@ export function findBloopSpans(transcript: Transcript, marker: string): BloopSpa
   const want = normalizeToken(marker);
   if (!want) return [];
   const words = transcript.words;
-  const isMarker = (i: number): boolean => normalizeToken(words[i]?.text ?? "") === want;
+  const matchAt = (i: number): MarkerMatch | null => {
+    const w = words[i];
+    return w ? matchMarker(w.text, want) : null;
+  };
 
   const spans: BloopSpan[] = [];
   for (let i = 0; i < words.length; i++) {
-    if (!isMarker(i)) continue;
+    const match = matchAt(i);
+    if (!match) continue;
 
     // Walk back over the attempt this marker spoiled, to the start of its
     // sentence. The marker's own text usually ENDS a sentence ("blooper."), so
@@ -70,10 +134,12 @@ export function findBloopSpans(transcript: Transcript, marker: string): BloopSpa
     // one-word island of a sentence nobody finished.
     const prev = spans[spans.length - 1];
     let markers = 1;
+    let matched = match.exact ? [] : [match.surface];
     if (prev && start <= prev.endWord + 1) {
       spans.pop();
       start = prev.startWord;
       markers = prev.markers + 1;
+      matched = [...prev.matched, ...matched];
     }
 
     spans.push({
@@ -82,6 +148,8 @@ export function findBloopSpans(transcript: Transcript, marker: string): BloopSpa
       startSec: words[start]!.start,
       endSec: words[i]!.end,
       markers,
+      marker: want,
+      matched,
     });
   }
   return spans;
@@ -98,5 +166,13 @@ export function formatBloopSpan(transcript: Transcript, span: BloopSpan): string
     .map((w) => w.text)
     .join(" ");
   const attempts = span.markers > 1 ? ` (${span.markers} attempts)` : "";
-  return `"${said}"${attempts}`;
+  // A fuzzy hit must never be silent — this line is the safety net that
+  // makes on-by-default fuzzy matching acceptable (Task 3, editor-dogfood-fixes
+  // plan): a false positive shows up here instead of quietly cutting a good
+  // take.
+  const fuzzy =
+    span.matched.length > 0
+      ? " " + span.matched.map((m) => `matched "${m}" ~ "${span.marker}"`).join(", ")
+      : "";
+  return `"${said}"${attempts}${fuzzy}`;
 }

package/src/concat.ts

@@ -0,0 +1,333 @@
+import { existsSync } from "node:fs";
+import { readdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod/v4";
+import { probe, type IngestTools } from "./ingest";
+import { run } from "./exec";
+
+/**
+ * `ossclip produce <folder>` (2026-08-05 field request, verbatim intent in
+ * .superpowers/sdd/folder-input-brief.md): a folder of camera-clip takes gets
+ * concatenated into ONE source before the normal produce pipeline ever sees
+ * it, instead of the user hand-concatenating with an agent first.
+ *
+ * Split per CLAUDE.md's pure/IO mandate — the bug that motivates the split is
+ * in the brief: a hand-built ffmpeg filtergraph corrupted by shell expansion
+ * (zsh's `:a` history modifier) silently played clip 1's audio in every
+ * concat slot, and nothing validated the filter STRING before it reached
+ * ffmpeg. `planFolderConcat`, `buildConcatFilter`, `folderManifestKey` and
+ * `assertAllClipsHaveAudio` are pure so each can be asserted on directly;
+ * `listFolderVideos` and `concatFolder` are the only I/O.
+ */
+
+const VIDEO_EXTENSIONS = ["mov", "mp4", "m4v", "mkv", "webm", "avi"] as const;
+const VIDEO_EXTENSION_SET = new Set<string>(VIDEO_EXTENSIONS);
+
+function noVideoFilesError(folder: string): Error {
+  return new Error(
+    `no video files found directly inside ${folder} ` +
+      `(looked for: ${VIDEO_EXTENSIONS.map((e) => `.${e}`).join(", ")})`,
+  );
+}
+
+export interface ConcatEntry {
+  name: string;
+  mtimeMs: number;
+  size: number;
+}
+
+/**
+ * Order clips for concatenation. `name` (default, per the field request "sort
+ * them by name or date modified, name being default") is a PLAIN codepoint
+ * sort — comparing strings with `<`/`>` rather than `localeCompare`, which is
+ * what `ls` gives on a case-sensitive filesystem and a locale-aware sort would
+ * NOT: it reorders case and punctuation differently per machine locale, which
+ * would make the same folder concat in a different order on a different
+ * machine. `mtime` ties (a batch copy that preserved one timestamp across
+ * several files) fall back to name so the order stays reproducible either way.
+ */
+export function planFolderConcat(
+  entries: readonly ConcatEntry[],
+  sort: "name" | "mtime",
+): string[] {
+  const byName = (a: ConcatEntry, b: ConcatEntry): number =>
+    a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
+  const cmp = sort === "name" ? byName : (a: ConcatEntry, b: ConcatEntry) => a.mtimeMs - b.mtimeMs || byName(a, b);
+  return [...entries].sort(cmp).map((e) => e.name);
+}
+
+/**
+ * A deterministic, order-independent identity for a folder's clip set —
+ * sorted by name (a canonical order regardless of `readdir`'s OS-dependent
+ * enumeration order) before joining, so the same files always hash the same
+ * way. `sort` is folded in because a `--sort` flip changes the concat's
+ * actual bytes (different clip order), not just how it was chosen.
+ *
+ * Fix for a review finding on the first cut of this feature: the workdir
+ * hash used to be derived from the FOLDER PATH alone, which is stable across
+ * content changes — but `audio.wav`, `transcript.json`, the content-rect
+ * cache and the mezzanine are all existence-keyed inside that same workdir.
+ * Adding a take (or flipping --sort) rebuilt `source-concat.mp4` correctly
+ * but silently reused every one of those, producing a video with captions
+ * transcribed against the PREVIOUS concat. Hashing the manifest content here
+ * — the same invariant a file input already has via `sha1File` — means a
+ * changed folder gets a fresh workdir, and every derived cache is fresh too.
+ *
+ * Serialized with JSON.stringify, not a `:`/`|` delimiter join (audit fix):
+ * a filename is user-controlled free text that can itself contain the
+ * delimiters, letting two DIFFERENT entry sets serialize to one identical
+ * key — `a:1` sized 2 and `a` sized `1:2` collide under a `:` join, and a
+ * collision here means one folder silently reuses another's transcript and
+ * mezzanine. JSON escapes the filename instead of trusting it. This changed
+ * every existing folder workdir hash once — a one-time cache invalidation
+ * (fresh workdir, full re-concat/re-transcribe on the next run), accepted as
+ * the cost of an injection-proof key.
+ */
+export function folderManifestKey(entries: readonly ConcatEntry[], sort: "name" | "mtime"): string {
+  const canonical = [...entries]
+    .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+    .map((e) => ({ name: e.name, size: e.size, mtimeMs: e.mtimeMs }));
+  return JSON.stringify({ sort, entries: canonical });
+}
+
+/**
+ * The `-filter_complex` string concatenating `n` inputs into one output.
+ * Each input gets its OWN scale+pad+fps+setsar+format chain — letterboxed to
+ * `target`, never cropped, since produce's own framing decides crops later —
+ * and its own audio resample, before the `concat` filter joins them.
+ *
+ * Rotation: ffmpeg auto-rotates on decode by default (R27 §119, `probe()` in
+ * ingest.ts relies on the same fact), so every `[i:v]` input here is ASSUMED
+ * to already arrive in DISPLAYED orientation — the scale/pad math needs no
+ * separate rotation step. This is an assumption carried over from R27 §119,
+ * not something the folder-input verification run could independently
+ * confirm: a letterboxed, correctly-proportioned 1080x1920 output is also
+ * what a WRONG rotation assumption would produce once padded to a portrait
+ * canvas, so that run couldn't distinguish "handled correctly" from
+ * "accidentally looks fine." Flagged rather than overclaimed per CLAUDE.md.
+ *
+ * `n` labels of each kind, never more or fewer, and the tail's `[vI][aI]`
+ * pairs are built in the SAME loop that emits them — this is the direct
+ * regression test target for the field bug (see module comment): a
+ * hand-built graph had a slot silently reference input 0's audio a second
+ * time instead of its own index, and nothing caught the STRING being wrong.
+ */
+export function buildConcatFilter(n: number, target: { w: number; h: number }): string {
+  const chains: string[] = [];
+  const tail: string[] = [];
+  for (let i = 0; i < n; i++) {
+    chains.push(
+      `[${i}:v]scale=${target.w}:${target.h}:force_original_aspect_ratio=decrease,` +
+        `pad=${target.w}:${target.h}:(ow-iw)/2:(oh-ih)/2,fps=30,setsar=1,format=yuv420p[v${i}]`,
+    );
+    chains.push(`[${i}:a]aresample=48000,aformat=channel_layouts=stereo[a${i}]`);
+    tail.push(`[v${i}][a${i}]`);
+  }
+  return `${chains.join(";")};${tail.join("")}concat=n=${n}:v=1:a=1[outv][outa]`;
+}
+
+/**
+ * `buildConcatFilter` emits `[i:a]` unconditionally for every input — it has
+ * no way to know a clip is silent. Handed a video-only clip (b-roll with no
+ * audio stream), ffmpeg dies deep inside the filtergraph with a bare stream-
+ * specifier error that names neither the clip nor the reason. `probe()`
+ * already reports `hasAudio`; failing HERE, before ffmpeg ever runs, keeps
+ * faith with the brief's "a file that probe() rejects is an error naming the
+ * file, not a silent skip" — a clip with no audio is the same class of
+ * problem, just discovered an instant later than "no video stream at all".
+ */
+export function assertAllClipsHaveAudio(
+  clips: ReadonlyArray<{ name: string; hasAudio: boolean }>,
+): void {
+  const silent = clips.filter((c) => !c.hasAudio).map((c) => c.name);
+  if (silent.length > 0) {
+    throw new Error(
+      `no audio stream in: ${silent.join(", ")} — produce cuts by silence, so ` +
+        "every clip in a folder concat needs one (a silent b-roll clip can't be concatenated this way).",
+    );
+  }
+}
+
+const ConcatManifestSchema = z.object({
+  sort: z.enum(["name", "mtime"]),
+  entries: z.array(
+    z.object({
+      name: z.string(),
+      mtimeMs: z.number(),
+      size: z.number(),
+      durationSec: z.number(),
+    }),
+  ),
+});
+type ConcatManifest = z.infer<typeof ConcatManifestSchema>;
+
+/**
+ * The cached build is reusable only if EVERY current file is present in the
+ * manifest with the same size and mtime (a changed byte count or timestamp
+ * means the clip could have been re-exported), the counts match (a clip
+ * removed leaves no trace otherwise), and the sort mode is the one the
+ * manifest was built under (a `--sort` change reorders the clips, so a
+ * same-files cache is still the WRONG concat).
+ *
+ * Belt-and-suspenders alongside `folderManifestKey`: the workdir is now
+ * content-addressed too, so in practice a stale manifest can only be reached
+ * by a hash collision or a folder mutated mid-run — this is what catches
+ * either without trusting the hash alone.
+ */
+function manifestStillValid(manifest: ConcatManifest, sort: "name" | "mtime", current: readonly ConcatEntry[]): boolean {
+  if (manifest.sort !== sort) return false;
+  if (manifest.entries.length !== current.length) return false;
+  const byName = new Map(manifest.entries.map((e) => [e.name, e]));
+  return current.every((e) => {
+    const prev = byName.get(e.name);
+    return prev !== undefined && prev.mtimeMs === e.mtimeMs && prev.size === e.size;
+  });
+}
+
+export interface FolderListing {
+  entries: ConcatEntry[];
+  /** Files skipped for not matching a video extension (dotfiles excluded). */
+  nonVideoCount: number;
+}
+
+/**
+ * Enumerate the video files directly inside `folder` (no recursion — a
+ * subfolder is out of scope, not "ignored", so it is never counted).
+ *
+ * Symlinks to a regular file are followed (`stat`, which resolves the link)
+ * rather than dropped — a folder of symlinks into another drive is a normal
+ * way to stage takes, and silently enumerating zero clips from it would be a
+ * worse surprise than the extra `stat` call. A broken symlink or a symlink to
+ * a directory stats as "not a file" and is skipped without counting, the same
+ * as a real subfolder. Dotfiles (`.DS_Store` and friends) are skipped
+ * entirely and never counted — they are not a folder content decision the
+ * user made, so reporting them as "non-video files ignored" would be noise.
+ */
+export async function listFolderVideos(folder: string): Promise<FolderListing> {
+  const dirents = await readdir(folder, { withFileTypes: true });
+  let nonVideoCount = 0;
+  const entries: ConcatEntry[] = [];
+  for (const d of dirents) {
+    if (d.name.startsWith(".")) continue;
+    let isFile = d.isFile();
+    if (!isFile && d.isSymbolicLink()) {
+      try {
+        isFile = (await stat(join(folder, d.name))).isFile();
+      } catch {
+        isFile = false; // broken symlink — treated like a subfolder: skipped, not counted
+      }
+    }
+    if (!isFile) continue; // a real subfolder, or a symlink to one
+    const dot = d.name.lastIndexOf(".");
+    const ext = dot >= 0 ? d.name.slice(dot + 1).toLowerCase() : "";
+    if (!VIDEO_EXTENSION_SET.has(ext)) {
+      nonVideoCount++;
+      continue;
+    }
+    const st = await stat(join(folder, d.name));
+    entries.push({ name: d.name, mtimeMs: st.mtimeMs, size: st.size });
+  }
+  if (entries.length === 0) throw noVideoFilesError(folder);
+  return { entries, nonVideoCount };
+}
+
+export interface FolderConcatResult {
+  /** The intermediate file — hand this to the rest of produce. */
+  path: string;
+  /** In final concat order, for the "one line per clip" console report. */
+  clips: Array<{ name: string; durationSec: number }>;
+  /** Files skipped for not matching a video extension. */
+  nonVideoCount: number;
+  /** True when the existing `source-concat.mp4` was reused, not rebuilt. */
+  cached: boolean;
+  /** The concat's own total duration (ffprobe'd from the output). */
+  durationSec: number;
+}
+
+/**
+ * Order and concat `listing`'s clips into `<workDir>/source-concat.mp4`,
+ * caching on a manifest of names+sizes+mtimes so an unchanged folder skips
+ * the re-encode. `listing` comes from `listFolderVideos` — the caller
+ * enumerates once, up front, because it ALSO needs the listing to derive the
+ * workdir's content-addressed hash (`folderManifestKey`) before this can
+ * even be called with a `workDir` to write into.
+ */
+export async function concatFolder(
+  tools: IngestTools,
+  folder: string,
+  listing: FolderListing,
+  workDir: string,
+  sort: "name" | "mtime",
+  target: { w: number; h: number },
+): Promise<FolderConcatResult> {
+  const { entries: current, nonVideoCount } = listing;
+  if (current.length === 0) throw noVideoFilesError(folder);
+  const order = planFolderConcat(current, sort);
+
+  const outPath = join(workDir, "source-concat.mp4");
+  const manifestPath = join(workDir, "source-concat.json");
+  if (existsSync(outPath) && existsSync(manifestPath)) {
+    const parsed = ConcatManifestSchema.safeParse(JSON.parse(await readFile(manifestPath, "utf8")));
+    if (parsed.success && manifestStillValid(parsed.data, sort, current)) {
+      const byName = new Map(parsed.data.entries.map((e) => [e.name, e]));
+      const outProbe = await probe(tools, outPath);
+      return {
+        path: outPath,
+        clips: order.map((name) => ({ name, durationSec: byName.get(name)!.durationSec })),
+        nonVideoCount,
+        cached: true,
+        durationSec: outProbe.duration,
+      };
+    }
+  }
+
+  // A file with a video EXTENSION that fails to probe (no video stream) is an
+  // error naming the file, not a silent skip (folder-input-brief.md) — so
+  // `probe()`'s own "no video stream in <path>" is left to propagate rather
+  // than caught here.
+  const probes = await Promise.all(order.map((name) => probe(tools, join(folder, name))));
+  assertAllClipsHaveAudio(order.map((name, i) => ({ name, hasAudio: probes[i]!.hasAudio })));
+
+  const filter = buildConcatFilter(order.length, target);
+  const inputArgs = order.flatMap((name) => ["-i", join(folder, name)]);
+  // Encode to a sibling temp path, rename only on success — same reasoning as
+  // `bakeNormalizedSource` in normalize.ts (R27 §125): ffmpeg writes the
+  // container header as it goes, so a bake that dies mid-graph leaves a file
+  // with no `moov` atom, and a cache keyed on EXISTENCE would reuse that
+  // corpse forever. Rename is atomic on a POSIX filesystem.
+  const partial = `${outPath}.partial.mp4`;
+  try {
+    await run(tools.ffmpegPath, [
+      "-y",
+      ...inputArgs,
+      "-filter_complex", filter,
+      "-map", "[outv]",
+      "-map", "[outa]",
+      "-c:v", "libx264", "-preset", "medium", "-crf", "18",
+      "-c:a", "aac", "-b:a", "192k",
+      partial,
+    ]);
+    await rename(partial, outPath);
+  } catch (err) {
+    await rm(partial, { force: true });
+    throw err;
+  }
+
+  const manifest: ConcatManifest = {
+    sort,
+    entries: current.map((e) => ({
+      ...e,
+      durationSec: probes[order.indexOf(e.name)]!.duration,
+    })),
+  };
+  await writeFile(manifestPath, JSON.stringify(manifest, null, 2));
+
+  const outProbe = await probe(tools, outPath);
+  return {
+    path: outPath,
+    clips: order.map((name, i) => ({ name, durationSec: probes[i]!.duration })),
+    nonVideoCount,
+    cached: false,
+    durationSec: outProbe.duration,
+  };
+}

package/src/cutlist.ts

@@ -63,10 +63,19 @@ export interface BuildCutlistArgs {
   /**
    * Spans the speaker marked as bloopers out loud (R27 §122), from
    * `findBloopSpans`. Passed in rather than detected here so this stays a pure
-   * function of its arguments — and so `--blooper-marker` is the only thing
-   * that can put a `retake` cut in the timeline.
+   * function of its arguments.
    */
   bloops?: readonly { startWord: number; endWord: number; startSec: number; endSec: number }[];
+  /**
+   * Spans `findRetakeGroups` (R27 §128) elected to cut — the deterministic
+   * "keep only the last complete take" detector for the flub the speaker did
+   * NOT mark. Also a `reason: "retake"` cut, and also passed in rather than
+   * detected here, for the same purity reason as `bloops`: `buildCutlist`
+   * still has no judgement of its own about what a bad take looks like, it
+   * just folds whichever spans two independent detectors handed it into the
+   * one partition.
+   */
+  retakes?: readonly { startWord: number; endWord: number; startSec: number; endSec: number }[];
 }
 
 export function buildCutlist({
@@ -75,11 +84,13 @@ export function buildCutlist({
   duration,
   level,
   bloops,
+  retakes,
 }: BuildCutlistArgs): Segment[] {
   const keepAll: Segment[] = [{ srcIn: 0, srcOut: duration, kind: "keep" }];
   // `exact` means exact: it is the escape hatch for "touch nothing", and a
-  // blooper cut is still a cut. --blooper-marker with --cleanup exact is a
-  // contradiction, and the flag the user typed second does not get to win.
+  // blooper or retake cut is still a cut. --blooper-marker or
+  // --collapse-retakes with --cleanup exact is a contradiction, and the flag
+  // the user typed second does not get to win.
   if (level === "exact") return keepAll;
   const policy = POLICIES[level];
   const words = transcript.words;
@@ -105,6 +116,21 @@ export function buildCutlist({
     });
   }
 
+  // Same injection, same reason, lower confidence (R27 §128): a marker is the
+  // speaker asserting "this attempt is bad" — confidence 1. A retake group is
+  // this codebase inferring it from token similarity and the hallucination
+  // guard, so it earns 0.9, not 1 — the report and any future confidence-
+  // gated behavior can tell a supplied fact from an inferred one.
+  for (const r of retakes ?? []) {
+    removals.push({
+      start: r.startSec,
+      end: r.endSec,
+      reason: "retake",
+      confidence: 0.9,
+      source: "acoustic",
+    });
+  }
+
   for (const pause of analysis.cuttable) {
     // Lead and tail are decided by the SILENCE's position in the file, not by
     // comparing it to a word stamp (R27 §127). Whisper's `-ml 1` stamps stretch
@@ -178,7 +204,23 @@ export function buildCutlist({
   // keep. Acoustic boundaries are exempt: whisper's `-ml 1` stamps stretch a
   // word's end all the way to the next word's start, so a pause *always* looks
   // like it is "inside" a word — applying this rule to them cancels every cut.
-  const protectedWords = words.filter((_, i) => !fillerIndices.has(i));
+  //
+  // Fillers are excluded here ONLY when `policy.removeFillers` says they're
+  // actually being removed (fix wave final review, findings §124's
+  // follow-up): this same `protectedWords` list also feeds
+  // `hasProtectedWordInside` below, which Task 6 widened to fold a wordless
+  // keep-gap up to `policy.pauseMin` (1.2s at light). Excluding fillers
+  // unconditionally meant a lone "um" sitting in a gap between two silence
+  // removals read as "wordless" even at `light`, where `removeFillers` is
+  // false and the filler was never scheduled for removal at all — so the
+  // fold silently ate it, cutting a word `light`'s own contract promises to
+  // keep. The transcript-boundary loop right below is unaffected: it only
+  // ever runs for `source === "transcript"` removals, which only exist when
+  // `policy.removeFillers` created them (the `if (policy.removeFillers)`
+  // block above) — so at `light`, that loop already sees zero such removals
+  // and this widened list changes nothing for it, verified by reading rather
+  // than assumed.
+  const protectedWords = words.filter((_, i) => !policy.removeFillers || !fillerIndices.has(i));
   for (const r of removals) {
     if (r.source !== "transcript") continue;
     for (const w of protectedWords) {
@@ -193,12 +235,40 @@ export function buildCutlist({
       return mid > start && mid < end;
     });
 
-  // Merge removals that overlap, or whose in-between keep is a wordless sliver.
+  // Merge removals that overlap, or whose in-between keep is a wordless
+  // sliver — folded in regardless of length, not just when it's already
+  // under MIN_KEEP. A 0.37s wordless gap between two `silence` removals
+  // shipped in a real cleanup run because the old condition ANDed the
+  // wordless check to the length check, so `hasProtectedWordInside` was only
+  // ever asked once the gap was already short — a wordless gap that cleared
+  // MIN_KEEP was never asked at all (findings §124). MIN_KEEP's own comment
+  // already says wordless fragments fold; this makes the code do it.
+  //
+  // The fold is capped at `policy.pauseMin`, not left unbounded — folds any
+  // wordless gap UP TO pauseMin, refuses anything past it. The cap isn't
+  // about protecting short gaps; it's about what a gap LONGER than pauseMin
+  // sitting between two removals implies. The interior-pause branch above
+  // already generates its own removal for every genuinely silent stretch
+  // longer than pauseMin (`pauseDur <= policy.pauseMin` is the only case it
+  // skips) — so if a wordless-per-transcript gap that long survives here
+  // as bare space between two OTHER removals, the acoustic detector looked
+  // at it and did NOT call it silence. That's a live-audio signal the
+  // transcript can't see (a breath, laughter, room action, b-roll audio)
+  // being kept safe from a rule that only knows "the transcript found no
+  // words." A gap AT OR UNDER pauseMin, by contrast, is exactly the field
+  // bug's shape (0.37s, standard's 0.7s pauseMin): debris left over once
+  // both its neighbors are already cut, not a stretch the detector had any
+  // chance to flag on its own. `Math.max` with MIN_KEEP is defensive, not
+  // load-bearing: every current pauseMin already exceeds MIN_KEEP.
   const merged: Removal[] = [];
   for (const r of removals) {
     if (r.end - r.start < 0.05) continue;
     const prev = merged[merged.length - 1];
-    if (prev && (r.start <= prev.end + 1e-6 || (r.start - prev.end < MIN_KEEP && !hasProtectedWordInside(prev.end, r.start)))) {
+    const gap = prev ? r.start - prev.end : Number.POSITIVE_INFINITY;
+    const overlapping = prev !== undefined && gap <= 1e-6;
+    const wordless = prev !== undefined && !hasProtectedWordInside(prev.end, r.start);
+    const foldableGap = wordless && gap <= Math.max(MIN_KEEP, policy.pauseMin);
+    if (prev && (overlapping || foldableGap)) {
       const prevDur = prev.end - prev.start;
       const curDur = r.end - r.start;
       prev.end = Math.max(prev.end, r.end);

package/src/index.ts

@@ -6,12 +6,15 @@ export * from "./assemble";
 export * from "./fill";
 export * from "./producer/index";
 export * from "./timemap";
+export * from "./recut";
 export * from "./ingest";
+export * from "./concat";
 export * from "./transcribe";
 export * from "./analyze";
 export * from "./cutlist";
 export * from "./clip";
 export * from "./blooper";
+export * from "./retake";
 export * from "./captions";
 export * from "./zoom";
 export * from "./grounding";