ossclip 0.1.26 → 0.1.27

package/src/edit.ts

@@ -29,7 +29,9 @@ import {
   outPathInsideInput,
   PORTRAIT_MIME_TYPES,
   portraitMimeType,
+  readCoverProvenance,
   thumbnailImageCacheName,
+  type CoverProvenance,
   type GenerateThumbnailImageOptions,
   type ThumbnailConcept,
   type ThumbnailConceptApproved,
@@ -39,7 +41,23 @@ import {
 // server startup — open.ts is node:child_process + node:path and pure command
 // building, with nothing to defer.
 import { revealInFileManager } from "./open";
-import { artifactPath, expandHome } from "./paths";
+// The recorded-invocation reads live in cover.ts (2026-08-19): `ossclip
+// cover` needs the same out-resolution rule this server's thumbnail dest,
+// youtube markdown and reveal endpoint derive from, and two spellings of it
+// could disagree about which file a replay writes. cover.ts stays free of a
+// static @ossclip/renderer import for exactly this reason.
+import {
+  CoverAtSecondsSchema,
+  CoverFromSchema,
+  RecordedCommandSchema,
+  readRecordedCommand,
+  recordedArtifactPath as recordedArtifactPathIn,
+  recordedOutPath,
+  regenerateCover,
+  type CoverSeams,
+  type RecordedCommand,
+} from "./cover";
+import { expandHome } from "./paths";
 import {
   PORTRAIT_OVERRIDE_BASENAME,
   portraitExtensionForMime,
@@ -81,21 +99,6 @@ export function resolveEditorPageDir(): string | null {
  * replays the invocation `produce` recorded, never anything a client sent.
  */
 
-/**
- * The invocation `produce` recorded into the workdir (R11 Task 4.1).
- * Validated on read — it's a file on disk like any other user data — and the
- * ONLY thing `/api/render` will ever spawn: this server binds locally, but
- * accepting a client-supplied command would make it a remote shell.
- */
-const CommandSchema = z.object({
-  execPath: z.string(),
-  execArgv: z.array(z.string()).default([]),
-  script: z.string(),
-  args: z.array(z.string()),
-  cwd: z.string(),
-  out: z.string().optional(),
-});
-
 /** Ring-buffer cap for captured render output. */
 const RENDER_LOG_LINES = 200;
 export interface EditServer {
@@ -254,6 +257,13 @@ export async function startEditServer(
      * observe the revealed path instead of popping a real Finder/Explorer
      * window on the runner. */
     reveal?: (path: string) => void;
+    /**
+     * The cover render seam, exactly like `generateThumbnail` above. Without
+     * it `regenerateCover` lazily imports @ossclip/renderer and boots a
+     * headless browser — which `edit-server.test.ts` must never do, and which
+     * is also why cover.ts keeps that import lazy in the first place.
+     */
+    renderCover?: CoverSeams["renderCover"];
   } = {},
 ): Promise<EditServer> {
   // MUTABLE since R17 §83: the server can start with no project (the page
@@ -293,36 +303,13 @@ export async function startEditServer(
   // buy two.
   let thumbnailBusy = false;
   /** command.json's recorded invocation, or null when absent/corrupt — the
-   * thumbnail panel degrades to the config fallback rather than 500ing. */
-  const readCommandRecord = async (): Promise<z.infer<typeof CommandSchema> | null> => {
-    if (!existsSync(commandPath())) return null;
-    try {
-      const parsed = CommandSchema.safeParse(JSON.parse(await readFile(commandPath(), "utf8")));
-      return parsed.success ? parsed.data : null;
-    } catch {
-      return null;
-    }
-  };
-  /** The recorded out as an absolute path (the top-level `out` when
-   * recorded, else the argv's -o/--out resolved against the recorded cwd —
-   * the replay's own resolution), or null when no out was ever recorded.
-   * ONE spelling of the out-resolution rule: the artifact paths below and
-   * the reveal endpoint both derive from it, so they can never disagree
-   * about which file a replay writes. */
-  const recordedOutPath = (cmd: z.infer<typeof CommandSchema>): string | null => {
-    const out = cmd.out ?? lastFlagValue(cmd.args, ["-o", "--out"]);
-    if (out === undefined) return null;
-    return resolve(cmd.cwd, expandHome(out));
-  };
+   * thumbnail panel degrades to the config fallback rather than 500ing.
+   * Bound to the CURRENT workdir; the rule itself lives in cover.ts. */
+  const readCommandRecord = (): Promise<RecordedCommand | null> => readRecordedCommand(workdir!);
   /** `<out><ext>` from the recorded out, or null when no out was ever
    * recorded. Shared by the thumbnail dest and the youtube markdown. */
-  const recordedArtifactPath = async (ext: string): Promise<string | null> => {
-    const cmd = await readCommandRecord();
-    if (!cmd) return null;
-    const out = recordedOutPath(cmd);
-    if (out === null) return null;
-    return artifactPath(out, ext);
-  };
+  const recordedArtifactPath = (ext: string): Promise<string | null> =>
+    recordedArtifactPathIn(workdir!, ext);
   const thumbnailDestPath = (): Promise<string | null> => recordedArtifactPath(".thumbnail.png");
   /** Newest workdir file passing `test`, by mtime — the cache fallbacks. */
   const newestWorkdirFile = async (test: (name: string) => boolean): Promise<string | null> => {
@@ -354,6 +341,33 @@ export async function startEditServer(
       return null;
     }
   };
+  // ---- Cover regeneration (editor panel, 2026-08-19) ----------------------
+  // The cover is written on EVERY produce, `--youtube` or not, so this is not
+  // a YouTube-menu concern — it has its own top-bar button in the page. The
+  // panel round-trips through the workdir's `cover.json`, which is the same
+  // provenance `ossclip cover` reads and produce honours (`textSource:
+  // "user"`), so an edit made here survives into future renders with no new
+  // plumbing — the thumbnail block's approval-file contract, applied.
+  //
+  // One regeneration at a time: it can shell out to ffmpeg and it boots a
+  // headless browser, and a double-click must not run two renders at the same
+  // destination. `thumbnailBusy`'s rule, for the same reason.
+  let coverBusy = false;
+  /** Where the JPEG lives right now: the destination the last cover used,
+   * else `<recorded out>.cover.jpg`. Existence is the caller's check — a
+   * recorded destination that was never rendered is a real state (the panel
+   * shows a placeholder), not an error. */
+  const currentCoverImage = async (provenance: CoverProvenance | null): Promise<string | null> => {
+    if (provenance !== null && existsSync(provenance.out)) return provenance.out;
+    const dest = await recordedArtifactPath(".cover.jpg");
+    return dest !== null && existsSync(dest) ? dest : null;
+  };
+  /** mtime as the ts so the URL changes exactly when the file does — the
+   * thumbnail imageUrl's own cache-busting rule (a regenerate REPLACES the
+   * file behind this URL). */
+  const coverImageUrl = (image: string | null): string | null =>
+    image === null ? null : `/api/cover/image?ts=${Math.round(statSync(image).mtimeMs)}`;
+
   // ---- Portrait override (editor face swap, 2026-08-17) -------------------
   // A per-project `portrait-override.<ext>` in the workdir that outranks the
   // pin and the config (portrait-override.ts has the precedence argument).
@@ -647,7 +661,7 @@ export async function startEditServer(
           } catch {
             // ignore
           }
-          const parsed = CommandSchema.safeParse(
+          const parsed = RecordedCommandSchema.safeParse(
             JSON.parse(await readFile(commandPath(), "utf8")),
           );
           if (!parsed.success) return send(500, { error: `command.json is not valid: ${parsed.error.message}` });
@@ -1124,6 +1138,109 @@ export async function startEditServer(
           return send(200, { ok: true, mdPath });
         }
 
+        if (url.pathname === "/api/cover" && req.method === "GET") {
+          // The cover panel's one status call (2026-08-19): the provenance to
+          // prefill and where the current image is. All reads — the panel
+          // owns no state on the server.
+          if (!workdir) return send(409, { error: "no workdir open" });
+          const provenance = await readCoverProvenance(workdir);
+          const image = await currentCoverImage(provenance);
+          // Where a regeneration would WRITE. `coverDestination`'s canonical
+          // ladder: the destination the last cover used, else
+          // `<recorded out>.cover.jpg`. Neither means regenerateCover would
+          // throw for want of a destination, and the panel says so up front
+          // rather than after a click.
+          const outPath = provenance?.out ?? (await recordedArtifactPath(".cover.jpg"));
+          return send(200, {
+            status: outPath === null ? "unavailable" : "ready",
+            ...(outPath === null
+              ? { reason: "no-destination" as const }
+              : image === null
+                ? { reason: "never-rendered" as const }
+                : {}),
+            provenance,
+            outPath,
+            imageUrl: coverImageUrl(image),
+          });
+        }
+
+        if (url.pathname === "/api/cover/image" && req.method === "GET") {
+          if (!workdir) return send(409, { error: "no workdir open" });
+          const image = await currentCoverImage(await readCoverProvenance(workdir));
+          if (image === null) return send(404, { error: "no cover image" });
+          // Whole-file read + no-store, the thumbnail image endpoint's exact
+          // posture and for the same reason: a regenerate REPLACES the file
+          // behind a URL the panel busts with ?ts, and a cached 200 would show
+          // the old cover against the new ts on some proxies.
+          const bytes = await readFile(image);
+          res.writeHead(200, {
+            "content-type": "image/jpeg",
+            "cache-control": "no-store",
+            "content-length": String(bytes.length),
+          });
+          res.end(bytes);
+          return;
+        }
+
+        if (url.pathname === "/api/cover/regenerate" && req.method === "POST") {
+          if (!workdir) return send(409, { error: "no workdir open" });
+          // A regeneration can shell out to ffmpeg and it boots a headless
+          // browser — one at a time, a second is a 409 like a second render.
+          if (coverBusy) return send(409, { error: "a cover regeneration is already running" });
+          const chunks: Buffer[] = [];
+          for await (const c of req) chunks.push(c as Buffer);
+          // Three steerable values and NOTHING else. `atSec` rides the CLI's
+          // own schema so a negative seek is refused at both surfaces, and
+          // `from` rides the enum so a typo'd "finall" is a 400 rather than a
+          // cover quietly rebuilt from the wrong video (CLAUDE.md's
+          // --source-fit rule). Unknown keys are stripped by the parse, which
+          // is the load-bearing half of the paragraph below.
+          const parsed = z
+            .object({
+              text: z.string().optional(),
+              atSec: CoverAtSecondsSchema.optional(),
+              from: CoverFromSchema.optional(),
+            })
+            .safeParse(JSON.parse(Buffer.concat(chunks).toString() || "{}"));
+          if (!parsed.success) return send(400, { error: parsed.error.message });
+          coverBusy = true;
+          try {
+            // Every PATH is derived server-side — from command.json,
+            // cover.json and render-props.json — and never from the body: the
+            // stance the render and reveal endpoints already hold. This server
+            // binds locally, but an endpoint that WRITES a file wherever a
+            // client names is the same door as spawning a client-supplied
+            // command. Note the absent `outPath`: it exists on
+            // CoverRegenerateOptions for `ossclip cover --out`, and passing
+            // one through from here is exactly the bug this omission prevents.
+            const notes: string[] = [];
+            const provenance = await regenerateCover(
+              workdir,
+              { text: parsed.data.text, atSec: parsed.data.atSec, from: parsed.data.from },
+              { renderCover: opts.renderCover, log: (line) => notes.push(line) },
+            );
+            const image = await currentCoverImage(provenance);
+            // The notes ride back so the panel can show what the CLI PRINTS —
+            // a headline trimmed to nine words, or a re-picked frame. Silence
+            // on either is how a user ships a cover they did not write.
+            return send(200, {
+              ok: true,
+              provenance,
+              notes,
+              outPath: provenance.out,
+              imageUrl: coverImageUrl(image),
+            });
+          } catch (err) {
+            // 200 with ok:false, the thumbnail regenerate's posture: these
+            // failures are user-actionable sentences ("is the timestamp past
+            // the end?", "--from source needs cover.json") and the panel shows
+            // them inline VERBATIM rather than as a dead 500.
+            return send(200, { ok: false, error: err instanceof Error ? err.message : String(err) });
+          } finally {
+            coverBusy = false;
+          }
+        }
+
         if (url.pathname.startsWith("/media/")) {
           if (!workdir) return send(409, { error: "no workdir open" });
           const file = join(workdir, decodeURIComponent(url.pathname.slice("/media/".length)));

package/src/interactive/resolve-workdir.ts

@@ -106,10 +106,19 @@ export function resolveWorkdir(
  * interactive picker cannot run. Each line is rendered through
  * renderCommand so a path containing a space pastes into a shell as ONE
  * argument — an unquoted list defeats the only thing this branch is for.
+ *
+ * `command` is the subcommand the user actually ran: this ladder is shared
+ * with `ossclip cover`, and printing `ossclip edit <path>` to someone who
+ * typed `cover` sends them to a different command than the one they wanted.
+ * Defaults to "edit", the only caller when this was written.
  */
-export function candidateListMessage(dir: string, candidates: Candidate[]): string {
+export function candidateListMessage(
+  dir: string,
+  candidates: Candidate[],
+  command: string = "edit",
+): string {
   return (
     `several produce runs under ${dir} — name one:\n` +
-    candidates.map((c) => `  ${renderCommand(["edit", c.path])}`).join("\n")
+    candidates.map((c) => `  ${renderCommand([command, c.path])}`).join("\n")
   );
 }

package/src/produce.ts

@@ -39,8 +39,11 @@ import {
   listFolderVideos,
   outInsideInputFolderMessage,
   outPathInsideInput,
+  COVER_PROVENANCE_BASENAME,
   coverDecision,
   coverHeadline,
+  readCoverProvenance,
+  writeCoverProvenance,
   cropFilter,
   detectContentRect,
   letterboxedSeconds,
@@ -165,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";
@@ -306,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;
   /**
@@ -4061,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
@@ -4088,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),
@@ -4122,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 ` +
@@ -4139,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`,
+          );
+        }
       }
     }
   }

package/src/program.ts

@@ -3,7 +3,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { Command, InvalidArgumentError } from "commander";
 import { z } from "zod/v4";
-import { CleanupLevelSchema, SceneComponentIdSchema } from "@ossclip/core";
+import { CleanupLevelSchema, COVER_MAX_WORDS, SceneComponentIdSchema } from "@ossclip/core";
 import { STUDIO_ENTRY } from "@ossclip/renderer";
 import { loadEnvFiles } from "./env";
 import { ExportFormatSchema, runAnalyze } from "./analyze";
@@ -60,6 +60,42 @@ export function concurrencyFlag(v: string): number {
   return n;
 }
 
+/**
+ * `<command> [workdir]` → the workdir the user meant.
+ *
+ * ONE spelling of the probe → resolve → pick ladder, because `edit` and
+ * `cover` both need it and two copies drift: the reported failure it exists
+ * for is `ossclip edit <video folder>` when produce wrote into
+ * `<video folder>/.ossclip/<name>/`, and a `cover` that resolved differently
+ * would rebuild a cover for a run the user is not looking at.
+ *
+ * `command` is threaded so the no-TTY candidate list names the command that
+ * was actually run, not always `edit`.
+ *
+ * Every import here is dynamic on purpose: the interactive stack is not
+ * loaded on invocations that never reach a picker, which is what keeps CLI
+ * startup cheap.
+ */
+async function resolveWorkdirArgument(typed: string, command: string): Promise<string> {
+  const { probeWorkdir } = await import("./interactive/workdir-probe");
+  const { resolveWorkdir, candidateListMessage } = await import("./interactive/resolve-workdir");
+  const { isInteractive } = await import("./interactive/tty");
+  const { dir, probe } = await probeWorkdir(typed);
+  const resolution = resolveWorkdir(dir, probe);
+  if (resolution.kind === "none") throw new Error(resolution.message);
+  if (resolution.kind === "choose") {
+    if (!isInteractive()) {
+      throw new Error(candidateListMessage(dir, resolution.candidates, command));
+    }
+    const { pickWorkdir } = await import("./interactive/pick-workdir");
+    return await pickWorkdir(resolution.candidates);
+  }
+  // Say so when the path was not the one typed — a silent redirect leaves the
+  // user with the wrong mental model of where things live.
+  if (resolution.via === "nested") console.log(`▸ resolved ${typed} → ${resolution.workdir}`);
+  return resolution.workdir;
+}
+
 /**
  * Every command this CLI has, built onto a fresh instance.
  *
@@ -432,6 +468,11 @@ export function buildProgram(): Command {
         "any motion crops the head. Per-scene control stays in the editor (autoZoom)",
     )
     .option("--cover <path>", "cover image output path (default: <out>.cover.jpg)")
+    .option(
+      "--cover-text-reset",
+      "use this run's generated cover headline even if `ossclip cover --text` set one — " +
+        "that headline is user-owned and kept by default (deleting cover.json does the same)",
+    )
     .option("--open-editor", "open the editor when the run finishes")
     .option(
       "--no-open-editor",
@@ -586,6 +627,9 @@ export function buildProgram(): Command {
           jumpCuts,
           cover: opts.cover !== false,
           coverPath: typeof opts.cover === "string" ? opts.cover : undefined,
+          // A separate key from --cover: this one is about the TEXT, and the
+          // cover/coverPath pair already shares one.
+          coverTextReset: opts.coverTextReset === true,
           clip: opts.clip,
           clipWindow: opts.clipWindow,
           // Validated by concurrencyFlag at parse time; undefined = "not
@@ -829,27 +873,8 @@ export function buildProgram(): Command {
       // With no argument the editor opens on its own project picker (R17 §83).
       // With one, resolve what the user MEANT: `ossclip edit <video folder>`
       // was the reported failure, and produce's output lives one level down.
-      let target: string | undefined = workdir;
-      if (workdir !== undefined) {
-        const { probeWorkdir } = await import("./interactive/workdir-probe");
-        const { resolveWorkdir, candidateListMessage } = await import("./interactive/resolve-workdir");
-        const { isInteractive } = await import("./interactive/tty");
-        const { dir, probe } = await probeWorkdir(workdir);
-        const resolution = resolveWorkdir(dir, probe);
-        if (resolution.kind === "none") throw new Error(resolution.message);
-        if (resolution.kind === "choose") {
-          if (!isInteractive()) {
-            throw new Error(candidateListMessage(dir, resolution.candidates));
-          }
-          const { pickWorkdir } = await import("./interactive/pick-workdir");
-          target = await pickWorkdir(resolution.candidates);
-        } else {
-          target = resolution.workdir;
-          // Say so when the path was not the one typed — a silent redirect
-          // leaves the user with the wrong mental model of where things live.
-          if (resolution.via === "nested") console.log(`▸ resolved ${workdir} → ${target}`);
-        }
-      }
+      const target =
+        workdir === undefined ? undefined : await resolveWorkdirArgument(workdir, "edit");
 
       const server = await startEditServer(target, { port: opts.port, pageDir });
       console.log(`▸ editor at ${server.url}`);
@@ -864,6 +889,64 @@ export function buildProgram(): Command {
       void telemetry.flush();
     });
 
+  program
+    .command("cover")
+    .description(
+      "regenerate a produced workdir's cover image — a new headline or a new frame, " +
+        "in seconds, with no video re-render",
+    )
+    // Optional, like `edit`'s: with no argument this resolves the run under
+    // the CURRENT directory, so `cd`-ing to the video's folder is enough.
+    .argument("[workdir]", "a work directory, or the folder you produced in")
+    .option(
+      "--text <headline>",
+      `banner headline. Capped at ${COVER_MAX_WORDS} words like produce's (§35), and the ` +
+        "trimmed result is printed. Omitted keeps the headline this cover already has",
+    )
+    .option(
+      "--at <seconds>",
+      "take the frame from this timestamp. Omitted re-uses the still the last cover was " +
+        "built from — the cheap path, which runs no ffmpeg at all",
+    )
+    .option(
+      "--from <video>",
+      "which video --at reads: `final` (default) is the FINISHED render, so the frame " +
+        "carries the burned-in captions, graphics and watermark; `source` is the original " +
+        "take, framed the way produce framed it",
+      "final",
+    )
+    .option(
+      "--out <path>",
+      "write the JPEG here for THIS run only; a one-off destination that does not change " +
+        "where this project's cover lives (that stays where this workdir's last cover went, " +
+        "else <out>.cover.jpg)",
+    )
+    .action(async (workdir: string | undefined, opts) => {
+      const { parseCoverFlags, regenerateCover } = await import("./cover");
+      // Parsed before anything touches disk: a typo'd `--from finall` must be
+      // an error naming the flag, not a cover quietly rebuilt from the wrong
+      // video (the --source-fit rule above).
+      const flags = parseCoverFlags(opts);
+
+      // The `edit` action's ladder, literally the same one: produce writes
+      // into <video's folder>/.ossclip/<name>/, and `ossclip cover
+      // ~/Downloads/MyClips` has to find that nested run exactly as `edit`
+      // does. With no argument, the current directory is the target.
+      const target = await resolveWorkdirArgument(workdir ?? ".", "cover");
+
+      // A thin shell by design: every decision lives in regenerateCover, so
+      // the editor's /api/cover/regenerate is the same code and not a second
+      // spelling of it.
+      await regenerateCover(target, {
+        text: flags.text,
+        atSec: flags.atSec,
+        from: flags.from,
+        // Raw: `coverDestination` owns the tilde expansion and the cwd
+        // anchor, so there is one site applying `expandHome` to the user half.
+        outPath: flags.outPath,
+      });
+    });
+
   program
     .command("setup")
     .description(