ossclip 0.1.33 → 0.1.34

package/src/edit.ts

@@ -1,7 +1,7 @@
 import { spawn, type ChildProcess } from "node:child_process";
 import { createHash } from "node:crypto";
 import { createReadStream, existsSync, readFileSync, statSync } from "node:fs";
-import { copyFile, mkdir, readFile, readdir, rename, unlink, writeFile } from "node:fs/promises";
+import { copyFile, mkdir, readFile, readdir, rename, stat, unlink, writeFile } from "node:fs/promises";
 import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
 import { homedir } from "node:os";
 import { dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
@@ -17,10 +17,24 @@ import {
   type YoutubePack,
   ThumbnailConceptApprovedSchema,
   ThumbnailConceptSchema,
+  appendUsageRun,
   approvedOverlayText,
   buildThumbnailPrompt,
+  captionCap,
   captionForProvider,
+  checkDurationCaps,
   createPostizProvider,
+  createProvider,
+  encodeEta,
+  formatUsageLine,
+  generateCaptionRegen,
+  generateYoutubePack,
+  YOUTUBE_PROMPT_VERSION,
+  deliveryEncodePlan,
+  ensureDeliveryFile,
+  PLATFORM_DURATION_CAPS_SEC,
+  PLATFORM_SIZE_CAP_BYTES,
+  probe,
   alignRestamp,
   emptyOverrideDoc,
   extractAudioSpan,
@@ -38,8 +52,10 @@ import {
   SegmentSchema,
   spliceTranscript,
   TranscriptSchema,
+  ungroundedTokens,
   whisperPromptFor,
   wordsInSpan,
+  type ModelPrice,
   type Segment,
   thumbnailImageCacheName,
   type CoverProvenance,
@@ -51,7 +67,9 @@ import {
 // drags in @ossclip/core's process runner and llm-detect, worth deferring off
 // server startup — open.ts is node:child_process + node:path and pure command
 // building, with nothing to defer.
+import { loadEnvFiles } from "./env";
 import { revealInFileManager } from "./open";
+import { REVIEWED_SCENES_BASENAME, renderReplayArgs } from "./render-replay-args";
 // 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
@@ -81,7 +99,16 @@ import {
   type ResolvedPortrait,
 } from "./portrait-override";
 import { lastFlagValue, thumbnailPanelState } from "./thumbnail-panel";
-import { buildPublishPosts, publishConfigured, publishReceiptPath, readPublishReceipt } from "./publish";
+import { captionRegenProvider } from "./caption-regen-panel";
+import { binOnPath } from "./llm-detect";
+import {
+  attachDeliveryMedia,
+  buildPublishPosts,
+  publishConfigured,
+  publishReceiptPath,
+  readPublishReceipt,
+  sizeCapGroups,
+} from "./publish";
 
 /**
  * Where the built editor page lives (R18 §90b): `editor-dist/` inside this
@@ -353,6 +380,12 @@ export async function startEditServer(
       portrait?: unknown;
       thumbnailModel?: unknown;
       postizUrl?: string;
+      /** produce's config fallback for `--audience` — the on-demand pack
+       * generation reads it the same way (typeof, never truthiness). */
+      audience?: unknown;
+      /** The caption-regenerate spend report prices through the same table
+       * produce does — absent in a stub, the defaults apply. */
+      pricing?: Record<string, ModelPrice>;
     } & RetranscribeConfig;
     /** Env seam for the publish endpoints — tests inject their own so the
      * runner's real OSSCLIP_POSTIZ_API_KEY (or its absence) never decides a
@@ -361,10 +394,18 @@ export async function startEditServer(
     /** Fetch seam for the publish endpoints — tests stub Postiz instead of
      * needing an instance on the runner (createPostizProvider's fetchImpl). */
     publishFetch?: typeof fetch;
+    /** The publish endpoints' two ffmpeg-family shell-outs (the sliceAudio/
+     * runWhisper seam pattern) — tests stub a probe and a delivery encode
+     * instead of needing ffmpeg/ffprobe and a real render on the runner. */
+    probeVideo?: typeof probe;
+    ensureDelivery?: typeof ensureDeliveryFile;
     /** File-manager reveal seam (the `generateThumbnail` pattern) — tests
      * observe the revealed path instead of popping a real Finder/Explorer
      * window on the runner. */
     reveal?: (path: string) => void;
+    /** The caption-regenerate LLM seam (the `generateThumbnail` pattern for
+     * text): tests inject a fake provider factory and never touch a model. */
+    makeLlmProvider?: typeof createProvider;
     /**
      * The cover render seam, exactly like `generateThumbnail` above. Without
      * it `regenerateCover` lazily imports @ossclip/renderer and boots a
@@ -477,6 +518,38 @@ export async function startEditServer(
    * `coverBusy`'s rule with a second reason on top.
    */
   let retranscribeBusy = false;
+  /**
+   * One caption regeneration at a time (`/api/publish/regenerate`) — an LLM
+   * call costs money, and a double-click must not buy two. `thumbnailBusy`'s
+   * rule, its own flag: a caption rewrite must not block a thumbnail.
+   */
+  let captionRegenBusy = false;
+  /**
+   * One pack generation at a time (`/api/youtube/generate`) — an LLM call
+   * costs money, and a double-click must not buy two. `captionRegenBusy`'s
+   * rule, its own flag: generating the pack must not block a caption rewrite
+   * already in flight (they are different buttons in different panels).
+   */
+  let packGenBusy = false;
+  /**
+   * Where the in-flight publish is right now, for the panel's poll
+   * (2026-08-29): the POST runs the delivery encode synchronously — minutes
+   * of x264 behind one fetch — so `GET /api/publish/progress` reads this
+   * instead of the panel staring at a static button. Null whenever no publish
+   * is in flight; a POST's `finally` owns the reset so an error can't leave a
+   * stale "encoding" behind. Per server instance like the busy flags above.
+   */
+  let publishProgress: {
+    phase: "encoding" | "uploading";
+    pct: number | null;
+    etaSec: number | null;
+    speed: number | null;
+    /** The delivery file being encoded (from onStart) — a size-capped
+     * publish runs two sequential encodes, and a bare pct that resets to 0
+     * mid-publish looks like a hang unless the label names which file it
+     * restarted for. Null before the first onStart and while uploading. */
+    file: string | null;
+  } | null = null;
   /** 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
@@ -531,6 +604,33 @@ export async function startEditServer(
   // panel round-trips through youtube-pack-approved.json, which produce's Y2
   // block honors VERBATIM on every replay — an edit persisted there survives
   // into future renders with zero new plumbing.
+  /**
+   * The publish config, resolved FRESH per request — both halves of it.
+   *
+   * `loadConfig()` already re-read `config.json` every time, but the API key
+   * came from the process env, which is populated once at CLI startup: a user
+   * who set up Postiz while the editor was open got "not configured" until a
+   * restart, with `postizUrl` live and the key stale (2026-08-27). Re-running
+   * `loadEnvFiles` costs two small file reads on a button press and keeps the
+   * documented precedence exactly — it never clobbers a key the real
+   * environment already set, so a shell-provided key still wins.
+   *
+   * Skipped entirely when the caller injected `publishEnv` (tests own their
+   * environment, and reading the developer's real `~/.ossclip/.env` into a
+   * test would make the suite depend on the machine it runs on).
+   */
+  const resolvePublishConfig = (): ReturnType<typeof publishConfigured> => {
+    if (opts.publishEnv === undefined) loadEnvFiles();
+    return publishConfigured((opts.loadCfg ?? loadConfig)(), opts.publishEnv ?? process.env);
+  };
+  /** ffmpeg/ffprobe for the publish endpoints' probe + delivery encode —
+   * from the same config read the rest of the panel resolves through. The
+   * `?? "ffmpeg"` legs exist only for the narrowed `loadCfg` seam; the real
+   * `loadConfig()` always fills both. */
+  const publishTools = (): { ffmpegPath: string; ffprobePath: string } => {
+    const cfg = (opts.loadCfg ?? loadConfig)();
+    return { ffmpegPath: cfg.ffmpegPath ?? "ffmpeg", ffprobePath: cfg.ffprobePath ?? "ffprobe" };
+  };
   const approvedPackPath = (): string => join(workdir!, YOUTUBE_APPROVED_BASENAME);
   /** The pack the panel shows: the approved file first (the user's
    * decision), else the newest valid `youtube-<key>.json` cache (what the
@@ -970,13 +1070,16 @@ export async function startEditServer(
           const chunks: Buffer[] = [];
           for await (const c of req) chunks.push(c as Buffer);
           let customOut: string | undefined;
+          let replan = false;
           try {
             const raw = Buffer.concat(chunks).toString();
             if (raw.trim()) {
-              const body = JSON.parse(raw) as { out?: string };
+              const body = JSON.parse(raw) as { out?: string; replan?: boolean };
               if (typeof body.out === "string" && body.out.trim()) {
                 customOut = body.out.trim();
               }
+              // Opt back into a fresh LLM plan (renderReplayArgs' why).
+              replan = body.replan === true;
             }
           } catch {
             // ignore
@@ -1031,6 +1134,30 @@ export async function startEditServer(
             filteredArgs.push("--out", customOut);
             args = filteredArgs;
           }
+          // THE EDITOR IS THE AUTHORITY for a render started here: pin the
+          // plan the user just reviewed (`production.json`'s scenes) instead
+          // of letting `--produce` plan a fresh one that renumbers scenes and
+          // orphans their edits (renderReplayArgs owns the full why). Written
+          // to its own file rather than reusing `scenes-<key>.json`, which is
+          // keyed to a beat sheet this render may no longer match.
+          let scenesPath: string | undefined;
+          if (!replan) {
+            try {
+              const production = JSON.parse(
+                await readFile(join(workdir!, "production.json"), "utf8"),
+              ) as { scenes?: unknown };
+              if (Array.isArray(production.scenes) && production.scenes.length > 0) {
+                scenesPath = join(workdir!, REVIEWED_SCENES_BASENAME);
+                await writeFile(scenesPath, `${JSON.stringify(production.scenes, null, 2)}\n`);
+              }
+            } catch {
+              // No production.json, an old one without `scenes`, or an
+              // unwritable workdir: replay the recorded command rather than
+              // refuse to render (renderReplayArgs' no-plan case).
+              scenesPath = undefined;
+            }
+          }
+          args = renderReplayArgs(args, { scenesPath, replan });
           renderLines = [];
           renderExit = null;
           renderStartedAt = Date.now();
@@ -1458,6 +1585,205 @@ export async function startEditServer(
           return send(200, { ok: true, mdPath });
         }
 
+        if (url.pathname === "/api/youtube/generate" && req.method === "POST") {
+          // Generate the pack ON DEMAND (2026-08-29): a render produced
+          // without --youtube has no caption pack, and the publish modal
+          // dead-ended on "run produce with --youtube" — a full re-produce
+          // just to buy one LLM call. This writes the same CACHE file
+          // produce's Y2 block would have, never the approved file: approval
+          // stays the user's explicit act (PUT /api/youtube), and the user
+          // still reviews the captions before anything sends.
+          if (!workdir) return send(409, { error: "no workdir open" });
+          // An LLM call costs money — one at a time, a second is a 409 like
+          // a second caption rewrite.
+          if (packGenBusy) {
+            return send(409, { error: "a caption-pack generation is already running" });
+          }
+          // Lenient transcript read but a 412 when it yields nothing — the
+          // /api/publish/regenerate posture, same reason: a pack with no
+          // transcript would be invented metadata. The words joined raw is
+          // the honest input the server has (regenerate made the same call);
+          // produce's stamped transcript needs the cut map, which only a
+          // produce run holds — the prompt tolerates plain text, the model
+          // just gets no measured chapters worth trusting.
+          let words: Array<{ text: string }> = [];
+          let lastWordEnd: number | null = null;
+          try {
+            const raw = JSON.parse(await readFile(join(workdir, "transcript.json"), "utf8")) as {
+              words?: unknown;
+            };
+            if (Array.isArray(raw.words)) {
+              words = raw.words.filter(
+                (w): w is { text: string } =>
+                  typeof (w as { text?: unknown } | null)?.text === "string",
+              );
+              for (const w of raw.words) {
+                const end = (w as { end?: unknown } | null)?.end;
+                if (typeof end === "number" && Number.isFinite(end)) {
+                  lastWordEnd = Math.max(lastWordEnd ?? 0, end);
+                }
+              }
+            }
+          } catch {
+            // absent/corrupt → the 412 below
+          }
+          if (words.length === 0) {
+            return send(412, {
+              error:
+                "no transcript in this workdir — the pack would have nothing to ground " +
+                "against; re-run `ossclip produce`.",
+            });
+          }
+          // The prompt's runtime ceiling: the output duration produce
+          // measured (render-props.json), else the transcript's last word
+          // end — source-clock, but the honest number available, and a
+          // raw-text transcript gets no measured chapters anyway.
+          let durationSec: number | null = null;
+          try {
+            const props = JSON.parse(await readFile(propsPath(), "utf8")) as {
+              outputDurationSec?: unknown;
+            };
+            if (
+              typeof props.outputDurationSec === "number" &&
+              Number.isFinite(props.outputDurationSec) &&
+              props.outputDurationSec > 0
+            ) {
+              durationSec = props.outputDurationSec;
+            }
+          } catch {
+            // corrupt props — the transcript fallback below
+          }
+          if (durationSec === null && lastWordEnd !== null && lastWordEnd > 0) {
+            durationSec = lastWordEnd;
+          }
+          if (durationSec === null) {
+            return send(412, {
+              error: "cannot determine the video's duration — re-run `ossclip produce`.",
+            });
+          }
+          const cmd = await readCommandRecord();
+          const cfg = (opts.loadCfg ?? loadConfig)();
+          // The editorial steer produce would have used: the recorded flags
+          // first, then produce's own defaults when a flag is absent —
+          // intent has none, audience falls back to the config's `audience`
+          // (produce.ts's typed read: typeof, never truthiness).
+          const intent = lastFlagValue(cmd?.args ?? [], ["--intent"]);
+          const audience =
+            lastFlagValue(cmd?.args ?? [], ["--audience"]) ??
+            (typeof cfg.audience === "string" ? cfg.audience : undefined);
+          // hook/coverText come from the beat sheet in produce; a produce
+          // run that planned left its sheet cached in the workdir. The
+          // shipped cover headline (cover.json, possibly the user's own
+          // words) backstops coverText. All optional — buildYoutubePrompt
+          // omits absent lines, exactly as a no-beat-sheet produce does.
+          let hook: string | undefined;
+          let coverText: string | undefined;
+          const beatCache = await newestWorkdirFile(
+            (n) => n.startsWith("beatsheet-") && n.endsWith(".json"),
+          );
+          if (beatCache !== null) {
+            try {
+              const sheet = JSON.parse(await readFile(beatCache, "utf8")) as {
+                hook?: unknown;
+                coverText?: unknown;
+              };
+              if (typeof sheet.hook === "string" && sheet.hook.trim().length > 0) {
+                hook = sheet.hook;
+              }
+              if (typeof sheet.coverText === "string" && sheet.coverText.trim().length > 0) {
+                coverText = sheet.coverText;
+              }
+            } catch {
+              // a corrupt cache loses a steer line, never the generation
+            }
+          }
+          if (coverText === undefined) {
+            const provenance = await readCoverProvenance(workdir);
+            if (provenance !== null && provenance.text.trim().length > 0) {
+              coverText = provenance.text;
+            }
+          }
+          // Env fresh per press, then the caption regenerate's provider
+          // resolution verbatim — the same "which LLM does this project
+          // use" question with the same three-rung answer.
+          if (opts.publishEnv === undefined) loadEnvFiles();
+          const env = opts.publishEnv ?? process.env;
+          const usagePath = join(workdir, "usage.json");
+          let usageLog: unknown = null;
+          try {
+            usageLog = JSON.parse(await readFile(usagePath, "utf8"));
+          } catch {
+            // no log yet — the resolution falls through to the pin/detection
+          }
+          const resolved = captionRegenProvider({
+            usageLog,
+            commandArgs: cmd?.args ?? null,
+            env,
+            hasBin: (bin) => binOnPath(bin, env),
+          });
+          if (resolved.status === "unavailable") {
+            return send(412, { error: resolved.reason });
+          }
+          const provider = (opts.makeLlmProvider ?? createProvider)(resolved.provider);
+          packGenBusy = true;
+          try {
+            let pack: YoutubePack;
+            try {
+              pack = await generateYoutubePack(provider, {
+                transcriptText: words.map((w) => w.text).join(" "),
+                ...(intent !== undefined ? { intent } : {}),
+                ...(hook !== undefined ? { hook } : {}),
+                ...(coverText !== undefined ? { coverText } : {}),
+                ...(audience !== undefined ? { audience } : {}),
+                durationSec,
+              });
+            } catch (err) {
+              // 200 with ok:false, the caption regenerate's posture: a
+              // provider failure is a sentence the panel shows VERBATIM,
+              // never a dead 500. Nothing is cached (§106).
+              return send(200, { ok: false, error: err instanceof Error ? err.message : String(err) });
+            }
+            const pricing = cfg.pricing ?? {};
+            // The spend is real, so it survives the session — the caption
+            // regenerate's append, atomically.
+            const nextLog = appendUsageRun(
+              usageLog,
+              { at: new Date().toISOString(), records: provider.usage },
+              pricing,
+            );
+            const usageTmp = `${usagePath}.tmp`;
+            await writeFile(usageTmp, JSON.stringify(nextLog, null, 2));
+            await rename(usageTmp, usagePath);
+            // A `youtube-<key>.json` cache, keyed on the provider asked like
+            // produce's Y2 write — deliberately NOT produce's exact key: that
+            // key hashes the cut map's spans and the stamped transcript,
+            // which only a produce run holds, and matching it would falsely
+            // claim cache identity with an answer built from different
+            // inputs. mtime is what makes this pack current: both
+            // currentYoutubePack and loadPublishPack sort caches newest
+            // first. Atomic like the approved-pack write.
+            const key = createHash("sha1")
+              .update(
+                JSON.stringify([
+                  YOUTUBE_PROMPT_VERSION,
+                  resolved.provider,
+                  intent ?? "",
+                  audience ?? "",
+                  words.map((w) => w.text),
+                ]),
+              )
+              .digest("hex")
+              .slice(0, 8);
+            const packPath = join(workdir, `youtube-${key}.json`);
+            const packTmp = `${packPath}.tmp`;
+            await writeFile(packTmp, JSON.stringify(pack, null, 2));
+            await rename(packTmp, packPath);
+            return send(200, { ok: true, usage: formatUsageLine(provider.usage, pricing) });
+          } finally {
+            packGenBusy = false;
+          }
+        }
+
         // ---- Publish (2026-08-26) -----------------------------------------
         // The server's FIRST outbound-network endpoints, against the
         // roadmap's "replay-only by deliberate design" posture — allowed
@@ -1468,14 +1794,33 @@ export async function startEditServer(
         // in the user's shell env) does the upload.
         if (url.pathname === "/api/publish" && req.method === "GET") {
           if (!workdir) return send(409, { error: "no workdir open" });
-          const configured = publishConfigured((opts.loadCfg ?? loadConfig)(), opts.publishEnv ?? process.env);
+          const configured = resolvePublishConfig();
           if (!configured.ok) {
             return send(200, { configured: false, reason: configured.message });
           }
           const cmd = await readCommandRecord();
           const out = cmd ? recordedOutPath(cmd) : null;
           const pack = await currentYoutubePack();
-          let integrations: Array<{ id: string; provider: string; name: string; caption: string }> = [];
+          // Pre-flight duration for the panel, read leniently (the
+          // /api/cleanup posture): a missing ffprobe or an unreadable render
+          // degrades to null — the panel loses the gray-out, never the modal —
+          // and POST re-checks the caps authoritatively anyway.
+          let durationSec: number | null = null;
+          if (out !== null && existsSync(out)) {
+            try {
+              durationSec = (await (opts.probeVideo ?? probe)(publishTools(), out)).duration;
+            } catch {
+              // degrade — the caps still apply server-side on POST
+            }
+          }
+          let integrations: Array<{
+            id: string;
+            provider: string;
+            name: string;
+            caption: string;
+            durationCapSec: number | null;
+            sizeCapBytes: number | null;
+          }> = [];
           try {
             const provider = createPostizProvider({
               baseUrl: configured.baseUrl,
@@ -1488,6 +1833,13 @@ export async function startEditServer(
               // The caption the publish WOULD use — authored-else-derived —
               // so the panel previews truth, not a guess of it.
               caption: pack !== null ? captionForProvider(pack, t.provider) : "",
+              // Null = no cap (limits.ts: absence means unlimited) — the
+              // panel grays out a channel only against a cap that exists.
+              durationCapSec: PLATFORM_DURATION_CAPS_SEC[t.provider] ?? null,
+              // The platform's upload byte ceiling, same posture: null means
+              // uncapped, a number means this channel gets its own smaller
+              // delivery encode (limits.ts: Instagram's ~100MB URL-fetch cap).
+              sizeCapBytes: PLATFORM_SIZE_CAP_BYTES[t.provider] ?? null,
             }));
           } catch (err) {
             return send(200, {
@@ -1502,13 +1854,14 @@ export async function startEditServer(
             integrations,
             packAvailable: pack !== null,
             outPathExists: out !== null && existsSync(out),
+            durationSec,
             receipt: await readPublishReceipt(workdir),
           });
         }
 
         if (url.pathname === "/api/publish" && req.method === "POST") {
           if (!workdir) return send(409, { error: "no workdir open" });
-          const configured = publishConfigured((opts.loadCfg ?? loadConfig)(), opts.publishEnv ?? process.env);
+          const configured = resolvePublishConfig();
           if (!configured.ok) return send(412, { error: configured.message });
           const chunks: Buffer[] = [];
           for await (const c of req) chunks.push(c as Buffer);
@@ -1522,6 +1875,9 @@ export async function startEditServer(
               // ids fall back to the pack's authored-else-derived caption.
               captions: z.record(z.string(), z.string()).optional(),
               force: z.boolean().optional(),
+              // What uploads (the CLI's --delivery): auto (default) builds
+              // the cached delivery encode, master sends the untouched render.
+              delivery: z.enum(["auto", "master"]).optional(),
             })
             .safeParse(JSON.parse(Buffer.concat(chunks).toString() || "{}"));
           if (!parsed.success) return send(400, { error: parsed.error.message });
@@ -1555,23 +1911,290 @@ export async function startEditServer(
               fetchImpl: opts.publishFetch,
             });
             const targets = await provider.listTargets();
-            const picked = parsed.data.integrationIds.map((id) => {
+            let picked = parsed.data.integrationIds.map((id) => {
               const hit = targets.find((t) => t.id === id);
               if (!hit) throw new Error(`no integration with id "${id}" in Postiz`);
               return hit;
             });
+            // Same core helpers, same semantics as the CLI (checkDurationCaps
+            // + ensureDeliveryFile — one spelling of the rules): drop the
+            // channels this video can never land on, publish the rest, and
+            // only when EVERY pick is over its cap refuse the whole request.
+            const tools = publishTools();
+            const masterProbe = await (opts.probeVideo ?? probe)(tools, out);
+            const violations = checkDurationCaps(picked, masterProbe.duration);
+            // Duration entries keep their original shape; size entries carry
+            // a `reason` and the cap that doomed them — additive fields only,
+            // so an older panel reading `dropped` keeps working.
+            const dropped: Array<Record<string, unknown>> = violations.map((v) => ({
+              id: v.target.id,
+              provider: v.target.provider,
+              name: v.target.name,
+              capSec: v.capSec,
+            }));
+            if (violations.length > 0) {
+              const over = new Set(violations.map((v) => v.target.id));
+              picked = picked.filter((t) => !over.has(t.id));
+              if (picked.length === 0) {
+                return send(412, {
+                  error:
+                    `every picked channel refuses a ${Math.round(masterProbe.duration)}s video — ` +
+                    "nothing to publish",
+                  dropped,
+                });
+              }
+            }
+            // Size-cap pre-check with the pure plan (the CLI's semantics,
+            // one spelling): an unattainable cap drops the channel BEFORE
+            // any encode — ensureDeliveryFile THROWS on unattainable, and a
+            // 502 with ffmpeg arithmetic in it is not a drop-and-continue.
+            const masterSizeBytes = (await stat(out)).size;
+            const src = {
+              width: masterProbe.width,
+              height: masterProbe.height,
+              fps: masterProbe.fps,
+              duration: masterProbe.duration,
+              sizeBytes: masterSizeBytes,
+            };
+            let capGroups = sizeCapGroups(picked);
+            if (parsed.data.delivery !== "master") {
+              for (const [capBytes, group] of capGroups) {
+                const capped = deliveryEncodePlan(src, { sizeCapBytes: capBytes });
+                if (capped !== null && "unattainable" in capped) {
+                  for (const t of group) {
+                    dropped.push({
+                      id: t.id,
+                      provider: t.provider,
+                      name: t.name,
+                      sizeCapBytes: capBytes,
+                      reason: "size",
+                    });
+                  }
+                  const over = new Set(group.map((t) => t.id));
+                  picked = picked.filter((t) => !over.has(t.id));
+                }
+              }
+              if (picked.length === 0) {
+                return send(412, {
+                  error:
+                    `every picked channel's size cap is unattainable for a ` +
+                    `${Math.round(masterProbe.duration)}s video — nothing to publish`,
+                  dropped,
+                });
+              }
+              capGroups = sizeCapGroups(picked);
+            }
             const posts = buildPublishPosts(pack, picked).map((p) => ({
               ...p,
               caption: parsed.data.captions?.[p.target.id] ?? p.caption,
             }));
-            const result = await provider.publish({ videoPath: out, posts, when });
+            // Synchronous encodes (~1–3 min each, fetch won't time out) — a
+            // job/poll model for the WORK is a noted follow-up, but the
+            // PROGRESS is polled: /api/publish/progress reads the state the
+            // onProgress callback below keeps current. Sequential per cap
+            // group (two ffmpegs racing for cores would slow both), so pct
+            // simply runs 0→100 once per file and `file` names which one.
+            let uploadPath = out;
+            const cappedPaths = new Map<number, string>();
+            if (parsed.data.delivery !== "master") {
+              // `workdir` is a mutable binding, so its non-null narrowing
+              // from the top of the handler doesn't survive into a closure —
+              // capture it while narrowed.
+              const wd = workdir;
+              const runEnsure = async (
+                sizeCapBytes?: number,
+              ): ReturnType<typeof ensureDeliveryFile> => {
+                let currentFile: string | null = null;
+                publishProgress = { phase: "encoding", pct: 0, etaSec: null, speed: null, file: null };
+                return (opts.ensureDelivery ?? ensureDeliveryFile)(tools, wd, out, {
+                  ...(sizeCapBytes !== undefined ? { sizeCapBytes } : {}),
+                  onStart: (name) => {
+                    currentFile = name;
+                    publishProgress = { phase: "encoding", pct: 0, etaSec: null, speed: null, file: name };
+                  },
+                  onProgress: (p) => {
+                    publishProgress = {
+                      phase: "encoding",
+                      // Percent against the MASTER's duration — the delivery
+                      // encode preserves it, so out_time maps 1:1.
+                      pct:
+                        p.outTimeSec !== undefined && masterProbe.duration > 0
+                          ? Math.min(
+                              100,
+                              Math.round((p.outTimeSec / masterProbe.duration) * 100),
+                            )
+                          : null,
+                      etaSec:
+                        p.outTimeSec !== undefined && p.speed !== undefined
+                          ? encodeEta(masterProbe.duration, p.outTimeSec, p.speed)
+                          : null,
+                      speed: p.speed ?? null,
+                      file: currentFile,
+                    };
+                  },
+                });
+              };
+              uploadPath = (await runEnsure()).path;
+              // One encode per DISTINCT cap — the bitrate-bearing filename is
+              // the cache key, so a capped plan that lands on the default
+              // file's name cache-hits instead of re-encoding.
+              for (const capBytes of capGroups.keys()) {
+                cappedPaths.set(capBytes, (await runEnsure(capBytes)).path);
+              }
+            }
+            // No upload ETA — Postiz's multipart upload gives us nothing to
+            // measure, so the phase alone is the signal.
+            publishProgress = { phase: "uploading", pct: null, etaSec: null, speed: null, file: null };
+            const result = await provider.publish({
+              videoPath: uploadPath,
+              posts: attachDeliveryMedia(posts, uploadPath, cappedPaths),
+              when,
+            });
             await writeFile(publishReceiptPath(workdir), `${JSON.stringify(result, null, 2)}\n`);
-            return send(200, { ok: true, receipt: result });
+            return send(200, { ok: true, receipt: result, dropped });
           } catch (err) {
             // Fail loud, verbatim — Postiz's own validation message is the
             // most specific thing anyone has (per-provider settings are its
             // domain, not ours).
             return send(502, { error: err instanceof Error ? err.message : String(err) });
+          } finally {
+            publishProgress = null;
+          }
+        }
+
+        if (url.pathname === "/api/publish/progress" && req.method === "GET") {
+          // Where the in-flight publish is — 200 always, `progress: null`
+          // when idle (a cache hit or a skip-plan publish never enters the
+          // encoding phase, and the panel keeps its static line for that).
+          return send(200, { progress: publishProgress });
+        }
+
+        if (url.pathname === "/api/publish/regenerate" && req.method === "POST") {
+          // Rewrite ONE network's caption with the LLM the produce run used
+          // (handoff 2026-08-29 item 4): the prompt carries the transcript,
+          // the caption AS THE PANEL HOLDS IT and the user's correction, and
+          // the replacement text rides back into the panel's box. Nothing
+          // auto-sends and nothing writes to the pack — the user still
+          // reviews, edits and presses Publish.
+          if (!workdir) return send(409, { error: "no workdir open" });
+          // An LLM call costs money — one at a time, a second is a 409 like
+          // a second thumbnail.
+          if (captionRegenBusy) {
+            return send(409, { error: "a caption regeneration is already running" });
+          }
+          const chunks: Buffer[] = [];
+          for await (const c of req) chunks.push(c as Buffer);
+          // `currentCaption` is deliberately the client's text — the ONE
+          // body-steered value beyond the ask itself, because the box may
+          // hold the user's manual edits and the model must see what the
+          // user sees. It steers only prompt text, never a path or a spawn.
+          const parsed = z
+            .object({
+              network: z.string().min(1),
+              instruction: z.string().min(1),
+              currentCaption: z.string(),
+            })
+            .safeParse(JSON.parse(Buffer.concat(chunks).toString() || "{}"));
+          if (!parsed.success) return send(400, { error: parsed.error.message });
+          // Lenient transcript read (the GET /api/transcript posture), but a
+          // 412 when it yields nothing: a rewrite with no transcript would be
+          // a rewrite with no factual evidence, which is the exact failure
+          // this endpoint exists to repair.
+          let transcript: { language: string; words: Array<{ text: string }> } | null = null;
+          try {
+            const raw = JSON.parse(await readFile(join(workdir, "transcript.json"), "utf8")) as {
+              language?: unknown;
+              words?: unknown;
+            };
+            if (Array.isArray(raw.words)) {
+              transcript = {
+                language: typeof raw.language === "string" ? raw.language : "en",
+                words: raw.words.filter(
+                  (w): w is { text: string } =>
+                    typeof (w as { text?: unknown } | null)?.text === "string",
+                ),
+              };
+            }
+          } catch {
+            // absent/corrupt → the 412 below
+          }
+          if (transcript === null || transcript.words.length === 0) {
+            return send(412, {
+              error:
+                "no transcript in this workdir — the rewrite would have nothing to " +
+                "ground against; re-run `ossclip produce`.",
+            });
+          }
+          // Env fresh per press, resolvePublishConfig's rule: a key set after
+          // startup must count. Skipped when tests own the environment.
+          if (opts.publishEnv === undefined) loadEnvFiles();
+          const env = opts.publishEnv ?? process.env;
+          const usagePath = join(workdir, "usage.json");
+          let usageLog: unknown = null;
+          try {
+            usageLog = JSON.parse(await readFile(usagePath, "utf8"));
+          } catch {
+            // no log yet — the resolution falls through to the pin/detection
+          }
+          const cmd = await readCommandRecord();
+          const resolved = captionRegenProvider({
+            usageLog,
+            commandArgs: cmd?.args ?? null,
+            env,
+            hasBin: (bin) => binOnPath(bin, env),
+          });
+          if (resolved.status === "unavailable") {
+            // Precondition, not a generation failure — 412 like a thumbnail
+            // regenerate on an unavailable project.
+            return send(412, { error: resolved.reason });
+          }
+          const provider = (opts.makeLlmProvider ?? createProvider)(resolved.provider);
+          captionRegenBusy = true;
+          try {
+            let caption: string;
+            try {
+              caption = await generateCaptionRegen(provider, {
+                network: parsed.data.network,
+                currentCaption: parsed.data.currentCaption,
+                instruction: parsed.data.instruction,
+                transcriptText: transcript.words.map((w) => w.text).join(" "),
+                charCap: captionCap(parsed.data.network),
+              });
+            } catch (err) {
+              // 200 with ok:false, the thumbnail regenerate's posture: a
+              // provider failure is a sentence the panel shows VERBATIM,
+              // never a dead 500.
+              return send(200, { ok: false, error: err instanceof Error ? err.message : String(err) });
+            }
+            const pricing = (opts.loadCfg ?? loadConfig)().pricing ?? {};
+            // The spend is real, so it survives the session: appended into
+            // the workdir's usage log the way produce appends its runs.
+            // Atomic like the overrides write — /api/usage may read it at
+            // any moment.
+            const nextLog = appendUsageRun(
+              usageLog,
+              { at: new Date().toISOString(), records: provider.usage },
+              pricing,
+            );
+            const tmp = `${usagePath}.tmp`;
+            await writeFile(tmp, JSON.stringify(nextLog, null, 2));
+            await rename(tmp, usagePath);
+            // Advisory ONLY, never a block: captions legitimately carry
+            // brand and platform words the take never speaks. The `--speaker`
+            // pin counts as spoken vocabulary for checkGrounding's §39
+            // reason — the channel name is in nearly every caption.
+            const speaker = lastFlagValue(cmd?.args ?? [], ["--speaker"]);
+            const notes = [...new Set(ungroundedTokens(caption, transcript, speaker))].map(
+              (token) => `⚠ grounding: "${token}" — not in the take`,
+            );
+            return send(200, {
+              ok: true,
+              caption,
+              usage: formatUsageLine(provider.usage, pricing),
+              notes,
+            });
+          } finally {
+            captionRegenBusy = false;
           }
         }